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
Aint
s 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