Provides additional utility functionality used by multiple modules. More...

Collaboration diagram for Utility:

Modules
	Bloom Filter
	Provides seqan3:bloom_filter.

	Builtin Character Operations
	Provides various operations on character types.

	Concept
	Provides various general purpose concepts.

	Container
	Provides various general purpose container and concepts.

	Parallel
	This module contains types and utilities for concurrent execution of algorithms in SeqAn.

	Range
	The range module provides general purpose range concepts.

	SIMD
	The simd module contains a unified interface to provide simd types and functions used in seqan3.

	Tuple
	Additional helper utilities for "tuple" types like std::tuple, std::pair, seqan3::pod_tuple that are not specific to a SeqAn module.

	Type List
	Provides seqan3::type_list and metaprogramming utilities for working on type lists.

	Type Pack
	Provides metaprogramming utilities for working on template parameter packs.

	Type Traits
	Provides various type traits and their shortcuts.

	Views
	Views are "lazy range combinators" that offer modified views onto other ranges.

Classes
struct	seqan3::detail::multi_invocable< invocable_ts >
	A type that can conveniently inherit multiple invocables and acts as a union over them. More...

Typedefs
template<uint64_t value>
using	seqan3::detail::min_viable_uint_t = std::conditional_t< value<=1ull, bool, std::conditional_t< value<=255ull, uint8_t, std::conditional_t< value<=65535ull, uint16_t, std::conditional_t< value<=4 '294 '967 '295ull, uint32_t, uint64_t > > > >
	Given a value, return the smallest unsigned integer that can hold it.

Functions
template<std::unsigned_integral unsigned_t>
constexpr unsigned_t	seqan3::detail::ceil_log2 (unsigned_t const n) noexcept
	Computes the ceil of the logarithm to the base of two for unsigned integers.

template<std::unsigned_integral unsigned_t>
constexpr unsigned_t	seqan3::detail::floor_log2 (unsigned_t const n) noexcept
	Computes the floor of the logarithm to the base of two for unsigned integers.

template<typename base_t , std::unsigned_integral exp_t> requires (std::same_as<base_t, uint64_t> \|\| std::same_as<base_t, int64_t>)
base_t	seqan3::pow (base_t base, exp_t exp)
	Computes the value of `base` raised to the power `exp`.

template<std::integral type>
constexpr type	seqan3::detail::to_little_endian (type const in) noexcept
	Convert the byte encoding of integer values to little-endian byte order.

Variables
template<typename type_t >
constexpr auto	seqan3::detail::bits_of = min_viable_uint_v<CHAR_BIT * sizeof(type_t)>
	How many bits has a type?

template<uint64_t value>
constexpr auto	seqan3::detail::min_viable_uint_v = static_cast<min_viable_uint_t<value>>(value)
	Given a value, cast the value as the smallest unsigned integer that can hold it.

template<typename int_t >
constexpr size_t	seqan3::detail::size_in_values_v
	Return the number of values an integral type can have, i.e. the difference between min and max.

template<typename type >
std::string const	seqan3::detail::type_name_as_string
	Defines the human-readable name of the given type using the typeid operator.

Detailed Description

Provides additional utility functionality used by multiple modules.

The utility module contains concepts, functions, traits and classes that are independent of the remaining modules in SeqAn. These implementations are considered external functionality, i.e. they could have been outsourced into their own libraries.

The utility module has no dependency to any other module except the Core module.

Function Documentation

◆ ceil_log2()

template<std::unsigned_integral unsigned_t>

constexpr unsigned_t seqan3::detail::ceil_log2 ( unsigned_t const n )

constexprnoexcept

Computes the ceil of the logarithm to the base of two for unsigned integers.

Parameters

[in] n An unsigned integer.

Attention: n = 0 is a special case and is undefined.

Returns: \( \lceil log_2(n) \rceil \).

The difference to std::ceil(std::log2(n)) is that everything is computed exactly (without precision loss due to promoting to double)

Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/math.hpp>
 
int main()
{
    // the same as std::ceil(std::log2(x)), but exact for unsigned integers
    seqan3::debug_stream << "ceil_log2(2^0 + 0): " << seqan3::detail::ceil_log2(1u) << '\n'; // 0u
    seqan3::debug_stream << "ceil_log2(2^1 + 0): " << seqan3::detail::ceil_log2(2u) << '\n'; // 1u
    seqan3::debug_stream << "ceil_log2(2^1 + 1): " << seqan3::detail::ceil_log2(3u) << '\n'; // 2u
    seqan3::debug_stream << "ceil_log2(2^2 + 0): " << seqan3::detail::ceil_log2(4u) << '\n'; // 2u
    seqan3::debug_stream << "ceil_log2(2^2 + 1): " << seqan3::detail::ceil_log2(5u) << '\n'; // 3u
    seqan3::debug_stream << "ceil_log2(2^2 + 2): " << seqan3::detail::ceil_log2(6u) << '\n'; // 3u
    seqan3::debug_stream << "ceil_log2(2^2 + 3): " << seqan3::detail::ceil_log2(7u) << '\n'; // 3u
    seqan3::debug_stream << "ceil_log2(2^3 + 0): " << seqan3::detail::ceil_log2(8u) << '\n'; // 3u
    seqan3::debug_stream << "ceil_log2(2^3 + 1): " << seqan3::detail::ceil_log2(9u) << '\n'; // 4u
 
    return 0;
}

Exception

No-throw guarantee.

Thread-safety

Thread safe.

Complexity

Constant.

◆ floor_log2()

template<std::unsigned_integral unsigned_t>

constexpr unsigned_t seqan3::detail::floor_log2 ( unsigned_t const n )

constexprnoexcept

Computes the floor of the logarithm to the base of two for unsigned integers.

Parameters

[in] n An unsigned integer.

Attention: n = 0 is a special case and is undefined.

Returns: \( \lfloor log_2(n) \rfloor \).

The difference to std::floor(std::log2(n)) is that everything is computed exactly (without precision loss due to promoting to double)

Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/math.hpp>
 
int main()
{
    // the same as std::floor(std::log2(x)), but exact for unsigned integers
    seqan3::debug_stream << "floor_log2(2^0 + 0): " << seqan3::detail::floor_log2(1u) << '\n'; // 0u
    seqan3::debug_stream << "floor_log2(2^1 + 0): " << seqan3::detail::floor_log2(2u) << '\n'; // 1u
    seqan3::debug_stream << "floor_log2(2^1 + 1): " << seqan3::detail::floor_log2(3u) << '\n'; // 1u
    seqan3::debug_stream << "floor_log2(2^2 + 0): " << seqan3::detail::floor_log2(4u) << '\n'; // 2u
    seqan3::debug_stream << "floor_log2(2^2 + 1): " << seqan3::detail::floor_log2(5u) << '\n'; // 2u
    seqan3::debug_stream << "floor_log2(2^2 + 2): " << seqan3::detail::floor_log2(6u) << '\n'; // 2u
    seqan3::debug_stream << "floor_log2(2^2 + 3): " << seqan3::detail::floor_log2(7u) << '\n'; // 2u
    seqan3::debug_stream << "floor_log2(2^3 + 0): " << seqan3::detail::floor_log2(8u) << '\n'; // 3u
    seqan3::debug_stream << "floor_log2(2^3 + 1): " << seqan3::detail::floor_log2(9u) << '\n'; // 3u
 
    return 0;
}

Exception

No-throw guarantee.

Thread-safety

Thread safe.

Complexity

Constant.

◆ pow()

template<typename base_t , std::unsigned_integral exp_t>
requires (std::same_as<base_t, uint64_t> || std::same_as<base_t, int64_t>)

base_t seqan3::pow	(	base_t	base,
		exp_t	exp
	)

Computes the value of base raised to the power exp.

Parameters

[in]	base	The base to compute the power for.
[in]	exp	The power to raise `base` to.

Returns: \( base^{exp} \).

Exceptions

std::overflow_error	if an overflow occurs (Only in Debug build).
std::underflow_error	if an underflow occurs (Only in Debug build).

See also: https://en.cppreference.com/w/cpp/numeric/math/pow

The difference to std::pow is that the powers of an integer base are computed exact (without precision loss due to promoting to double) iff exp_t models std::unsigned_integral and

base_t models std::unsigned_integral (returns uint64_t)
base_t models std::integral, but not std::unsigned_integral (returns int64_t)

In all other cases the return value and type is equivalent to that of std::pow.

Example

// SPDX-FileCopyrightText: 2006-2025 Knut Reinert & Freie Universität Berlin
// SPDX-FileCopyrightText: 2016-2025 Knut Reinert & MPI für molekulare Genetik
// SPDX-License-Identifier: CC0-1.0
 
#include <seqan3/core/debug_stream.hpp>
#include <seqan3/utility/math.hpp>
 
int main()
{
    // Uses specialisation for signed integers.
    seqan3::debug_stream << seqan3::pow(2, 3u) << '\n';  // Prints 8
    seqan3::debug_stream << seqan3::pow(-2, 3u) << '\n'; // Prints -8
 
    // Uses specialisation for unsigned integers.
    seqan3::debug_stream << seqan3::pow(2u, 3u) << '\n'; // Prints 8
 
    // Uses `std::pow`.
    seqan3::debug_stream << seqan3::pow(2, 3) << '\n';   // Prints 8
    seqan3::debug_stream << seqan3::pow(2u, 3) << '\n';  // Prints 8
    seqan3::debug_stream << seqan3::pow(2.0, 3) << '\n'; // Prints 8
 
    // 5^25 should be 298023223876953125.
    seqan3::debug_stream << seqan3::pow(5u, 25u) << '\n';                     // Prints 298023223876953125
    seqan3::debug_stream << static_cast<uint64_t>(std::pow(5u, 25u)) << '\n'; // Prints 298023223876953152 (wrong!)
}

◆ to_little_endian()

template<std::integral type>

constexpr type seqan3::detail::to_little_endian ( type const in )

constexprnoexcept

Convert the byte encoding of integer values to little-endian byte order.

Template Parameters

type	The type of the value to convert; must model std::integral.

Parameters

in	The input value to convert.

Returns: the converted value in little-endian byte-order.

This function swaps the bytes if the host system uses big endian. In this case only 1, 2, 4, or 8 byte big integral types are allowed as input. On host systems with little endian this function is a no-op and returns the unchanged input value. Other systems with mixed endianness are not supported.

Variable Documentation

◆ bits_of

template<typename type_t >

constexpr auto seqan3::detail::bits_of = min_viable_uint_v<CHAR_BIT * sizeof(type_t)>

constexpr

How many bits has a type?

Template Parameters

type_t The type to determine the number of bits.

◆ min_viable_uint_v

template<uint64_t value>

constexpr auto seqan3::detail::min_viable_uint_v = static_cast<min_viable_uint_t<value>>(value)

constexpr

Given a value, cast the value as the smallest unsigned integer that can hold it.

See also: seqan3::min_viable_uint_t

◆ size_in_values_v

template<typename int_t >

constexpr size_t seqan3::detail::size_in_values_v

constexpr

Initial value:

=

static_cast<size_t>(std::numeric_limits<int_t>::max()) - std::numeric_limits<int_t>::lowest() + 1

std::numeric_limits::max

T max(T... args)

std::numeric_limits

Return the number of values an integral type can have, i.e. the difference between min and max.

◆ type_name_as_string

template<typename type >

std::string const seqan3::detail::type_name_as_string

inline

Defines the human-readable name of the given type using the typeid operator.

Template Parameters

type	The type to get the human-readable name for.

On gcc and clang std::type_info only returns a mangled name. The mangled name can be converted to human-readable form using implementation-specific API such as abi::__cxa_demangle. In other implementations the name returned is already human-readable.

Note: The returned name is implementation defined and might change between different tool chains.

Modules

Classes

Typedefs

Functions

Variables

Detailed Description

Function Documentation

◆ ceil_log2()

Example

Exception

Thread-safety

Complexity

◆ floor_log2()

Example

Exception

Thread-safety

Complexity

◆ pow()

Example

◆ to_little_endian()

Variable Documentation

◆ bits_of

◆ min_viable_uint_v

◆ size_in_values_v

◆ type_name_as_string