bitty/
lib.rs

1//! # bitty - helps a bit
2//! `bitty` contains functions to extract bits from, and put back into integer types.
3//!
4//! ## Usage
5//! Include `bitty` in your `Cargo.toml`:
6//!
7//! ```toml
8//! [dependencies]
9//! bitty = "1.0"
10//! ```
11//!
12//! # Use cases
13//! Extracting individual bits:
14//!
15//! ```rust
16//! # use bitty::*;
17//! let five_as_bits: Vec<bool> = 5u8.as_bits();
18//! // Expected: 1 0 1 0 0 0 0 0
19//! assert_eq!(five_as_bits, vec![true, false, true, false, false, false, false, false]);
20//! ```
21//!
22//! Putting bits back into an u8:
23//!
24//! ```rust
25//! # use bitty::*;
26//! let five_from_bits: u8 = u8::from_bits(&5u8.as_bits());
27//! assert_eq!(5, five_from_bits);
28//! ```
29//!
30//! Creating an integer from some bits:
31//!
32//! ```rust
33//! # use bitty::*;
34//! // Note that the vector does not have to contain 64 bits.
35//! // Missing bits default to 0.
36//! let one_from_bits: u64 = u64::from_bits(&vec![true]);
37//! assert_eq!(1, one_from_bits);
38//! ```
39
40pub use traits::*;
41
42mod macros;
43
44pub mod traits {
45    pub trait AsBits {
46        /// Extracts all bits as a boolean vector.
47        ///
48        /// # Examples
49        /// ```rust
50        /// # use bitty::*;
51        /// let bits: Vec<bool> = 5u8.as_bits();
52        /// // Expected: 1 0 1 0 0 0 0 0
53        /// assert_eq!(bits, vec![true, false, true, false, false, false, false, false]);
54        /// ```
55        fn as_bits(&self) -> Vec<bool>;
56
57        /// Extracts bits until an index as a boolean vector.
58        ///
59        /// # Arguments
60        /// * `until` - Take bits until this index (exclusive)
61        ///
62        /// # Panics
63        /// This function panics if `until` is smaller than the size of the integer type.
64        ///
65        /// # Examples
66        /// ```rust
67        /// # use bitty::*;
68        /// let bits: Vec<bool> = 5u64.as_bits_until(4);
69        /// // Expected: 1 0 1 0
70        /// assert_eq!(bits, vec![true, false, true, false]);
71        /// ```
72        fn as_bits_until(&self, until: usize) -> Vec<bool>;
73
74        /// Extracts bits until an index as a boolean vector.
75        ///
76        /// # Arguments
77        /// * `until` - Take bits until this index (exclusive)
78        ///
79        /// # Safety
80        /// This function does not check if `until` is larger than the bits in the integer type.
81        /// The code might try to bit shift outside the size of the integer type, which is UB.
82        ///
83        /// # Examples
84        /// ```rust
85        /// # use bitty::*;
86        /// unsafe {
87        ///     let bits: Vec<bool> = 5u64.as_bits_until_unchecked(4);
88        ///     // Expected: 1 0 1 0
89        ///     assert_eq!(bits, vec![true, false, true, false]);
90        /// }
91        /// ```
92        unsafe fn as_bits_until_unchecked(&self, until: usize) -> Vec<bool>;
93    }
94
95    pub trait FromBits {
96        /// Puts bits back into an integer type.
97        ///
98        /// # Arguments
99        /// * `bits` - A boolean slice containing all bits of the integer.
100        /// Missing bits default to 0.
101        ///
102        /// # Panics
103        /// This function panics if the length of `bits` is larger than the size of the integer type.
104        ///
105        /// # Examples
106        /// ```rust
107        /// # use bitty::*;
108        /// let bits: Vec<bool> = vec![true, true, true, true];
109        /// assert_eq!(15, u8::from_bits(&bits));
110        /// ```
111        fn from_bits(bits: &[bool]) -> Self;
112
113        /// Puts bits back into an integer type.
114        ///
115        /// # Arguments
116        /// * `bits` - A boolean slice containing all bits of the integer.
117        /// Missing bits default to 0.
118        ///
119        /// # Safety
120        /// The code might try to bit shift outside the size of the integer type, which is UB.
121        /// This might cause a panic at runtime.
122        ///
123        /// # Examples
124        /// ```rust
125        /// # use bitty::*;
126        /// unsafe {
127        ///     let bits: Vec<bool> = vec![true, true, true, true];
128        ///     assert_eq!(15, u8::from_bits_unchecked(&bits));
129        /// }
130        /// ```
131        unsafe fn from_bits_unchecked(bits: &[bool]) -> Self;
132    }
133}
bitty/lib.rs

bitty/
lib.rs
