Expand description
§arbitrary-int - Arbitrary number types for Rust
This crate implements arbitrary numbers for Rust. Once included, you can use types like u5 or u120.
§Why yet another arbitrary integer crate?
There are quite a few similar crates to this one (the most famous being ux). After trying out a few of them I just realized that they are all very heavy: They create a ton of classes and take seconds to compile.
This crate is designed to be very short, using const generics. Instead of introducing ~123 new structs, this crates only
introduces 5 (one for u8, u16, u32, u64, u128) and uses const generics for the specific bit depth.
It does introduce 123 new type aliases (u1, u2, etc.), but these don’t stress the compiler nearly as much.
Additionally, most of its functions are const, so that they can be used in const contexts.
§How to use
Unlike primitive data types like u32, there is no intrinsic syntax (Rust does not allow that). An instance is created as
follows:
use arbitrary_int::u9;
let value9 = u9::new(30);This will create a value with 9 bits. If the value passed into new() doesn’t fit, a panic! will be raised. This means
that a function that accepts a u9 as an argument can be certain that its contents are never larger than an u9.
Standard operators are all overloaded, so it is possible to perform calculations using this type. Note that addition and subtraction (at least in debug mode) performs bounds check. If this is undesired, see chapter num-traits below.
Internally, u9 will hold its data in an u16. It is possible to get this value:
use arbitrary_int::u9;
let value9 = u9::new(30).value();§Underlying data type
This crate defines types u1, u2, .., u126, u127 (skipping the normal u8, u16, u32, u64, u128). Each of those types holds
its actual data in the next larger data type (e.g. a u14 internally has an u16, a u120 internally has an u128). However,
uXX are just type aliases; it is also possible to use the actual underlying generic struct:
use arbitrary_int::UInt;
let a = UInt::<u8, 5>::new(0b10101);
let b = UInt::<u32, 5>::new(0b10101);In this example, a will have 5 bits and be represented by a u8. This is identical to u5. b however is represented by a
u32, so it is a different type from u5.
§Extract
A common source for arbitrary integers is by extracting them from bitfields. For example, if data contained 32 bits and
we want to extract bits 4..=9, we could perform the following:
use arbitrary_int::u6;
let data = 5_u32;
let a = u6::new(((data >> 4) & 0b111111) as u8);This is a pretty common operation, but it’s easy to get it wrong: The number of 1s and u6 have to match. Also, new()
will internally perform a bounds-check, which can panic. Thirdly, a type-cast is often needed.
To make this easier, various extract methods exist that handle shifting and masking, for example:
use arbitrary_int::{u6, u12};
let data = 0b1010100000_u32;
let a = u6::extract_u32(data, 4);
assert_eq!(a.value(), 0b101010);
let data2 = (0x800 as u128) << 63;
let b = u12::extract_u128(data2, 63);
assert_eq!(b.value(), 0x800);§num-traits
By default, arbitrary-int doesn’t require any other traits. It has optional support for num-traits however. It
implements WrappingAdd, WrappingSub, which (unlike the regular addition and subtraction) don’t perform bounds checks.
Modules§
- prelude
- The preferred way to import arbitrary-int into a project:
use arbitrary_int::prelude::* - traits
Structs§
- Int
- A signed integer of arbitrary bit length.
- TryNew
Error - UInt
- An unsigned integer of arbitrary bit length.
Traits§
- Number
Deprecated - Compatibility with arbitrary-int 1.x, which didn’t support signed integers.
Type Aliases§
- i1
- i2
- i3
- i4
- i5
- i6
- i7
- i9
- i10
- i11
- i12
- i13
- i14
- i15
- i17
- i18
- i19
- i20
- i21
- i22
- i23
- i24
- i25
- i26
- i27
- i28
- i29
- i30
- i31
- i33
- i34
- i35
- i36
- i37
- i38
- i39
- i40
- i41
- i42
- i43
- i44
- i45
- i46
- i47
- i48
- i49
- i50
- i51
- i52
- i53
- i54
- i55
- i56
- i57
- i58
- i59
- i60
- i61
- i62
- i63
- i65
- i66
- i67
- i68
- i69
- i70
- i71
- i72
- i73
- i74
- i75
- i76
- i77
- i78
- i79
- i80
- i81
- i82
- i83
- i84
- i85
- i86
- i87
- i88
- i89
- i90
- i91
- i92
- i93
- i94
- i95
- i96
- i97
- i98
- i99
- i100
- i101
- i102
- i103
- i104
- i105
- i106
- i107
- i108
- i109
- i110
- i111
- i112
- i113
- i114
- i115
- i116
- i117
- i118
- i119
- i120
- i121
- i122
- i123
- i124
- i125
- i126
- i127
- u1
- u2
- u3
- u4
- u5
- u6
- u7
- u9
- u10
- u11
- u12
- u13
- u14
- u15
- u17
- u18
- u19
- u20
- u21
- u22
- u23
- u24
- u25
- u26
- u27
- u28
- u29
- u30
- u31
- u33
- u34
- u35
- u36
- u37
- u38
- u39
- u40
- u41
- u42
- u43
- u44
- u45
- u46
- u47
- u48
- u49
- u50
- u51
- u52
- u53
- u54
- u55
- u56
- u57
- u58
- u59
- u60
- u61
- u62
- u63
- u65
- u66
- u67
- u68
- u69
- u70
- u71
- u72
- u73
- u74
- u75
- u76
- u77
- u78
- u79
- u80
- u81
- u82
- u83
- u84
- u85
- u86
- u87
- u88
- u89
- u90
- u91
- u92
- u93
- u94
- u95
- u96
- u97
- u98
- u99
- u100
- u101
- u102
- u103
- u104
- u105
- u106
- u107
- u108
- u109
- u110
- u111
- u112
- u113
- u114
- u115
- u116
- u117
- u118
- u119
- u120
- u121
- u122
- u123
- u124
- u125
- u126
- u127