Fixed-width integer types, decimal numbers, and numeric parsing and encoding utilities. More...

Concepts
concept	sourcemeta::core::decimal_or_integral
concept	sourcemeta::core::any_decimal

Classes
class	sourcemeta::core::Decimal
class	sourcemeta::core::DecimalParseError
class	sourcemeta::core::NumericDivisionByZeroError
class	sourcemeta::core::NumericInvalidOperationError
class	sourcemeta::core::NumericOverflowError
class	sourcemeta::core::NumericOutOfRangeError
class	sourcemeta::core::NumericOutOfMemoryError
struct	sourcemeta::core::uint128_t

Functions
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_double (const std::string_view input) noexcept -> std::optional< double >
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_int64_t (const std::string_view input) noexcept -> std::optional< std::int64_t >
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_int64_t (const std::string_view input, const int base) noexcept -> std::optional< std::int64_t >
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_uint64_t (const std::string_view input) noexcept -> std::optional< std::uint64_t >
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_uint32_t (const std::string_view input) noexcept -> std::optional< std::uint32_t >
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_uint32_t (const std::string_view input, const int base) noexcept -> std::optional< std::uint32_t >
SOURCEMETA_CORE_NUMERIC_EXPORT auto	sourcemeta::core::to_uint16_t (const std::string_view input) noexcept -> std::optional< std::uint16_t >
template<typename T>
auto	sourcemeta::core::to_decimal (const T &value) -> Decimal
constexpr auto	sourcemeta::core::is_digit (const char character) -> bool
constexpr auto	sourcemeta::core::is_positive_digit (const char character) -> bool
template<typename T>
constexpr auto	sourcemeta::core::is_byte (const T &value) -> bool
template<typename Dividend, typename Divisor>
auto	sourcemeta::core::divide_floor (const Dividend &dividend, const Divisor &divisor)
template<typename Dividend, typename Divisor>
auto	sourcemeta::core::divide_ceil (const Dividend &dividend, const Divisor &divisor)
template<typename Minimum, typename Maximum, typename Multiplier>
auto	sourcemeta::core::count_multiples (const Minimum &minimum, const Maximum &maximum, const Multiplier &multiplier)
template<typename T>
constexpr auto	sourcemeta::core::is_within (const T &value, const std::int64_t lower, const std::int64_t higher) noexcept -> bool
template<typename T>
constexpr auto	sourcemeta::core::is_within (const T &value, const std::uint64_t lower, const std::uint64_t higher) noexcept -> bool
auto	sourcemeta::core::is_within (const Decimal &value, const Decimal &lower, const Decimal &higher) -> bool
template<typename T>
auto	sourcemeta::core::abs (const T &value)
constexpr auto	sourcemeta::core::closest_smallest_exponent (const std::uint64_t value, const std::uint8_t base, const std::uint8_t exponent_start, const std::uint8_t exponent_end) -> std::uint8_t
template<std::floating_point Real>
constexpr auto	sourcemeta::core::correct_ieee754 (const Real value) -> Real
template<std::integral Integer, std::floating_point Real>
constexpr auto	sourcemeta::core::real_digits (Real value, std::uint64_t &point_position) -> Integer
template<std::floating_point Real>
auto	sourcemeta::core::real_equal (const Real left, const Real right) -> bool
template<typename T>
auto	sourcemeta::core::zigzag_encode (const T &value)
template<typename T>
auto	sourcemeta::core::zigzag_decode (const T &value)

Variables
template<unsigned int T>
constexpr auto	sourcemeta::core::uint_max

Detailed Description

Fixed-width integer types, decimal numbers, and numeric parsing and encoding utilities.

This functionality is included as follows:

#include <sourcemeta/core/numeric.h>

Class Documentation

◆ sourcemeta::core::Decimal

class sourcemeta::core::Decimal

Represents an arbitrary-precision decimal number.

Public Member Functions
	Decimal () noexcept
	Construct a decimal number initialized to zero.
	~Decimal ()
	Destructor.
	Decimal (const Decimal &other)
	Copy constructor.
	Decimal (Decimal &&other) noexcept
	Move constructor.
template<typename T>
	Decimal (const T value)
	Construct a decimal number from a signed integral type.
	Decimal (std::int64_t value)
	Construct a decimal number from a 64-bit signed integer.
template<typename T>
	Decimal (const T value)
	Construct a decimal number from an unsigned integral type.
	Decimal (std::uint64_t value)
	Construct a decimal number from a 64-bit unsigned integer.
	Decimal (float value)
	Construct a decimal number from a 32-bit float.
	Decimal (double value)
	Construct a decimal number from a 64-bit double.
	Decimal (const char *const value)
	Construct a decimal number from a C-string.
	Decimal (const std::string &value)
	Construct a decimal number from a C++ string.
	Decimal (const std::string_view value)
	Construct a decimal number from a string view.
auto	to_scientific_string () const -> std::string
	Convert the decimal number to scientific notation string.
auto	to_string () const -> std::string
	Convert the decimal number to a plain string representation.
auto	to_int64 () const -> std::int64_t
	Convert the decimal number to a 64-bit signed integer.
auto	to_int32 () const -> std::int32_t
	Convert the decimal number to a 32-bit signed integer.
auto	to_uint64 () const -> std::uint64_t
	Convert the decimal number to a 64-bit unsigned integer.
auto	to_uint32 () const -> std::uint32_t
	Convert the decimal number to a 32-bit unsigned integer.
auto	to_float () const -> float
	Convert the decimal number to a 32-bit float.
auto	to_double () const -> double
	Convert the decimal number to a 64-bit double.
auto	is_zero () const -> bool
	Check if the decimal number is zero.
auto	is_integral () const -> bool
SOURCEMETA_FORCEINLINE auto	is_integer () const -> bool
SOURCEMETA_FORCEINLINE auto	is_finite () const -> bool
	Check if the decimal number is finite.
SOURCEMETA_FORCEINLINE auto	is_real () const -> bool
	Check if the decimal number is a real number (finite and not NaN).
auto	is_float () const -> bool
auto	is_double () const -> bool
auto	is_int32 () const -> bool
	Check if the decimal number fits in a 32-bit signed integer.
auto	is_int64 () const -> bool
	Check if the decimal number fits in a 64-bit signed integer.
auto	is_uint32 () const -> bool
	Check if the decimal number fits in a 32-bit unsigned integer.
auto	is_uint64 () const -> bool
	Check if the decimal number fits in a 64-bit unsigned integer.
SOURCEMETA_FORCEINLINE auto	is_nan () const -> bool
SOURCEMETA_FORCEINLINE auto	is_snan () const -> bool
	Check if the decimal number is a signaling NaN.
SOURCEMETA_FORCEINLINE auto	is_qnan () const -> bool
	Check if the decimal number is a quiet NaN.
SOURCEMETA_FORCEINLINE auto	nan_payload () const -> std::uint64_t
	Get the payload of a NaN value (0 if no payload).
SOURCEMETA_FORCEINLINE auto	is_infinite () const -> bool
	Check if the decimal number is infinite.
SOURCEMETA_FORCEINLINE auto	is_signed () const -> bool
	Check if the decimal number is signed (negative, including -0).
auto	to_integral () const -> Decimal
	Round the decimal number to an integral value.
auto	divisible_by (const Decimal &divisor) const -> bool
	Check if this decimal number is divisible by another.
auto	reduce () const -> Decimal
	Strip trailing zeros from the coefficient.
auto	logb () const -> Decimal
	Return the adjusted exponent (floor of base-10 logarithm).
auto	scale_by (const Decimal &scale) const -> Decimal
	Scale the number by a power of 10.
auto	same_quantum (const Decimal &other) const -> bool
	Check if two numbers have the same quantum (exponent).
auto	compare_total (const Decimal &other) const -> Decimal
	IEEE 754 total ordering comparison returning -1, 0, or 1.
auto	divide_integer (const Decimal &other) const -> Decimal
	Integer division (truncate toward zero).
Static Public Member Functions
static auto	nan (std::uint64_t payload=0) -> Decimal
	Create a quiet NaN (Not a Number) value with an optional payload.
static auto	snan (std::uint64_t payload=0) -> Decimal
	Create a signaling NaN value with an optional payload.
static auto	strict_from (double value) -> Decimal
static auto	exact_from (double value) -> Decimal
static auto	infinity () -> Decimal
	Create a positive infinity value.
static auto	negative_infinity () -> Decimal
	Create a negative infinity value.

Member Function Documentation

◆ exact_from()

auto sourcemeta::core::Decimal::exact_from ( double value ) -> Decimal

staticnodiscard

Create a decimal that preserves the exact value stored by a double, expanding every digit of its underlying binary representation

◆ is_double()

auto sourcemeta::core::Decimal::is_double ( ) const -> bool

nodiscard

Check if the decimal number can be represented as a 64-bit double without precision loss

◆ is_float()

auto sourcemeta::core::Decimal::is_float ( ) const -> bool

nodiscard

Check if the decimal number can be represented as a 32-bit float without precision loss

◆ is_integer()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::Decimal::is_integer ( ) const -> bool

inlinenodiscard

Check if the decimal number originated as an integer literal. Returns true iff the value was constructed from an integer-typed constructor or from a string source consisting of an optional sign followed by one or more digits, with no fractional part and no exponent part. Returns false for values constructed from floating-point primitives, from strings with a fractional or exponent part, or as the result of arithmetic operations.

◆ is_integral()

auto sourcemeta::core::Decimal::is_integral ( ) const -> bool

nodiscard

Check if the decimal number represents an integer value, which includes a number like 3.0. This is a value-level check: returns true whenever the number mathematically equals an integer, regardless of how it was originally written.

◆ is_nan()

SOURCEMETA_FORCEINLINE auto sourcemeta::core::Decimal::is_nan ( ) const -> bool

inlinenodiscard

Check if the decimal number is NaN (Not a Number), either quiet or signaling

◆ strict_from()

auto sourcemeta::core::Decimal::strict_from ( double value ) -> Decimal

staticnodiscard

Create a decimal from a double by converting through its shortest round-trip string representation, avoiding IEEE 754 precision artifacts

◆ sourcemeta::core::DecimalParseError

class sourcemeta::core::DecimalParseError

This class represents a decimal parse error

Inheritance diagram for sourcemeta::core::DecimalParseError:

◆ sourcemeta::core::NumericDivisionByZeroError

class sourcemeta::core::NumericDivisionByZeroError

This class represents a numeric division by zero error

Inheritance diagram for sourcemeta::core::NumericDivisionByZeroError:

◆ sourcemeta::core::NumericInvalidOperationError

class sourcemeta::core::NumericInvalidOperationError

This class represents a numeric invalid operation error

Inheritance diagram for sourcemeta::core::NumericInvalidOperationError:

◆ sourcemeta::core::NumericOverflowError

class sourcemeta::core::NumericOverflowError

This class represents a numeric overflow error

Inheritance diagram for sourcemeta::core::NumericOverflowError:

◆ sourcemeta::core::NumericOutOfRangeError

class sourcemeta::core::NumericOutOfRangeError

This class represents a numeric value that falls outside the range of the target type

Inheritance diagram for sourcemeta::core::NumericOutOfRangeError:

◆ sourcemeta::core::NumericOutOfMemoryError

class sourcemeta::core::NumericOutOfMemoryError

This class represents a numeric out of memory error

Inheritance diagram for sourcemeta::core::NumericOutOfMemoryError:

◆ sourcemeta::core::uint128_t

struct sourcemeta::core::uint128_t

Cross-platform 128-bit unsigned integer type.

Public Member Functions
constexpr	uint128_t (int value) noexcept
	Construct from a signed integer, sign-extending negative values.
constexpr	uint128_t (unsigned int value) noexcept
	Construct from an unsigned integer.
constexpr	uint128_t (std::uint64_t value) noexcept
	Construct from a 64-bit unsigned integer.
constexpr	uint128_t (std::int64_t value) noexcept
	Construct from a 64-bit signed integer, sign-extending negative values.
constexpr	uint128_t (std::uint64_t high_part, std::uint64_t low_part) noexcept
	Construct from separate upper and lower 64-bit halves.
Public Attributes
std::uint64_t	low
	The lower 64 bits of the value.
std::uint64_t	high
	The upper 64 bits of the value.

Function Documentation

◆ abs()

template<typename T>

auto sourcemeta::core::abs ( const T & value )

Compute the absolute value of an integer or Decimal

◆ closest_smallest_exponent()

auto sourcemeta::core::closest_smallest_exponent	(	const std::uint64_t	value,
		const std::uint8_t	base,
		const std::uint8_t	exponent_start,
		const std::uint8_t	exponent_end ) -> std::uint8_t

constexpr

Find the smallest exponent in [exponent_start, exponent_end] such that base raised to the next power exceeds the given value, i.e. (base ^ exponent) <= value < (base ^ (exponent + 1))

◆ correct_ieee754()

template<std::floating_point Real>

auto sourcemeta::core::correct_ieee754 ( const Real value ) -> Real

constexpr

Correct IEEE 754 floating-point imprecision by rounding values that are extremely close to the nearest integer

◆ count_multiples()

template<typename Minimum, typename Maximum, typename Multiplier>

auto sourcemeta::core::count_multiples	(	const Minimum &	minimum,
		const Maximum &	maximum,
		const Multiplier &	multiplier )

Count the number of multiples of a given multiplier that fall within the closed range [minimum, maximum]. Supports primitive integers, Decimal operands, and mixed combinations.

◆ divide_ceil()

template<typename Dividend, typename Divisor>

auto sourcemeta::core::divide_ceil	(	const Dividend &	dividend,
		const Divisor &	divisor )

Compute the ceiling of the division of two integral values. Supports primitive integers, Decimal operands, and mixed combinations.

◆ divide_floor()

template<typename Dividend, typename Divisor>

auto sourcemeta::core::divide_floor	(	const Dividend &	dividend,
		const Divisor &	divisor )

Compute the floor of the division of two integral values. Supports primitive integers, Decimal operands, and mixed combinations.

◆ is_byte()

template<typename T>

auto sourcemeta::core::is_byte ( const T & value ) -> bool

constexpr

Check whether a value fits in an unsigned 8-bit byte

◆ is_digit()

auto sourcemeta::core::is_digit ( const char character ) -> bool

inlineconstexpr

Check whether the given character is an ASCII decimal digit ('0'-'9'). For example:

#include <sourcemeta/core/numeric.h>
 
#include <cassert>
 
assert(sourcemeta::core::is_digit('0'));
assert(sourcemeta::core::is_digit('9'));
assert(!sourcemeta::core::is_digit('a'));
assert(!sourcemeta::core::is_digit(' '));

◆ is_positive_digit()

auto sourcemeta::core::is_positive_digit ( const char character ) -> bool

inlineconstexpr

Check whether the given character is a non-zero ASCII decimal digit ('1'-'9'). For example:

#include <sourcemeta/core/numeric.h>
 
#include <cassert>
 
assert(sourcemeta::core::is_positive_digit('1'));
assert(sourcemeta::core::is_positive_digit('9'));
assert(!sourcemeta::core::is_positive_digit('0'));
assert(!sourcemeta::core::is_positive_digit('a'));

◆ is_within() [1/3]

auto sourcemeta::core::is_within	(	const Decimal &	value,
		const Decimal &	lower,
		const Decimal &	higher ) -> bool

inline

Check whether a Decimal value falls within the closed range [lower, higher]

◆ is_within() [2/3]

template<typename T>

auto sourcemeta::core::is_within	(	const T &	value,
		const std::int64_t	lower,
		const std::int64_t	higher ) -> bool

constexprnoexcept

Check whether a value falls within the closed range [lower, higher] using signed 64-bit bounds

◆ is_within() [3/3]

template<typename T>

auto sourcemeta::core::is_within	(	const T &	value,
		const std::uint64_t	lower,
		const std::uint64_t	higher ) -> bool

constexprnoexcept

Check whether a value falls within the closed range [lower, higher] using unsigned 64-bit bounds

◆ real_digits()

template<std::integral Integer, std::floating_point Real>

auto sourcemeta::core::real_digits	(	Real	value,
		std::uint64_t &	point_position ) -> Integer

constexpr

Extract the integer digits and decimal point position from a floating-point value. The point_position output indicates how many digits from the right the decimal point sits.

◆ real_equal()

template<std::floating_point Real>

auto sourcemeta::core::real_equal	(	const Real	left,
		const Real	right ) -> bool

Compare two floating-point values for equality within a small tolerance of four units in the last place, which absorbs the rounding error a typical computation accumulates. A NaN is never equal to anything, and an infinity is equal only to the same infinity. For example:

#include <sourcemeta/core/numeric.h>
 
#include <cassert>
 
assert(sourcemeta::core::real_equal(0.1 + 0.2, 0.3));
assert(!sourcemeta::core::real_equal(1.0, 2.0));

◆ to_decimal()

template<typename T>

auto sourcemeta::core::to_decimal ( const T & value ) -> Decimal

Convert a value to a Decimal, returning a copy if it is already one

◆ to_double()

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_double ( const std::string_view input ) -> std::optional< double >

noexcept

Attempt to parse a string as a double

◆ to_int64_t() [1/2]

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_int64_t ( const std::string_view input ) -> std::optional< std::int64_t >

noexcept

Attempt to parse a string as a signed 64-bit integer

◆ to_int64_t() [2/2]

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_int64_t	(	const std::string_view	input,
		const int	base ) -> std::optional< std::int64_t >

noexcept

Attempt to parse a string as a signed 64-bit integer in a given base

◆ to_uint16_t()

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_uint16_t ( const std::string_view input ) -> std::optional< std::uint16_t >

noexcept

Attempt to parse a string as an unsigned 16-bit decimal integer

◆ to_uint32_t() [1/2]

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_uint32_t ( const std::string_view input ) -> std::optional< std::uint32_t >

noexcept

Attempt to parse a string as an unsigned 32-bit decimal integer

◆ to_uint32_t() [2/2]

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_uint32_t	(	const std::string_view	input,
		const int	base ) -> std::optional< std::uint32_t >

noexcept

Attempt to parse a string as an unsigned 32-bit integer in a given base

◆ to_uint64_t()

SOURCEMETA_CORE_NUMERIC_EXPORT auto sourcemeta::core::to_uint64_t ( const std::string_view input ) -> std::optional< std::uint64_t >

noexcept

Attempt to parse a string as an unsigned 64-bit decimal integer.

◆ zigzag_decode()

template<typename T>

auto sourcemeta::core::zigzag_decode ( const T & value )

Decode a zigzag-encoded unsigned integer back into a signed integer

◆ zigzag_encode()

template<typename T>

auto sourcemeta::core::zigzag_encode ( const T & value )

Encode a signed integer into an unsigned integer using zigzag encoding, where the sign information is stored in the least significant bit

Variable Documentation

◆ uint_max

template<unsigned int T>

auto sourcemeta::core::uint_max

constexpr

Initial value:

                        = []() -> std::uint64_t {
  static_assert(T > 0 && T < 64, "uint_max<T> requires 0 < T < 64");
  return (std::uint64_t{1} << T) - 1;
}()

The maximum value representable by an unsigned integer of T bits

Concepts

Classes

Functions

Variables

Detailed Description

Class Documentation

◆ sourcemeta::core::Decimal

Public Member Functions

Static Public Member Functions

Member Function Documentation

◆ exact_from()

◆ is_double()

◆ is_float()

◆ is_integer()

◆ is_integral()

◆ is_nan()

◆ strict_from()

◆ sourcemeta::core::DecimalParseError

◆ sourcemeta::core::NumericDivisionByZeroError

◆ sourcemeta::core::NumericInvalidOperationError

◆ sourcemeta::core::NumericOverflowError

◆ sourcemeta::core::NumericOutOfRangeError

◆ sourcemeta::core::NumericOutOfMemoryError

◆ sourcemeta::core::uint128_t

Public Member Functions

Public Attributes

Function Documentation

◆ abs()

◆ closest_smallest_exponent()

◆ correct_ieee754()

◆ count_multiples()

◆ divide_ceil()

◆ divide_floor()

◆ is_byte()

◆ is_digit()

◆ is_positive_digit()

◆ is_within() [1/3]

◆ is_within() [2/3]

◆ is_within() [3/3]

◆ real_digits()

◆ real_equal()

◆ to_decimal()

◆ to_double()

◆ to_int64_t() [1/2]

◆ to_int64_t() [2/2]

◆ to_uint16_t()

◆ to_uint32_t() [1/2]

◆ to_uint32_t() [2/2]

◆ to_uint64_t()

◆ zigzag_decode()

◆ zigzag_encode()

Variable Documentation

◆ uint_max