UInt128 Structure

Represents a 128-bit unsigned integer.

Namespace: Meta.Numerics.Extended
Assembly: Meta.Numerics (in Meta.Numerics.dll) Version: 4.1.4

Syntax

public struct UInt128 : IEquatable<UInt128>, 
	IComparable<UInt128>

Public Structure UInt128
	Implements IEquatable(Of UInt128), IComparable(Of UInt128)

public value class UInt128 : IEquatable<UInt128>, 
	IComparable<UInt128>

[<SealedAttribute>]
type UInt128 =  
    struct
        interface IEquatable<UInt128>
        interface IComparable<UInt128>
    end

The UInt128 type exposes the following members.

Constructors

	Name	Description
	UInt128	Initializes a new 128-bit unsigned integer with the given base-10 representation.

Top

Methods

	Name	Description
	Compare	Compares two unsigned 128-bit integers.
	CompareTo	Compares the current instance to another unsigned 128-bit integer.
	DivRem(UInt128, UInt128, UInt128)	Computes the quotient and remaineder of two unsigned 128-bit integers.
	DivRem(UInt128, UInt32, UInt32)	Divides a 128-bit unsigned integer by a 32-bit unsigned integer.
	Equals(Object)	Tests whether the current instance is equal to another object. (Overrides ValueTypeEquals(Object).)
	Equals(UInt128)	Tests whether the current instance is equal to another unsigned 128-bit integer.
	Equals(UInt128, UInt128)	Tests whether two unsigned 128-bit integers are equal.
	GetHashCode	Gets a hash code for the current instance. (Overrides ValueTypeGetHashCode.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	Parse	Creates an unsigned 128-bit integer from its string representation.
	ToString	Produces a string representation of the unsigned 128-bit integer. (Overrides ValueTypeToString.)
	TryParse	Attempts to parse the given string as an unsigned 128-bit integer.

Top

Operators

	Name	Description
	Addition	Adds two 128-bit unsigned integers.
	BitwiseAnd	Computes the bitwise AND of two arguments.
	BitwiseOr	Computes the bitwise OR of two arguments.
	Decrement	Decrements a 128-bit unsigned integer.
	Division	Divides one 128-bit unsigned integer by another.
	Equality	Tests whether two unsigned 128-bit integers are equal.
	ExclusiveOr	Computes the bitwise XOR of two arguments.
	(Double to UInt128)	Converts a floating-point value into an unsigned 128-bit integer.
	(BigInteger to UInt128)	Converts an arbitrary-size big integer into an unsigned 128-bit integer.
	(UInt128 to UInt64)	Converts an unsigned 128-bit integer into an unsigned 64-bit integer.
	GreaterThan	Indicates whether the first value is greater than the second value.
	GreaterThanOrEqual	Indicates whether the first value is greater than or equal to the second value.
	(UInt64 to UInt128)	Converts an unsigned 64-bit integer to an unsigned 128-bit integer.
	(UInt128 to BigInteger)	Converts an unsigned 128-bit integer into an arbitrary-size big integer.
	(UInt128 to Double)	Converts an unsigned 128-bit integer into a floating point value.
	Increment	Increments a 128-bit unsigned integer.
	Inequality	Tests whether two unsigned 128-bit integers are unequal.
	LeftShift	Returns the unsigned 128-bit binary integer obtained by shifting all bits left by the given number of places.
	LessThan	Indicates whether the first value is less than the second value.
	LessThanOrEqual	Indicates whether the first value is less than or equal to the second value.
	Modulus	Computes the remainder when one 128-bit unsigned integer is divided by another.
	Multiply	Multiplies two 128-bit unsigned integers.
	OnesComplement	Computes the bitwise negation of the argument.
	RightShift	Returns the unsigned 128-bit binary integer obtained by shifting all bits right by the given number of places.
	Subtraction	Subtracts one 128 bit unsigned integer from another.

Top

Fields

	Name	Description
	MaxValue	The greatest representable unsigned 128-bit integer.
	MinValue	The least representable unsigned 128-bit integer.
	One	The unit value of the unsigned 128-bit integer.
	Zero	The zero value of the unsigned 128-bit integer.

Top

Remarks

The built-in unsigned integer types ushort, uint, and ulong are fixed-width registers with the characteristics shown below. UInt128 is a 128-bit unsigned integer register with analogous behavior and greatly extended range.

Type	C# Name	Width	MaxValue
UInt16	ushort	16b (2B)	~65 X 10³
UInt32	uint	32b (4B)	~4.2 X 10⁹
UInt64	ulong	64b (8B)	~18 X 10¹⁸
UInt128	UInt128	128b (16B)	~3.4 X 10³⁸

To instantiate a 128-bit unsigned integer, you can use the constructor UInt128(String), or the parsing methods Parse(String) or TryParse(String, UInt128) to parse a decimal representation provided as a string. The parsing then occurs at run-time. If the value you want is representable by a built-in unsigned integer type (e.g. UInt64), you can simply assign a UInt128 variable from a built-in integer type. This is particularly useful in source code, since the compiler will parse fixed values of these types at compile-time.

Operations that overflow and underflow UInt128 behave like they do for the native unsigned integer types, with results modulo 2¹²⁸, or wrapping around from MaxValue to Zero.

Explicit casts between UInt128 and the built-in integer types behave like unchecked explicit casts between the built-in integer types: the low-order bits of the binary representation are preserved and the high-order bits are, if necessary, discarded. This preserves values that are representable by the target type, but values that are not representable by the target type may be transformed in ways that, while correct in terms of the bit-level rules, are unexpected in terms of numerical values. While this is like the behavior of the built-in integer types, it is different than the behavior of BigInteger, which performs casts as if checked, throwing an exception if the value is not representable in the target type. If you want checked behavior, your code must explicitly check whether the value is in the range of the target before casting.

If you know that the numbers you need to work with all fit in a 128 bit unsigned register, arithmetic with UInt128 is typically significantly faster than with BigInteger. Addition and subtraction are about six times faster, multiplication is about twice as fast, and division is about 50% faster.

UInt128 also supports bitwise logical and shift operations.

Reference

Meta.Numerics.Extended Namespace