bit_int/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
// SPDX-FileCopyrightText: 2024 Shun Sakai
//
// SPDX-License-Identifier: Apache-2.0 OR MIT

//! The `bit-int` crate is a library for providing arbitrary fixed bit-width
//! integers.
//!
//! The [`BitInt`] type represents a `N`-bit signed integer. This type is
//! similar to `signed _BitInt(n)` in [C23], or arbitrary fixed bit-width signed
//! integer types (e.g., `i7`) in [Zig].
//!
//! The [`BitUint`] type represents a `N`-bit unsigned integer. This type is
//! similar to `unsigned _BitInt(n)` in C23, or arbitrary fixed bit-width
//! unsigned integer types (e.g., `u7`) in Zig.
//!
//! The largest size of `N` depends on the size of the underlying type in bits.
//! Therefore, when the underlying type of [`BitInt`] is [`i32`], the largest
//! size of `N` is [`i32::BITS`], and when the underlying type of [`BitUint`] is
//! [`u64`], the largest size of `N` is [`u64::BITS`].
//!
//! # Examples
//!
//! ## Signed integer type
//!
//! ```
//! use bit_int::BitInt;
//!
//! type Int = BitInt<i8, 7>;
//!
//! let n = Int::MIN;
//! assert_eq!(format!("{n}"), "-64");
//!
//! let n = n.checked_add(106).unwrap();
//! // Gets the contained value as the underlying type.
//! assert_eq!(n.get(), 42);
//!
//! let n = n.checked_add(21).unwrap();
//! assert_eq!(n.get(), 63);
//! assert_eq!(n, Int::MAX);
//!
//! assert!(n.checked_add(22).is_none());
//! ```
//!
//! ## Unsigned integer type
//!
//! ```
//! use bit_int::BitUint;
//!
//! type Uint = BitUint<u8, 7>;
//!
//! let n = Uint::MIN;
//! assert_eq!(format!("{n}"), "0");
//!
//! let n = n.checked_add(42).unwrap();
//! // Gets the contained value as the underlying type.
//! assert_eq!(n.get(), 42);
//!
//! let n = n.checked_add(85).unwrap();
//! assert_eq!(n.get(), 127);
//! assert_eq!(n, Uint::MAX);
//!
//! assert!(n.checked_add(86).is_none());
//! ```
//!
//! [C23]: https://en.cppreference.com/w/c/23
//! [Zig]: https://ziglang.org/

#![doc(html_root_url = "https://docs.rs/bit-int/0.1.0/")]
#![no_std]
// Lint levels of rustc.
#![deny(missing_docs)]

#[cfg(test)]
#[macro_use]
extern crate alloc;

mod bit_int;
mod bit_uint;

pub use crate::{
    bit_int::{BitI128, BitI16, BitI32, BitI64, BitI8, BitInt, BitIsize},
    bit_uint::{BitU128, BitU16, BitU32, BitU64, BitU8, BitUint, BitUsize},
};