Int128 Structure

The built-in integer types short, int, and long are fixed-width registers with the characteristics shown below. Int128 is a 128-bit signed integer register with analogous behavior and greatly extended range.

To instantiate a 128-bit signed integer, you can use the constructor Int128(String), or the parsing methods Parse(String) or TryParse(String, Int128) 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 integer type (e.g. Int64), you can simply assign a Int128 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.

If you know that the numbers you need to work with all fit in a 128 bit register, arithmetic with Int128 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. (Meta.Numerics itself uses Int128 internally in the implementation of some discrete distributions that require very large integers.)

Operations that overflow and underflow Int128 behave like they do for the native unsigned integer types, with results equal to the lower 128 bits of the full result, or wrapping around from MaxValue to MinValue.

Explicit casts between Int128 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.

Int128 does not support bit-wise logical and shift operations, but the unsigned 128-bit integer type UInt128 does. If you want to perform bit-wise operations on 128-bit registers, use UInt128.

Reference