UInt24

UInt24 is a 24-bit unsigned integer value type provided by the library. It fills the gap between ushort (16-bit) and uint (32-bit), and is the type returned by all GetUInt24 methods and accepted by all SetUInt24 methods.

Range and Constants

A UInt24 can represent integers from 0 to 16,777,215 (2²⁴ − 1).

Constant	Value
`UInt24.MinValue`	0
`UInt24.MaxValue`	16,777,215
`UInt24.Zero`	0
`UInt24.One`	1
`UInt24.AdditiveIdentity`	0
`UInt24.MultiplicativeIdentity`	1

Numeric Interfaces

UInt24 implements the standard .NET generic math interfaces, giving it full interoperability with generic algorithms:

Conversions

Implicit Widening Conversions

The following conversions are implicit (no cast required) because the target type can always represent every UInt24 value:

Direction	Notes
`byte` → `UInt24`	0..255 always fits
`ushort` → `UInt24`	0..65,535 always fits
`UInt24` → `uint`	Always safe, no data loss
`UInt24` → `int`	Always safe; result is non-negative
`UInt24` → `long`	Always safe
`UInt24` → `ulong`	Always safe

UInt24 a = (byte)255;      // implicit from byte
UInt24 b = (ushort)65535;  // implicit from ushort

uint  u = (UInt24)100;     // implicit to uint
int   i = (UInt24)100;     // implicit to int
long  l = (UInt24)100;     // implicit to long
ulong ul = (UInt24)100;    // implicit to ulong

Explicit Narrowing Conversions

Conversions that may overflow require an explicit cast. An OverflowException is thrown in the cases shown:

Direction	Throws `OverflowException` if…
`sbyte` → `UInt24`	value is negative
`short` → `UInt24`	value is negative
`int` → `UInt24`	value is negative or > 16,777,215
`uint` → `UInt24`	value > 16,777,215
`long` → `UInt24`	value is negative or > 16,777,215
`ulong` → `UInt24`	value > 16,777,215
`nint` → `UInt24`	value is negative or > 16,777,215
`nuint` → `UInt24`	value > 16,777,215
`Half` → `UInt24`	value is negative, NaN, or infinity
`float` → `UInt24`	value is negative, NaN, infinity, or > 16,777,215
`double` → `UInt24`	value is negative, NaN, infinity, or > 16,777,215
`decimal` → `UInt24`	value is negative or > 16,777,215
`UInt24` → `byte`	value > 255
`UInt24` → `sbyte`	value > 127
`UInt24` → `short`	value > 32,767
`UInt24` → `ushort`	value > 65,535

UInt24 x = (UInt24)16777215; // explicit from uint — OK
UInt24 y = (UInt24)16777216; // throws OverflowException

byte b = (byte)(UInt24)255;  // explicit to byte — OK
byte c = (byte)(UInt24)256;  // throws OverflowException

Generic Math — `CreateChecked`, `CreateSaturating`, `CreateTruncating`

UInt24 also supports the generic math conversion methods for use in generic algorithms:

UInt24 a = UInt24.CreateChecked<int>(100);     // 100 — throws if out of range
UInt24 b = UInt24.CreateSaturating<int>(-1);   // 0   — clamps to MinValue
UInt24 c = UInt24.CreateSaturating<int>(20_000_000); // 16,777,215 — clamps to MaxValue
UInt24 d = UInt24.CreateTruncating<uint>(0xFFFFFFFF); // 0xFFFFFF — keeps low 24 bits

Arithmetic

All standard arithmetic operators are supported. In unchecked contexts they wrap silently; in checked contexts they throw OverflowException on overflow.

UInt24 a = UInt24.MaxValue;
UInt24 b = a + (UInt24)1;      // wraps to 0 (unchecked)

checked
{
    UInt24 c = UInt24.MaxValue + (UInt24)1; // throws OverflowException
}

Parsing and Formatting

UInt24 supports the same parsing and formatting API as the built-in integer types:

UInt24 v = UInt24.Parse("12345", CultureInfo.InvariantCulture);
string s = v.ToString("X6", CultureInfo.InvariantCulture); // "00003039"

if (UInt24.TryParse("16777216", CultureInfo.InvariantCulture, out var result))
{
    // not reached — value exceeds MaxValue
}

Reading and Writing

UInt24 is used as the return type and parameter type for the 24-bit read/write extension methods on all supported byte container types. An optional Endian parameter (default Endian.Little) controls byte ordering.

byte[] data = new byte[3];

// Write little-endian (default)
data.SetUInt24(0, (UInt24)0x123456);
// data is now [0x56, 0x34, 0x12]

// Read it back
UInt24 le = data.GetUInt24(0);             // 0x123456
UInt24 be = data.GetUInt24(0, Endian.Big); // 0x563412

// Works on all container types
Span<byte> span = data;
UInt24 fromSpan = span.GetUInt24();

using var stream = new MemoryStream(data);
UInt24 fromStream = stream.ReadUInt24OrThrow();

See Reading and Writing for the full list of supported container types.