typenum

The typenum crate provides type-level signed integers through three primary structures: PInt<U> for strictly positive integers, NInt<U> for strictly negative integers, and Z0 for the integer zero.

Important Note: These signed integers do not use two's complement representation. Instead, they are composed of a sign and an underlying unsigned integer. Consequently, operators that manipulate the underlying bit structure are intentionally not implemented to avoid ambiguous results.

It is recommended to use the aliases provided in the consts module rather than instantiating these structs directly.

use std::ops::{Add, Div, Mul, Rem, Sub};
use typenum::{Integer, N3, P2};

// Example of type-level arithmetic operations
assert_eq!(<N3 as Add<P2>>::Output::to_i32(), -1);
assert_eq!(<N3 as Sub<P2>>::Output::to_i32(), -5);
assert_eq!(<N3 as Mul<P2>>::Output::to_i32(), -6);
assert_eq!(<N3 as Div<P2>>::Output::to_i32(), -1);
assert_eq!(<N3 as Rem<P2>>::Output::to_i32(), -1);

The typenum crate provides type-level numbers evaluated at compile time. It uses two primary categories of traits:

1. Marker Traits: These are used to convert a type-level number into its runtime counterpart, primarily for debugging or runtime logic. For example, the Integer trait allows you to call .to_i32() on a type.

2. Type Operators: These are traits that behave like functions at the type level. They perform arithmetic or logical operations where the Output associated type represents the result of the operation. For example, the Add trait can be used to compute the sum of two type-level integers.

To make type operators easier to use, the crate provides helper aliases (e.g., Sum instead of using <A as Add<B>>::Output).

use typenum::{Integer, P3, P4};
use std::ops::Add;

// Using a Type Operator directly
type X = <P3 as Add<P4>>::Output;
assert_eq!(<X as Integer>::to_i32(), 7);

// Using a helper alias
use typenum::{Sum};
type Y = Sum<P3, P4>;
assert_eq!(<Y as Integer>::to_i32(), 7);

A type-level array is represented by the TArr<V, A> struct, where V is the first element and A is the rest of the array. The array is terminated by the ATerm type.

Key Characteristics:

• Termination: Every array ends with ATerm.
• Length: The length of an ATerm is U0. The length of a TArr is the length of its tail plus one.
• Type Constraints: While TArr can hold any type, it is specifically optimized for Integer types. Operations like addition, subtraction, and multiplication are implemented for these types.
• Operations:
  • Array-to-Array: Add and Sub operations are only supported between two arrays of the same length. Adding two TArr instances results in a new TArr where each element is the sum of the corresponding elements from the input arrays.
  • Scalar Operations: You can multiply (Mul), divide (Div), modulo (Rem), or negate (Neg) an entire array by a scalar value. This applies the operation to every element within the array.

// Conceptual structure of a TArr
// tarr![P3, N4] expands to TArr<P3, TArr<N4, ATerm>>

typenum provides type-level unsigned integers through the UInt<U, B> struct and the UTerm terminating type. Instead of using the raw structs directly, it is recommended to use the aliases provided in the consts module (e.g., U0, U1, U2, etc.).

These types support standard arithmetic and bitwise operations implemented via traits from core::ops (like Add, Sub, Mul, Div, BitAnd, BitOr, BitXor, Shl, Shr) and typenum (like Cmp, Pow).

To convert a type-level integer to a runtime value, use the to_u32(), to_u64(), to_usize(), etc., methods provided by the Unsigned trait.

use std::ops::{Add, BitAnd, BitOr, BitXor, Div, Mul, Rem, Shl, Shr, Sub};
use typenum::{Unsigned, U1, U2, U3, U4};

assert_eq!(<U3 as BitAnd<U2>>::Output::to_u32(), 2);
assert_eq!(<U3 as BitOr<U4>>::Output::to_u32(), 7);
assert_eq!(<U3 as BitXor<U2>>::Output::to_u32(), 1);
assert_eq!(<U3 as Shl<U1>>::Output::to_u32(), 6);
assert_eq!(<U3 as Shr<U1>>::Output::to_u32(), 1);
assert_eq!(<U3 as Add<U2>>::Output::to_u32(), 5);
assert_eq!(<U3 as Sub<U2>>::Output::to_u32(), 1);
assert_eq!(<U3 as Mul<U2>>::Output::to_u32(), 6);
assert_eq!(<U3 as Div<U2>>::Output::to_u32(), 1);
assert_eq!(<U3 as Rem<U2>>::Output::to_u32(), 1);