rll::u128 class final
#include <rll/u128.h>

128-bit unsigned integer.

u128 offers a comprehensive suite of operations and utilities for handling 128-bit unsigned integers. It supports basic arithmetic operations, bitwise logic, comparison operators, and specialized functions for advanced integer manipulation. The class is optimized for both space and time efficiency, ensuring minimal overhead and maximum performance.

The design of u128 is focused on ease of use and integration. It provides constructors for seamless conversion from built-in integer types, as well as explicit methods for converting to and from other numeric representations. The class also includes support for standard library features like hashing and optional values, enhancing its utility in a wide range of programming scenarios.

The implementation is based on algorithms from the .NET UInt128 structure, ensuring reliable and efficient operations.

Public types

enum class format { decimal = 0, octal, hexadecimal }
String formats available for u128.

Public static functions

static auto from_string(std::string const& str, format fmt = format::decimal) →  optional<u128> noexcept
Parses a string to a u128 instance.
template <typename T, size_t N>
static auto from_string(T const (&str)[N], format fmt = format::decimal) →  optional<u128> constexpr noexcept
Parses a string to a u128 instance.

Constructors, destructors, conversion operators

operator bool() const explicit constexpr noexcept
Checks if the u128 value is non-zero.
operator char() const explicit constexpr noexcept
operator double() const explicit noexcept
operator float() const explicit noexcept
operator int() const explicit constexpr noexcept
operator long() const explicit constexpr noexcept
operator long double() const explicit noexcept
operator long long() const explicit constexpr noexcept
operator short() const explicit constexpr noexcept
operator signed char() const explicit constexpr noexcept
operator ulonglong() const explicit constexpr noexcept
operator unsigned char() const explicit constexpr noexcept
operator unsigned int() const explicit constexpr noexcept
operator unsigned long() const explicit constexpr noexcept
operator unsigned short() const explicit constexpr noexcept
u128() defaulted constexpr noexcept
Default constructor.
u128(u128 const& other) defaulted constexpr noexcept
Copy constructor.
u128(u128&& other) defaulted constexpr noexcept
Move constructor.
u128(u64 upper, u64 lower) constexpr noexcept
Constructs a u128 instance from upper and lower parts.
u128(ulonglong const lower) constexpr noexcept
Constructs an u128 instance from an unsigned integer.
u128(unsigned long const lower) constexpr noexcept
Constructs a u128 instance from an unsigned integer.
u128(unsigned int const lower) constexpr noexcept
Constructs a u128 instance from an unsigned integer.
u128(unsigned short const lower) constexpr noexcept
Constructs a u128 instance from an unsigned integer.
u128(long long const lower) constexpr noexcept
Constructs a u128 instance from a signed integer.
u128(long const lower) constexpr noexcept
Constructs a u128 instance from a signed integer.
u128(int const lower) constexpr noexcept
Constructs a u128 instance from a signed integer.
u128(short const lower) constexpr noexcept
Constructs a u128 instance from a signed integer.
u128(double const value) explicit noexcept
Constructs a u128 instance from a floating-point value.
u128(long double value) explicit noexcept
Constructs a u128 instance from a floating-point value.
u128(float value) explicit noexcept
Constructs a u128 instance from a floating-point value.

Public functions

auto hash() const →  std::size_t noexcept
Computes the hash value of the u128 instance.
auto lower() const →  u64 constexpr noexcept
Retrieves the lower 64 bits of the u128 value.
auto operator!() const →  bool constexpr noexcept
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator!=(T lower) const →  bool constexpr noexcept
Inequality operator with an integral type.
auto operator!=(u128 const& other) const →  bool constexpr noexcept
auto operator%(u128 const& other) const →  u128 constexpr noexcept
auto operator%=(u128 const& other) →  u128& constexpr noexcept
auto operator&(u128 const& other) const →  u128 constexpr noexcept
auto operator&&(u128 const& other) const →  bool constexpr noexcept
auto operator&=(u128 const& other) →  u128& constexpr noexcept
auto operator*(u128 const& other) const →  u128 constexpr noexcept
auto operator*=(u128 const& other) →  u128& constexpr noexcept
auto operator+() const →  u128 constexpr noexcept
auto operator+(u128 const& other) const →  u128 constexpr noexcept
auto operator++() →  u128& constexpr noexcept
auto operator++(int) →  u128 constexpr noexcept
auto operator+=(u128 const& other) →  u128& constexpr noexcept
auto operator-() const →  u128 constexpr noexcept
auto operator-(u128 const& other) const →  u128 constexpr noexcept
auto operator--() →  u128& constexpr noexcept
auto operator--(int) →  u128 constexpr noexcept
auto operator-=(u128 const& other) →  u128& constexpr noexcept
auto operator/(u128 const& other) const →  u128 constexpr noexcept
auto operator/=(u128 const& other) →  u128& constexpr noexcept
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator<(T lower) const →  bool constexpr noexcept
Less than operator with an integral type.
auto operator<(u128 const& other) const →  bool constexpr noexcept
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator<<(T shift) const →  u128 constexpr noexcept
Bitwise left shift operator with an integral type.
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator<<=(T shift) →  u128& constexpr noexcept
Bitwise left shift assignment operator.
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator<=(T lower) const →  bool constexpr noexcept
Less than or equal to operator with an integral type.
auto operator<=(u128 const& other) const →  bool constexpr noexcept
auto operator=(u128 const& other) →  u128& defaulted constexpr noexcept
Assignment operator.
auto operator=(u128&& other) →  u128& defaulted constexpr noexcept
Move assignment operator.
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator==(T lower) const →  bool constexpr noexcept
auto operator==(u128 const& other) const →  bool constexpr noexcept
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator>(T lower) const →  bool constexpr noexcept
Greater than operator with an integral type.
auto operator>(u128 const& other) const →  bool constexpr noexcept
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator>=(T lower) const →  bool constexpr noexcept
Greater than or equal to operator with an integral type.
auto operator>=(u128 const& other) const →  bool constexpr noexcept
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator>>(T shift) const →  u128 constexpr noexcept
Bitwise right shift operator with an integral type.
template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
auto operator>>=(T shift) →  u128& constexpr noexcept
Bitwise right shift assignment operator.
auto operator^(u128 const& other) const →  u128 constexpr noexcept
auto operator^=(u128 const& other) →  u128& constexpr noexcept
auto operator|(u128 const& other) const →  u128 constexpr noexcept
auto operator|=(u128 const& other) →  u128& constexpr noexcept
auto operator||(u128 const& other) const →  bool constexpr noexcept
auto operator~() const →  u128 constexpr noexcept
void swap(u128& other) constexpr noexcept
Swaps the values of two u128 instances.
auto to_string(format fmt = format::decimal) const →  std::string
Converts the u128 value to a string representation.
auto upper() const →  u64 constexpr noexcept
Retrieves the upper 64 bits of the u128 value.

Enum documentation

enum class rll::u128::format

String formats available for u128.

This enumeration defines the possible string representations of u128 values. It allows users to specify the desired format when converting u128 instances to strings.

Enumerators
decimal

Represents the number in decimal format. This is the default format.
octal

Represents the number in octal format.
hexadecimal

Represents the number in hexadecimal format.

Function documentation

static optional<u128> rll::u128::from_string(std::string const& str, format fmt = format::decimal) noexcept

Parses a string to a u128 instance.

Parameters
str in The input string to parse.
fmt in The string format to interpret the input string (defaults to decimal).
Returns An optional containing the parsed u128 value if successful, otherwise an empty optional.

Attempts to parse a given string as a u128 value in the specified format. If the parsing is successful, it returns an optional containing the parsed u128 value.

template <typename T, size_t N>
static optional<u128> rll::u128::from_string(T const (&str)[N], format fmt = format::decimal) constexpr noexcept

Parses a string to a u128 instance.

Template parameters
T The character type of the array.
N The size of the character array.
Parameters
str in The input string to parse.
fmt in The string format to interpret the input string (defaults to decimal).
Returns An optional containing the parsed u128 value if successful, otherwise an empty optional.

This static method attempts to parse a given string as a u128 value in the specified format. If the parsing is successful, it returns an optional containing the parsed u128 value.

rll::u128::operator bool() const explicit constexpr noexcept

Checks if the u128 value is non-zero.

Returns true if the u128 value is non-zero, false otherwise.

This method allows u128 instances to be contextually converted to a boolean to check for non-zero values.

rll::u128::u128() defaulted constexpr noexcept

Default constructor.

Constructs a new u128 instance with default values.

rll::u128::u128(u128 const& other) defaulted constexpr noexcept

Copy constructor.

Parameters
other in The u128 instance to copy.

Constructs a new u128 instance by copying the value from another instance.

rll::u128::u128(u128&& other) defaulted constexpr noexcept

Move constructor.

Parameters
other in/out The u128 instance to move.

Constructs a new u128 instance by moving the value from another instance.

rll::u128::u128(u64 upper, u64 lower) constexpr noexcept

Constructs a u128 instance from upper and lower parts.

Parameters
upper in The upper 64 bits of the u128 value.
lower in The lower 64 bits of the u128 value.

This constructor initializes a u128 instance using separate upper and lower 64-bit integers.

rll::u128::u128(ulonglong const lower) constexpr noexcept

Constructs an u128 instance from an unsigned integer.

Parameters
lower in The unsigned integer to initialize the u128 instance with.

This constructor initializes a u128 instance using an unsigned integer, setting it as the lower part of the u128 value.

rll::u128::u128(unsigned long const lower) constexpr noexcept

Constructs a u128 instance from an unsigned integer.

Parameters
lower in The unsigned integer to initialize the u128 instance with.

This constructor initializes a u128 instance using an unsigned integer, setting it as the lower part of the u128 value.

rll::u128::u128(unsigned int const lower) constexpr noexcept

Constructs a u128 instance from an unsigned integer.

Parameters
lower in The unsigned integer to initialize the u128 instance with.

This constructor initializes a u128 instance using an unsigned integer, setting it as the lower part of the u128 value.

rll::u128::u128(unsigned short const lower) constexpr noexcept

Constructs a u128 instance from an unsigned integer.

Parameters
lower in The unsigned integer to initialize the u128 instance with.

This constructor initializes a u128 instance using an unsigned integer, setting it as the lower part of the u128 value.

rll::u128::u128(long long const lower) constexpr noexcept

Constructs a u128 instance from a signed integer.

Parameters
lower in The signed integer to initialize the u128 instance with.

This constructor initializes a u128 instance using a signed integer, setting it as the lower part of the u128 value and extending the sign to the upper part.

rll::u128::u128(long const lower) constexpr noexcept

Constructs a u128 instance from a signed integer.

Parameters
lower in The signed integer to initialize the u128 instance with.

This constructor initializes a u128 instance using a signed integer, setting it as the lower part of the u128 value and extending the sign to the upper part.

rll::u128::u128(int const lower) constexpr noexcept

Constructs a u128 instance from a signed integer.

Parameters
lower in The signed integer to initialize the u128 instance with.

This constructor initializes a u128 instance using a signed integer, setting it as the lower part of the u128 value and extending the sign to the upper part.

rll::u128::u128(short const lower) constexpr noexcept

Constructs a u128 instance from a signed integer.

Parameters
lower in The signed integer to initialize the u128 instance with.

This constructor initializes a u128 instance using a signed integer, setting it as the lower part of the u128 value and extending the sign to the upper part.

rll::u128::u128(double const value) explicit noexcept

Constructs a u128 instance from a floating-point value.

Parameters
value in The floating-point value to convert.

This constructor initializes a u128 instance by converting a floating-point value to its 128-bit unsigned integer representation. The conversion is explicit to prevent unintended implicit conversions.

rll::u128::u128(long double value) explicit noexcept

Constructs a u128 instance from a floating-point value.

Parameters
value in The floating-point value to convert.

This constructor initializes a u128 instance by converting a floating-point value to its 128-bit unsigned integer representation. The conversion is explicit to prevent unintended implicit conversions.

rll::u128::u128(float value) explicit noexcept

Constructs a u128 instance from a floating-point value.

Parameters
value in The floating-point value to convert.

This constructor initializes a u128 instance by converting a floating-point value to its 128-bit unsigned integer representation. The conversion is explicit to prevent unintended implicit conversions.

u64 rll::u128::lower() const constexpr noexcept

Retrieves the lower 64 bits of the u128 value.

Returns The lower 64 bits as a u64.

This method returns the lower part of the u128 instance, allowing access to the least significant bits.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
bool rll::u128::operator!=(T lower) const constexpr noexcept

Inequality operator with an integral type.

Template parameters
T An integral type to compare with.
Parameters
lower in The integral value to compare with.
Returns true if this instance is not equal to the integral value, false otherwise.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
bool rll::u128::operator<(T lower) const constexpr noexcept

Less than operator with an integral type.

Template parameters
T An integral type to compare with.
Parameters
lower in The integral value to compare with.
Returns true if this instance is less than the integral value, false otherwise.

Checks if the value of this instance is lexicographically less than the provided integral value.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
u128 rll::u128::operator<<(T shift) const constexpr noexcept

Bitwise left shift operator with an integral type.

Template parameters
T An integral type representing the number of places to shift.
Parameters
shift in The number of bits to shift to the left.
Returns A new u128 instance representing the result of the left shift operation.

Shifts the bits of this instance to the left by the specified number of places and returns a new u128 instance with the result.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
u128& rll::u128::operator<<=(T shift) constexpr noexcept

Bitwise left shift assignment operator.

Template parameters
T An integral type representing the number of places to shift.
Parameters
shift in The number of bits to shift to the left.
Returns A reference to this instance after the shift operation.

Shifts the bits of this instance to the left by the specified number of places and assigns the result to this instance.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
bool rll::u128::operator<=(T lower) const constexpr noexcept

Less than or equal to operator with an integral type.

Template parameters
T An integral type to compare with.
Parameters
lower in The integral value to compare with.
Returns true if this instance is less than or equal to the integral value, false otherwise.

Checks if the value of this instance is lexicographically less than or equal to the provided integral value.

u128& rll::u128::operator=(u128 const& other) defaulted constexpr noexcept

Assignment operator.

Parameters
other in The u128 instance to assign from.
Returns A reference to the assigned u128 instance.

Assigns the value of one u128 instance to another.

u128& rll::u128::operator=(u128&& other) defaulted constexpr noexcept

Move assignment operator.

Parameters
other in/out The u128 instance to move from.
Returns A reference to the moved u128 instance.

Moves the value of one u128 instance to another.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
bool rll::u128::operator>(T lower) const constexpr noexcept

Greater than operator with an integral type.

Template parameters
T An integral type to compare with.
Parameters
lower in The integral value to compare with.
Returns true if this instance is greater than the integral value, false otherwise.

Checks if the value of this instance is lexicographically greater than the provided integral value.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
bool rll::u128::operator>=(T lower) const constexpr noexcept

Greater than or equal to operator with an integral type.

Template parameters
T An integral type to compare with.
Parameters
lower in The integral value to compare with.
Returns true if this instance is greater than or equal to the integral value, false otherwise.

Checks if the value of this instance is lexicographically greater than or equal to the provided integral value.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
u128 rll::u128::operator>>(T shift) const constexpr noexcept

Bitwise right shift operator with an integral type.

Template parameters
T An integral type representing the number of places to shift.
Parameters
shift in The number of bits to shift to the right.
Returns A new u128 instance representing the result of the right shift operation.

Shifts the bits of this instance to the right by the specified number of places and returns a new u128 instance with the result.

template <typename T, typename = typename std::enable_if<std::is_integral<T>::value, T>::type>
u128& rll::u128::operator>>=(T shift) constexpr noexcept

Bitwise right shift assignment operator.

Template parameters
T An integral type representing the number of places to shift.
Parameters
shift in The number of bits to shift to the right.
Returns A reference to this instance after the shift operation.

Shifts the bits of this instance to the right by the specified number of places and assigns the result to this instance.

void rll::u128::swap(u128& other) constexpr noexcept

Swaps the values of two u128 instances.

Parameters
other in/out The other u128 instance to swap with.

std::string rll::u128::to_string(format fmt = format::decimal) const

Converts the u128 value to a string representation.

Parameters
fmt in The format to use for the conversion, with format::decimal as the default.
Returns A std::string holding the converted value.

Supports decimal, octal, and hexadecimal formats.

u64 rll::u128::upper() const constexpr noexcept

Retrieves the upper 64 bits of the u128 value.

Returns The upper 64 bits as a u64.

This method returns the upper part of the u128 instance, allowing access to the most significant bits.