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
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

//! # bitty - helps a bit
//! `bitty` contains functions to extract bits from, and put back into integer types.
//!
//! ## Usage
//! Include `bitty` in your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! bitty = "1.0"
//! ```
//!
//! # Use cases
//! Extracting individual bits:
//!
//! ```rust
//! # use bitty::*;
//! let five_as_bits: Vec<bool> = 5u8.as_bits();
//! // Expected: 1 0 1 0 0 0 0 0
//! assert_eq!(five_as_bits, vec![true, false, true, false, false, false, false, false]);
//! ```
//!
//! Putting bits back into an u8:
//!
//! ```rust
//! # use bitty::*;
//! let five_from_bits: u8 = u8::from_bits(&5u8.as_bits());
//! assert_eq!(5, five_from_bits);
//! ```
//!
//! Creating an integer from some bits:
//!
//! ```rust
//! # use bitty::*;
//! // Note that the vector does not have to contain 64 bits.
//! // Missing bits default to 0.
//! let one_from_bits: u64 = u64::from_bits(&vec![true]);
//! assert_eq!(1, one_from_bits);
//! ```

pub use traits::*;

mod macros;

pub mod traits {
    pub trait AsBits {
        /// Extracts all bits as a boolean vector.
        ///
        /// # Examples
        /// ```rust
        /// # use bitty::*;
        /// let bits: Vec<bool> = 5u8.as_bits();
        /// // Expected: 1 0 1 0 0 0 0 0
        /// assert_eq!(bits, vec![true, false, true, false, false, false, false, false]);
        /// ```
        fn as_bits(&self) -> Vec<bool>;

        /// Extracts bits until an index as a boolean vector.
        ///
        /// # Arguments
        /// * `until` - Take bits until this index (exclusive)
        ///
        /// # Panics
        /// This function panics if `until` is smaller than the size of the integer type.
        ///
        /// # Examples
        /// ```rust
        /// # use bitty::*;
        /// let bits: Vec<bool> = 5u64.as_bits_until(4);
        /// // Expected: 1 0 1 0
        /// assert_eq!(bits, vec![true, false, true, false]);
        /// ```
        fn as_bits_until(&self, until: usize) -> Vec<bool>;

        /// Extracts bits until an index as a boolean vector.
        ///
        /// # Arguments
        /// * `until` - Take bits until this index (exclusive)
        ///
        /// # Safety
        /// This function does not check if `until` is larger than the bits in the integer type.
        /// The code might try to bit shift outside the size of the integer type, which is UB.
        ///
        /// # Examples
        /// ```rust
        /// # use bitty::*;
        /// unsafe {
        ///     let bits: Vec<bool> = 5u64.as_bits_until_unchecked(4);
        ///     // Expected: 1 0 1 0
        ///     assert_eq!(bits, vec![true, false, true, false]);
        /// }
        /// ```
        unsafe fn as_bits_until_unchecked(&self, until: usize) -> Vec<bool>;
    }

    pub trait FromBits {
        /// Puts bits back into an integer type.
        ///
        /// # Arguments
        /// * `bits` - A boolean slice containing all bits of the integer.
        /// Missing bits default to 0.
        ///
        /// # Panics
        /// This function panics if the length of `bits` is larger than the size of the integer type.
        ///
        /// # Examples
        /// ```rust
        /// # use bitty::*;
        /// let bits: Vec<bool> = vec![true, true, true, true];
        /// assert_eq!(15, u8::from_bits(&bits));
        /// ```
        fn from_bits(bits: &[bool]) -> Self;

        /// Puts bits back into an integer type.
        ///
        /// # Arguments
        /// * `bits` - A boolean slice containing all bits of the integer.
        /// Missing bits default to 0.
        ///
        /// # Safety
        /// The code might try to bit shift outside the size of the integer type, which is UB.
        /// This might cause a panic at runtime.
        ///
        /// # Examples
        /// ```rust
        /// # use bitty::*;
        /// unsafe {
        ///     let bits: Vec<bool> = vec![true, true, true, true];
        ///     assert_eq!(15, u8::from_bits_unchecked(&bits));
        /// }
        /// ```
        unsafe fn from_bits_unchecked(bits: &[bool]) -> Self;
    }
}