Crate aint

source ·
Expand description

Aint is a crate implementing integers of non-standard bit widths between 1 and 127. These integer types are represented by the next largest built-in Rust integer, but are bounded to the range and behaviors of the advertised bit width. That is, T::MIN and T::MAX, are what would be expected for the integer T with N bits, and similarly, wrapping, saturating, and overflow behaviors match what would be expected for a hypothetical built-in integer T with N bits.

Example

fn add(a: i13, b: i13) -> i13 {
    a + b
}

let x = i13!(100);
let y = add(x, i13!(-42));
assert_eq!(y, i13!(58));

The core implementation type is Aint<R, const WIDTH: u32>, which accepts a representation type, R, and a bit width, WIDTH. Aint is intended to primarily be an implementation detail, not to be used directly. Instead, it is preferred to use the type aliases provided by this crate.

If Aint is used directly, it will only permit generic parameters that match one of the existing type aliases provided by this crate. For example, the type i24 is an alias of Aint<i32, 24>. In theory, Aint<i64, 24> would be equivalent in functionality, but will result in a compile time error if instantiated. This prevents the existence multiple Aints that are functionally the same but are incompatible types to the compiler.

Byte Wide Types

Integer types that have an exact byte width provide additional methods and functionality that other integer types do not. These are types whose width is a multiple of 8, such as i24 (3 bytes), u56 (7 bytes), and u120 (15 bytes). Such types provide the byte and endianness manipulation APIs that built-in Rust integers provide, such as T::from_be_bytes, T::swap_bytes, and T::to_le. Other integer types do not implement these methods since their meaning becomes ambiguous or perhaps even nonsensical.

Conversions

All integer types provided by this crate implement traits to convert to and from all built-in Rust integer types. A conversion will be implemented as From when the conversion is infallible, and TryFrom when the conversion can fail. For example, converting from i4 to i8 is implemented as impl From<i4> for i8, but the reverse conversion is implemented as impl TryFrom<i8> for i4.

Unfortunately, this crate does not provide the same conversions between each of the pairs of types provided, such as i4 to i13. Existing blanket implmentations on the standard conversion traits prevent a generic implementation of these traits that would cover all the types provided by this crate, and implementing conversions for each pair of types individually is infeasible due to extreme compiliation times, since each pair would result on the order of 1282 trait implementations.

This crate also provides two alternate conversion traits that perform infallible, but potentially lossy, conversions: WrappingFrom/WrappingInto and SaturatingFrom/SaturatingInto. These are implemented for all combinations of built-in integers and integers provided by this crate. See each trait’s documentation for more details.

Concatenation and Splitting

This crate also provides two traits for concatenating and spliting integers bitwise: BitConcat and BitSplit. Any pair of two integer types can be concatenated as long as their combined bit width is at most 128, and any integer can be split bitwise into any two integers whose combined bit width equals the bit width of the original integer.

let x: u16 = 0b0101010100101_101;
let (x1, x2): (i13, u3) = x.bit_split();
let y = u16::bit_concat(x1, x2);

assert_eq!(x, y);
assert_eq!(x1, i13!(0b0101010100101));
assert_eq!(x2, u3!(0b101));

Macros

Each integer type provided by this crate comes with macro for constructing these types from literals. Built-in integers can have typed literals, such as 42u8 or -7i64. The macros provided by this crate perform a similar function. u13!(100) is essentially a u13 literal with the value 100. The values provided to these macros are also checked at compile time to ensure that they are valid for the type. For example, u4!(100), would result in a compile time error, because u4 can only represent values from 0 to 15, inclusive.

Features

This crate has two non-default features, serde and num, which enable compaitbility with the serde and num crates.

Enabling the serde feature will provide implementations of serde::Serialize and serde::Deserialize for each integer type in this crate.

Enabling the num feature will provide implementations of all appropriate traits from the [num_traits] and [num_integer] crates under the num family of crates.

[dependencies]
aint = { version = "0.1", features = [ "serde", "num" ] }

no_std

This crate is also #![no_std]. Unlike some other crates, this crate does not have a std (or no_std) feature - it simply never uses or needs libstd. Additionally, this crate does not use alloc either. libcore is the only required dependency, and the crates pulled in by the serde and num features are also no_std compatible.

Macros

  • Returns a bit checked at compile time.
  • Returns a i1 checked at compile time.
  • Returns a i2 checked at compile time.
  • Returns a i3 checked at compile time.
  • Returns a i4 checked at compile time.
  • Returns a i5 checked at compile time.
  • Returns a i6 checked at compile time.
  • Returns a i7 checked at compile time.
  • Returns a i8 checked at compile time.
  • Returns a i9 checked at compile time.
  • Returns a i10 checked at compile time.
  • Returns a i11 checked at compile time.
  • Returns a i12 checked at compile time.
  • Returns a i13 checked at compile time.
  • Returns a i14 checked at compile time.
  • Returns a i15 checked at compile time.
  • Returns a i16 checked at compile time.
  • Returns a i17 checked at compile time.
  • Returns a i18 checked at compile time.
  • Returns a i19 checked at compile time.
  • Returns a i20 checked at compile time.
  • Returns a i21 checked at compile time.
  • Returns a i22 checked at compile time.
  • Returns a i23 checked at compile time.
  • Returns a i24 checked at compile time.
  • Returns a i25 checked at compile time.
  • Returns a i26 checked at compile time.
  • Returns a i27 checked at compile time.
  • Returns a i28 checked at compile time.
  • Returns a i29 checked at compile time.
  • Returns a i30 checked at compile time.
  • Returns a i31 checked at compile time.
  • Returns a i32 checked at compile time.
  • Returns a i33 checked at compile time.
  • Returns a i34 checked at compile time.
  • Returns a i35 checked at compile time.
  • Returns a i36 checked at compile time.
  • Returns a i37 checked at compile time.
  • Returns a i38 checked at compile time.
  • Returns a i39 checked at compile time.
  • Returns a i40 checked at compile time.
  • Returns a i41 checked at compile time.
  • Returns a i42 checked at compile time.
  • Returns a i43 checked at compile time.
  • Returns a i44 checked at compile time.
  • Returns a i45 checked at compile time.
  • Returns a i46 checked at compile time.
  • Returns a i47 checked at compile time.
  • Returns a i48 checked at compile time.
  • Returns a i49 checked at compile time.
  • Returns a i50 checked at compile time.
  • Returns a i51 checked at compile time.
  • Returns a i52 checked at compile time.
  • Returns a i53 checked at compile time.
  • Returns a i54 checked at compile time.
  • Returns a i55 checked at compile time.
  • Returns a i56 checked at compile time.
  • Returns a i57 checked at compile time.
  • Returns a i58 checked at compile time.
  • Returns a i59 checked at compile time.
  • Returns a i60 checked at compile time.
  • Returns a i61 checked at compile time.
  • Returns a i62 checked at compile time.
  • Returns a i63 checked at compile time.
  • Returns a i64 checked at compile time.
  • Returns a i65 checked at compile time.
  • Returns a i66 checked at compile time.
  • Returns a i67 checked at compile time.
  • Returns a i68 checked at compile time.
  • Returns a i69 checked at compile time.
  • Returns a i70 checked at compile time.
  • Returns a i71 checked at compile time.
  • Returns a i72 checked at compile time.
  • Returns a i73 checked at compile time.
  • Returns a i74 checked at compile time.
  • Returns a i75 checked at compile time.
  • Returns a i76 checked at compile time.
  • Returns a i77 checked at compile time.
  • Returns a i78 checked at compile time.
  • Returns a i79 checked at compile time.
  • Returns a i80 checked at compile time.
  • Returns a i81 checked at compile time.
  • Returns a i82 checked at compile time.
  • Returns a i83 checked at compile time.
  • Returns a i84 checked at compile time.
  • Returns a i85 checked at compile time.
  • Returns a i86 checked at compile time.
  • Returns a i87 checked at compile time.
  • Returns a i88 checked at compile time.
  • Returns a i89 checked at compile time.
  • Returns a i90 checked at compile time.
  • Returns a i91 checked at compile time.
  • Returns a i92 checked at compile time.
  • Returns a i93 checked at compile time.
  • Returns a i94 checked at compile time.
  • Returns a i95 checked at compile time.
  • Returns a i96 checked at compile time.
  • Returns a i97 checked at compile time.
  • Returns a i98 checked at compile time.
  • Returns a i99 checked at compile time.
  • Returns a i100 checked at compile time.
  • Returns a i101 checked at compile time.
  • Returns a i102 checked at compile time.
  • Returns a i103 checked at compile time.
  • Returns a i104 checked at compile time.
  • Returns a i105 checked at compile time.
  • Returns a i106 checked at compile time.
  • Returns a i107 checked at compile time.
  • Returns a i108 checked at compile time.
  • Returns a i109 checked at compile time.
  • Returns a i110 checked at compile time.
  • Returns a i111 checked at compile time.
  • Returns a i112 checked at compile time.
  • Returns a i113 checked at compile time.
  • Returns a i114 checked at compile time.
  • Returns a i115 checked at compile time.
  • Returns a i116 checked at compile time.
  • Returns a i117 checked at compile time.
  • Returns a i118 checked at compile time.
  • Returns a i119 checked at compile time.
  • Returns a i120 checked at compile time.
  • Returns a i121 checked at compile time.
  • Returns a i122 checked at compile time.
  • Returns a i123 checked at compile time.
  • Returns a i124 checked at compile time.
  • Returns a i125 checked at compile time.
  • Returns a i126 checked at compile time.
  • Returns a i127 checked at compile time.
  • Returns a i128 checked at compile time.
  • Returns a u1 checked at compile time.
  • Returns a u2 checked at compile time.
  • Returns a u3 checked at compile time.
  • Returns a u4 checked at compile time.
  • Returns a u5 checked at compile time.
  • Returns a u6 checked at compile time.
  • Returns a u7 checked at compile time.
  • Returns a u8 checked at compile time.
  • Returns a u9 checked at compile time.
  • Returns a u10 checked at compile time.
  • Returns a u11 checked at compile time.
  • Returns a u12 checked at compile time.
  • Returns a u13 checked at compile time.
  • Returns a u14 checked at compile time.
  • Returns a u15 checked at compile time.
  • Returns a u16 checked at compile time.
  • Returns a u17 checked at compile time.
  • Returns a u18 checked at compile time.
  • Returns a u19 checked at compile time.
  • Returns a u20 checked at compile time.
  • Returns a u21 checked at compile time.
  • Returns a u22 checked at compile time.
  • Returns a u23 checked at compile time.
  • Returns a u24 checked at compile time.
  • Returns a u25 checked at compile time.
  • Returns a u26 checked at compile time.
  • Returns a u27 checked at compile time.
  • Returns a u28 checked at compile time.
  • Returns a u29 checked at compile time.
  • Returns a u30 checked at compile time.
  • Returns a u31 checked at compile time.
  • Returns a u32 checked at compile time.
  • Returns a u33 checked at compile time.
  • Returns a u34 checked at compile time.
  • Returns a u35 checked at compile time.
  • Returns a u36 checked at compile time.
  • Returns a u37 checked at compile time.
  • Returns a u38 checked at compile time.
  • Returns a u39 checked at compile time.
  • Returns a u40 checked at compile time.
  • Returns a u41 checked at compile time.
  • Returns a u42 checked at compile time.
  • Returns a u43 checked at compile time.
  • Returns a u44 checked at compile time.
  • Returns a u45 checked at compile time.
  • Returns a u46 checked at compile time.
  • Returns a u47 checked at compile time.
  • Returns a u48 checked at compile time.
  • Returns a u49 checked at compile time.
  • Returns a u50 checked at compile time.
  • Returns a u51 checked at compile time.
  • Returns a u52 checked at compile time.
  • Returns a u53 checked at compile time.
  • Returns a u54 checked at compile time.
  • Returns a u55 checked at compile time.
  • Returns a u56 checked at compile time.
  • Returns a u57 checked at compile time.
  • Returns a u58 checked at compile time.
  • Returns a u59 checked at compile time.
  • Returns a u60 checked at compile time.
  • Returns a u61 checked at compile time.
  • Returns a u62 checked at compile time.
  • Returns a u63 checked at compile time.
  • Returns a u64 checked at compile time.
  • Returns a u65 checked at compile time.
  • Returns a u66 checked at compile time.
  • Returns a u67 checked at compile time.
  • Returns a u68 checked at compile time.
  • Returns a u69 checked at compile time.
  • Returns a u70 checked at compile time.
  • Returns a u71 checked at compile time.
  • Returns a u72 checked at compile time.
  • Returns a u73 checked at compile time.
  • Returns a u74 checked at compile time.
  • Returns a u75 checked at compile time.
  • Returns a u76 checked at compile time.
  • Returns a u77 checked at compile time.
  • Returns a u78 checked at compile time.
  • Returns a u79 checked at compile time.
  • Returns a u80 checked at compile time.
  • Returns a u81 checked at compile time.
  • Returns a u82 checked at compile time.
  • Returns a u83 checked at compile time.
  • Returns a u84 checked at compile time.
  • Returns a u85 checked at compile time.
  • Returns a u86 checked at compile time.
  • Returns a u87 checked at compile time.
  • Returns a u88 checked at compile time.
  • Returns a u89 checked at compile time.
  • Returns a u90 checked at compile time.
  • Returns a u91 checked at compile time.
  • Returns a u92 checked at compile time.
  • Returns a u93 checked at compile time.
  • Returns a u94 checked at compile time.
  • Returns a u95 checked at compile time.
  • Returns a u96 checked at compile time.
  • Returns a u97 checked at compile time.
  • Returns a u98 checked at compile time.
  • Returns a u99 checked at compile time.
  • Returns a u100 checked at compile time.
  • Returns a u101 checked at compile time.
  • Returns a u102 checked at compile time.
  • Returns a u103 checked at compile time.
  • Returns a u104 checked at compile time.
  • Returns a u105 checked at compile time.
  • Returns a u106 checked at compile time.
  • Returns a u107 checked at compile time.
  • Returns a u108 checked at compile time.
  • Returns a u109 checked at compile time.
  • Returns a u110 checked at compile time.
  • Returns a u111 checked at compile time.
  • Returns a u112 checked at compile time.
  • Returns a u113 checked at compile time.
  • Returns a u114 checked at compile time.
  • Returns a u115 checked at compile time.
  • Returns a u116 checked at compile time.
  • Returns a u117 checked at compile time.
  • Returns a u118 checked at compile time.
  • Returns a u119 checked at compile time.
  • Returns a u120 checked at compile time.
  • Returns a u121 checked at compile time.
  • Returns a u122 checked at compile time.
  • Returns a u123 checked at compile time.
  • Returns a u124 checked at compile time.
  • Returns a u125 checked at compile time.
  • Returns a u126 checked at compile time.
  • Returns a u127 checked at compile time.
  • Returns a u128 checked at compile time.

Structs

  • An integer with a given representation, R, and bit width, WIDTH.

Traits

  • Concatenate two integral types bitwise into a larger integral type.
  • Split an integral type bitwise into two smaller integral types.
  • Saturating conversion from one type into another.
  • Saturating conversion from one type into another.
  • Wrapping conversion from one type into another.
  • Wrapping conversion from one type into another.

Type Aliases

  • A single bit, unsigned integer
  • A 1-bit signed integer
  • A 2-bit signed integer
  • A 3-bit signed integer
  • A 4-bit signed integer
  • A 5-bit signed integer
  • A 6-bit signed integer
  • A 7-bit signed integer
  • A 8-bit signed integer
  • A 9-bit signed integer
  • A 10-bit signed integer
  • A 11-bit signed integer
  • A 12-bit signed integer
  • A 13-bit signed integer
  • A 14-bit signed integer
  • A 15-bit signed integer
  • A 16-bit signed integer
  • A 17-bit signed integer
  • A 18-bit signed integer
  • A 19-bit signed integer
  • A 20-bit signed integer
  • A 21-bit signed integer
  • A 22-bit signed integer
  • A 23-bit signed integer
  • A 24-bit signed integer
  • A 25-bit signed integer
  • A 26-bit signed integer
  • A 27-bit signed integer
  • A 28-bit signed integer
  • A 29-bit signed integer
  • A 30-bit signed integer
  • A 31-bit signed integer
  • A 32-bit signed integer
  • A 33-bit signed integer
  • A 34-bit signed integer
  • A 35-bit signed integer
  • A 36-bit signed integer
  • A 37-bit signed integer
  • A 38-bit signed integer
  • A 39-bit signed integer
  • A 40-bit signed integer
  • A 41-bit signed integer
  • A 42-bit signed integer
  • A 43-bit signed integer
  • A 44-bit signed integer
  • A 45-bit signed integer
  • A 46-bit signed integer
  • A 47-bit signed integer
  • A 48-bit signed integer
  • A 49-bit signed integer
  • A 50-bit signed integer
  • A 51-bit signed integer
  • A 52-bit signed integer
  • A 53-bit signed integer
  • A 54-bit signed integer
  • A 55-bit signed integer
  • A 56-bit signed integer
  • A 57-bit signed integer
  • A 58-bit signed integer
  • A 59-bit signed integer
  • A 60-bit signed integer
  • A 61-bit signed integer
  • A 62-bit signed integer
  • A 63-bit signed integer
  • A 64-bit signed integer
  • A 65-bit signed integer
  • A 66-bit signed integer
  • A 67-bit signed integer
  • A 68-bit signed integer
  • A 69-bit signed integer
  • A 70-bit signed integer
  • A 71-bit signed integer
  • A 72-bit signed integer
  • A 73-bit signed integer
  • A 74-bit signed integer
  • A 75-bit signed integer
  • A 76-bit signed integer
  • A 77-bit signed integer
  • A 78-bit signed integer
  • A 79-bit signed integer
  • A 80-bit signed integer
  • A 81-bit signed integer
  • A 82-bit signed integer
  • A 83-bit signed integer
  • A 84-bit signed integer
  • A 85-bit signed integer
  • A 86-bit signed integer
  • A 87-bit signed integer
  • A 88-bit signed integer
  • A 89-bit signed integer
  • A 90-bit signed integer
  • A 91-bit signed integer
  • A 92-bit signed integer
  • A 93-bit signed integer
  • A 94-bit signed integer
  • A 95-bit signed integer
  • A 96-bit signed integer
  • A 97-bit signed integer
  • A 98-bit signed integer
  • A 99-bit signed integer
  • A 100-bit signed integer
  • A 101-bit signed integer
  • A 102-bit signed integer
  • A 103-bit signed integer
  • A 104-bit signed integer
  • A 105-bit signed integer
  • A 106-bit signed integer
  • A 107-bit signed integer
  • A 108-bit signed integer
  • A 109-bit signed integer
  • A 110-bit signed integer
  • A 111-bit signed integer
  • A 112-bit signed integer
  • A 113-bit signed integer
  • A 114-bit signed integer
  • A 115-bit signed integer
  • A 116-bit signed integer
  • A 117-bit signed integer
  • A 118-bit signed integer
  • A 119-bit signed integer
  • A 120-bit signed integer
  • A 121-bit signed integer
  • A 122-bit signed integer
  • A 123-bit signed integer
  • A 124-bit signed integer
  • A 125-bit signed integer
  • A 126-bit signed integer
  • A 127-bit signed integer
  • A 128-bit signed integer
  • A 1-bit unsigned integer
  • A 2-bit unsigned integer
  • A 3-bit unsigned integer
  • A 4-bit unsigned integer
  • A 5-bit unsigned integer
  • A 6-bit unsigned integer
  • A 7-bit unsigned integer
  • A 8-bit unsigned integer
  • A 9-bit unsigned integer
  • A 10-bit unsigned integer
  • A 11-bit unsigned integer
  • A 12-bit unsigned integer
  • A 13-bit unsigned integer
  • A 14-bit unsigned integer
  • A 15-bit unsigned integer
  • A 16-bit unsigned integer
  • A 17-bit unsigned integer
  • A 18-bit unsigned integer
  • A 19-bit unsigned integer
  • A 20-bit unsigned integer
  • A 21-bit unsigned integer
  • A 22-bit unsigned integer
  • A 23-bit unsigned integer
  • A 24-bit unsigned integer
  • A 25-bit unsigned integer
  • A 26-bit unsigned integer
  • A 27-bit unsigned integer
  • A 28-bit unsigned integer
  • A 29-bit unsigned integer
  • A 30-bit unsigned integer
  • A 31-bit unsigned integer
  • A 32-bit unsigned integer
  • A 33-bit unsigned integer
  • A 34-bit unsigned integer
  • A 35-bit unsigned integer
  • A 36-bit unsigned integer
  • A 37-bit unsigned integer
  • A 38-bit unsigned integer
  • A 39-bit unsigned integer
  • A 40-bit unsigned integer
  • A 41-bit unsigned integer
  • A 42-bit unsigned integer
  • A 43-bit unsigned integer
  • A 44-bit unsigned integer
  • A 45-bit unsigned integer
  • A 46-bit unsigned integer
  • A 47-bit unsigned integer
  • A 48-bit unsigned integer
  • A 49-bit unsigned integer
  • A 50-bit unsigned integer
  • A 51-bit unsigned integer
  • A 52-bit unsigned integer
  • A 53-bit unsigned integer
  • A 54-bit unsigned integer
  • A 55-bit unsigned integer
  • A 56-bit unsigned integer
  • A 57-bit unsigned integer
  • A 58-bit unsigned integer
  • A 59-bit unsigned integer
  • A 60-bit unsigned integer
  • A 61-bit unsigned integer
  • A 62-bit unsigned integer
  • A 63-bit unsigned integer
  • A 64-bit unsigned integer
  • A 65-bit unsigned integer
  • A 66-bit unsigned integer
  • A 67-bit unsigned integer
  • A 68-bit unsigned integer
  • A 69-bit unsigned integer
  • A 70-bit unsigned integer
  • A 71-bit unsigned integer
  • A 72-bit unsigned integer
  • A 73-bit unsigned integer
  • A 74-bit unsigned integer
  • A 75-bit unsigned integer
  • A 76-bit unsigned integer
  • A 77-bit unsigned integer
  • A 78-bit unsigned integer
  • A 79-bit unsigned integer
  • A 80-bit unsigned integer
  • A 81-bit unsigned integer
  • A 82-bit unsigned integer
  • A 83-bit unsigned integer
  • A 84-bit unsigned integer
  • A 85-bit unsigned integer
  • A 86-bit unsigned integer
  • A 87-bit unsigned integer
  • A 88-bit unsigned integer
  • A 89-bit unsigned integer
  • A 90-bit unsigned integer
  • A 91-bit unsigned integer
  • A 92-bit unsigned integer
  • A 93-bit unsigned integer
  • A 94-bit unsigned integer
  • A 95-bit unsigned integer
  • A 96-bit unsigned integer
  • A 97-bit unsigned integer
  • A 98-bit unsigned integer
  • A 99-bit unsigned integer
  • A 100-bit unsigned integer
  • A 101-bit unsigned integer
  • A 102-bit unsigned integer
  • A 103-bit unsigned integer
  • A 104-bit unsigned integer
  • A 105-bit unsigned integer
  • A 106-bit unsigned integer
  • A 107-bit unsigned integer
  • A 108-bit unsigned integer
  • A 109-bit unsigned integer
  • A 110-bit unsigned integer
  • A 111-bit unsigned integer
  • A 112-bit unsigned integer
  • A 113-bit unsigned integer
  • A 114-bit unsigned integer
  • A 115-bit unsigned integer
  • A 116-bit unsigned integer
  • A 117-bit unsigned integer
  • A 118-bit unsigned integer
  • A 119-bit unsigned integer
  • A 120-bit unsigned integer
  • A 121-bit unsigned integer
  • A 122-bit unsigned integer
  • A 123-bit unsigned integer
  • A 124-bit unsigned integer
  • A 125-bit unsigned integer
  • A 126-bit unsigned integer
  • A 127-bit unsigned integer
  • A 128-bit unsigned integer