Equisized (primitive) signed ints for primitive ints

According to Rust's reference, primitive numeric integer types in Rust are such:

Numeric types

Integer types

The unsigned integer types consist of:

Type | Minimum | Maximum -------|---------|------------------- u8 | 0 | 2⁸-1 u16 | 0 | 2¹⁶-1 u32 | 0 | 2³²-1 u64 | 0 | 2⁶⁴-1 u128 | 0 | 2¹²⁸-1

The signed two's complement integer types consist of:

Type | Minimum | Maximum -------|--------------------|------------------- i8 | -(2⁷) | 2⁷-1 i16 | -(2¹⁵) | 2¹⁵-1 i32 | -(2³¹) | 2³¹-1 i64 | -(2⁶³) | 2⁶³-1 i128 | -(2¹²⁷) | 2¹²⁷-1

Machine-dependent integer types

The usize type is an unsigned integer type with the same number of bits as the platform's pointer type. It can represent every memory address in the process.

The isize type is a signed integer type with the same number of bits as the platform's pointer type. The theoretical upper bound on object and array size is the maximum isize value. This ensures that isize can be used to calculate differences between pointers into an object or array and can address every byte within an object along with one byte past the end.

usize and isize are at least 16-bits wide.

Note: Many pieces of Rust code may assume that pointers, usize, and isize are either 32-bit or 64-bit. As a consequence, 16-bit pointer support is limited and may require explicit care and acknowledgment from a library to support.

Why this trait is needed

All primitive numeric integer types, including machine-dependent types, come with known size that can be obtained via core::mem::size_of<T>() and the corresponding signed or unsigned counterpart with the exact size. Such algorithms as C++ 20 standard midpoint relies both on equisized primitive unsigned integers and on equisized primitive signed integers. This crate offers the latter.

Signed integers

Type | Size | Equisized primitive signed integer --------|------------------------|----------------------------------- i8 | 1 byte | i8
i16 | 2 bytes | i16
i32 | 4 bytes | i32
i64 | 8 bytes | i64
i128 | 16 bytes | i128
isize | platform-dependent | isize

Unsigned integers

Type | Size | Equisized primitive signed integer --------|------------------------|----------------------------------- u8 | 1 byte | i8
u16 | 2 bytes | i16
u32 | 4 bytes | i32
u64 | 8 bytes | i64
u128 | 16 bytes | i128
usize | platform-dependent | isize

Example

You can notice that EquisizedPrimitiveSignedIntExt is quite long to type. To make it shorter, you are advised to rename the imported trait as EPSI, the namesake for the crate. Because its uses are meant to be accompanied with fully qualified syntax, such shorthand is indispensible.

rust use epsi::EquisizedPrimitiveSignedIntExt as EPSI; let a: u8 = u8::MAX; assert_eq!(a as <u8 as EPSI>::EquisizedPrimitiveSignedInt, -1i8);

Analogues

• C++: std::make_signed

License

^{Licensed under either of Apache License, Version 2.0 or MIT license at your option.}

_{Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.}