Crate bitint

Expand description

Integer types that have a logical size measured in bits.

This crate provides the UBitint trait and 128 types named U1 through U128 that implement it. Each type wraps the smallest primitive unsigned integer type that can contain it. The types that are not the same width as their primitive type impose a validity constraint—the value is represented in the least significant bits and the upper bits are always clear.

Demo

// Recommended, but not required.
use bitint::prelude::*;

// Use the bitint! macro to write a bitint literal. Underscores are
// permitted anywhere in a Rust literal and are encouraged for readability.
let seven = bitint!(7_U12);

// Use the #[bitint_literals] attribute macro to write bitint literals
// anywhere inside an item. Here the item is a function, but it can also be
// useful on an impl block or inline module.
#[bitint_literals]
fn demo() {
    let five = 5_U12;

    // Arithmetic ops accept Self or the primitive type and panic or wrap
    // just like primitive arithmetic ops.
    assert_eq!(five + five, 10_U12);
    assert_eq!(five - 1_U12, 4_U12);
    assert_eq!(five * 2_U12, 10_U12);
    assert_eq!(five / 3_U12, 1_U12);
    assert_eq!(five % 3_U12, 2_U12);
    // If built with overflow-checks = true, this would panic.
    // If built with overflow-checks = false, this would wrap.
    // five + U12::MAX

    // Checked arithmetic ops.
    assert_eq!(five.checked_add(10_U12), Some(15_U12));
    assert_eq!(five.checked_add(4095_U12), None);

    // Wrapping arithmetic ops.
    assert_eq!(five.wrapping_add(10_U12), 15_U12);
    assert_eq!(five.wrapping_add(4095_U12), 4_U12);

    // Zero-(extra)-cost unchecked arithmetic ops.
    #[cfg(feature = "unchecked_math")]
    {
        // SAFETY: 15 is in range for U12.
        assert_eq!(unsafe { five.unchecked_add(10_U12) }, 15_U12);
        // This would violate the safety condition and cause undefined
        // behavior.
        // unsafe { five.unchecked_add(4095_U12) }
    }

    // Zero-cost conversion to a primitive type.
    assert_eq!(five.to_primitive(), 5);

    // Checked constructor.
    assert_eq!(U12::new(5), Some(five));
    assert_eq!(U12::new(4096), None);

    // Masking constructor.
    assert_eq!(U12::new_masked(5), five);
    assert_eq!(U12::new_masked(13 * 4096 + 5), five);

    // Zero-cost unsafe constructor.
    // SAFETY: 5 is in range for U12.
    assert_eq!(unsafe { U12::new_unchecked(5) }, five);
    // This would violate the safety condition and cause undefined behavior.
    // unsafe { U12::new_unchecked(65536) }

    // Zero-cost safe constructor, only for bitints that are the same width
    // as a primitive type.
    assert_eq!(U16::from_primitive(1234), 1234_U16);

    // String conversions.
    assert_eq!(format!("{five}"), "5");
    assert_eq!(five.to_string(), "5");
    assert_eq!("5".parse::<U12>().unwrap(), 5_U12);
};

Crate features

unchecked_math - Enables the unchecked_* methods on unsigned bitint types. Requires a nightly Rust compiler.

Modules

prelude
Convenience re-exports.

Macros

bitint
Constructs a bitint literal.

Structs

RangeError
The error type returned when a TryFrom conversion to a bitint fails.
U1
The 1-bit unsigned bitint type.
U2
The 2-bit unsigned bitint type.
U3
The 3-bit unsigned bitint type.
U4
The 4-bit unsigned bitint type.
U5
The 5-bit unsigned bitint type.
U6
The 6-bit unsigned bitint type.
U7
The 7-bit unsigned bitint type.
U8
The 8-bit unsigned bitint type.
U9
The 9-bit unsigned bitint type.
U10
The 10-bit unsigned bitint type.
U11
The 11-bit unsigned bitint type.
U12
The 12-bit unsigned bitint type.
U13
The 13-bit unsigned bitint type.
U14
The 14-bit unsigned bitint type.
U15
The 15-bit unsigned bitint type.
U16
The 16-bit unsigned bitint type.
U17
The 17-bit unsigned bitint type.
U18
The 18-bit unsigned bitint type.
U19
The 19-bit unsigned bitint type.
U20
The 20-bit unsigned bitint type.
U21
The 21-bit unsigned bitint type.
U22
The 22-bit unsigned bitint type.
U23
The 23-bit unsigned bitint type.
U24
The 24-bit unsigned bitint type.
U25
The 25-bit unsigned bitint type.
U26
The 26-bit unsigned bitint type.
U27
The 27-bit unsigned bitint type.
U28
The 28-bit unsigned bitint type.
U29
The 29-bit unsigned bitint type.
U30
The 30-bit unsigned bitint type.
U31
The 31-bit unsigned bitint type.
U32
The 32-bit unsigned bitint type.
U33
The 33-bit unsigned bitint type.
U34
The 34-bit unsigned bitint type.
U35
The 35-bit unsigned bitint type.
U36
The 36-bit unsigned bitint type.
U37
The 37-bit unsigned bitint type.
U38
The 38-bit unsigned bitint type.
U39
The 39-bit unsigned bitint type.
U40
The 40-bit unsigned bitint type.
U41
The 41-bit unsigned bitint type.
U42
The 42-bit unsigned bitint type.
U43
The 43-bit unsigned bitint type.
U44
The 44-bit unsigned bitint type.
U45
The 45-bit unsigned bitint type.
U46
The 46-bit unsigned bitint type.
U47
The 47-bit unsigned bitint type.
U48
The 48-bit unsigned bitint type.
U49
The 49-bit unsigned bitint type.
U50
The 50-bit unsigned bitint type.
U51
The 51-bit unsigned bitint type.
U52
The 52-bit unsigned bitint type.
U53
The 53-bit unsigned bitint type.
U54
The 54-bit unsigned bitint type.
U55
The 55-bit unsigned bitint type.
U56
The 56-bit unsigned bitint type.
U57
The 57-bit unsigned bitint type.
U58
The 58-bit unsigned bitint type.
U59
The 59-bit unsigned bitint type.
U60
The 60-bit unsigned bitint type.
U61
The 61-bit unsigned bitint type.
U62
The 62-bit unsigned bitint type.
U63
The 63-bit unsigned bitint type.
U64
The 64-bit unsigned bitint type.
U65
The 65-bit unsigned bitint type.
U66
The 66-bit unsigned bitint type.
U67
The 67-bit unsigned bitint type.
U68
The 68-bit unsigned bitint type.
U69
The 69-bit unsigned bitint type.
U70
The 70-bit unsigned bitint type.
U71
The 71-bit unsigned bitint type.
U72
The 72-bit unsigned bitint type.
U73
The 73-bit unsigned bitint type.
U74
The 74-bit unsigned bitint type.
U75
The 75-bit unsigned bitint type.
U76
The 76-bit unsigned bitint type.
U77
The 77-bit unsigned bitint type.
U78
The 78-bit unsigned bitint type.
U79
The 79-bit unsigned bitint type.
U80
The 80-bit unsigned bitint type.
U81
The 81-bit unsigned bitint type.
U82
The 82-bit unsigned bitint type.
U83
The 83-bit unsigned bitint type.
U84
The 84-bit unsigned bitint type.
U85
The 85-bit unsigned bitint type.
U86
The 86-bit unsigned bitint type.
U87
The 87-bit unsigned bitint type.
U88
The 88-bit unsigned bitint type.
U89
The 89-bit unsigned bitint type.
U90
The 90-bit unsigned bitint type.
U91
The 91-bit unsigned bitint type.
U92
The 92-bit unsigned bitint type.
U93
The 93-bit unsigned bitint type.
U94
The 94-bit unsigned bitint type.
U95
The 95-bit unsigned bitint type.
U96
The 96-bit unsigned bitint type.
U97
The 97-bit unsigned bitint type.
U98
The 98-bit unsigned bitint type.
U99
The 99-bit unsigned bitint type.
U100
The 100-bit unsigned bitint type.
U101
The 101-bit unsigned bitint type.
U102
The 102-bit unsigned bitint type.
U103
The 103-bit unsigned bitint type.
U104
The 104-bit unsigned bitint type.
U105
The 105-bit unsigned bitint type.
U106
The 106-bit unsigned bitint type.
U107
The 107-bit unsigned bitint type.
U108
The 108-bit unsigned bitint type.
U109
The 109-bit unsigned bitint type.
U110
The 110-bit unsigned bitint type.
U111
The 111-bit unsigned bitint type.
U112
The 112-bit unsigned bitint type.
U113
The 113-bit unsigned bitint type.
U114
The 114-bit unsigned bitint type.
U115
The 115-bit unsigned bitint type.
U116
The 116-bit unsigned bitint type.
U117
The 117-bit unsigned bitint type.
U118
The 118-bit unsigned bitint type.
U119
The 119-bit unsigned bitint type.
U120
The 120-bit unsigned bitint type.
U121
The 121-bit unsigned bitint type.
U122
The 122-bit unsigned bitint type.
U123
The 123-bit unsigned bitint type.
U124
The 124-bit unsigned bitint type.
U125
The 125-bit unsigned bitint type.
U126
The 126-bit unsigned bitint type.
U127
The 127-bit unsigned bitint type.
U128
The 128-bit unsigned bitint type.

Enums

ParseBitintError
The error type returned when parsing a string to a bitint fails.
UBitintForWidth
Maps each bit width to its corresponding UBitint type.

Traits

FnUBitint
A type-level function returning a UBitint.
UBitint
Unsigned bitint types.

Attribute Macros

bitint_literals
Rewrites bitint literals in the item it is attached to.