brainfoamkit 1.1.0

An interpreter for the brainf*** language
Documentation 
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
134
135
136
137
138
139
140
141
142
143
144
145
146

// SPDX-FileCopyrightText: 2023 - 2024 Ali Sajid Imami
//
// SPDX-License-Identifier: Apache-2.0
// SPDX-License-Identifier: MIT

use crate::{
    Bit,
    Nybble,
};

/// An iterator over a nybble
///
/// This struct is a wrapper struct to generate an iterator
/// for `Nybble`. This allows us to map and/or loop over all the `Bit`s
/// in the `Nybble`.
///
/// This iterator iterates from the Least Significant Bit (LSB) to the
/// Most Significant Bit (MSB). This means that the first `Bit` returned
/// is the last `Bit` in the `Nybble` and the last `Bit` returned is the
/// first `Bit` in the `Nybble`.
///
/// # Examples
///
/// ```
/// use brainfoamkit_lib::{
///     Bit,
///     IterableNybble,
///     Nybble,
/// };
///
/// let nybble = Nybble::from(0b1010); // Dec: 10; Hex: 0xA; Oct: 0o12
/// let mut iter = IterableNybble::new(&nybble);
///
/// assert_eq!(iter.next(), Some(Bit::zero()));
/// assert_eq!(iter.next(), Some(Bit::one()));
/// assert_eq!(iter.next(), Some(Bit::zero()));
/// assert_eq!(iter.next(), Some(Bit::one()));
/// assert_eq!(iter.next(), None);
/// ```
///
/// # See Also
///
/// * [`Nybble`](crate::Nybble)
/// * [`Bit`](crate::Bit)
/// * [`Byte`](crate::Byte)
/// * [`IterableByte`](crate::IterableByte)
pub struct IterableNybble<'a> {
    nybble:        &'a Nybble,
    current_index: u8,
}

impl<'a> IterableNybble<'a> {
    /// Create a new `IterableNybble` from a reference to a `Nybble`
    ///
    /// # Arguments
    ///
    /// * `nybble` - A reference to a `Nybble` to iterate over
    ///
    /// # Returns
    ///
    /// A new `IterableNybble` that can be used to iterate over the `Nybble`
    ///
    /// # Examples
    ///
    /// ```
    /// use brainfoamkit_lib::{
    ///     IterableNybble,
    ///     Nybble,
    /// };
    ///
    /// let nybble = Nybble::from(0b1010); // Dec: 10; Hex: 0xA; Oct: 0o12
    /// let mut iter = IterableNybble::new(&nybble);
    ///
    /// for bit in iter {
    ///     println!("{}", bit);
    /// }
    /// ```
    #[must_use]
    pub const fn new(nybble: &'a Nybble) -> Self {
        Self {
            nybble,
            current_index: 0,
        }
    }
}

impl<'a> Iterator for IterableNybble<'a> {
    /// The type of the element the iterator returns
    type Item = Bit;

    /// Advance the iterator and return the next element
    ///
    /// # Returns
    ///
    /// The next element in the iterator
    ///
    /// # Examples
    ///
    /// ```
    /// use brainfoamkit_lib::{
    ///     Bit,
    ///     IterableNybble,
    ///     Nybble,
    /// };
    ///
    /// let nybble = Nybble::from(0b1010); // Dec: 10; Hex: 0xA; Oct: 0o12
    ///
    /// let mut iter = IterableNybble::new(&nybble);
    ///
    /// assert_eq!(iter.next(), Some(Bit::zero()));
    /// assert_eq!(iter.next(), Some(Bit::one()));
    /// assert_eq!(iter.next(), Some(Bit::zero()));
    /// assert_eq!(iter.next(), Some(Bit::one()));
    /// assert_eq!(iter.next(), None);
    /// ```
    fn next(&mut self) -> Option<Self::Item> {
        let current_index = self.current_index;
        let next_index = current_index + 1;

        if next_index > 4 {
            self.current_index = 0;
            None
        } else {
            self.current_index = next_index;
            Some(self.nybble.get_bit(current_index))
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::Bit;

    #[test]
    fn test_iterable_nybble() {
        let nybble = Nybble::from(0b1010); // Dec: 10; Hex: 0xA; Oct: 0o12
        let mut iter = nybble.iter();

        assert_eq!(iter.next(), Some(Bit::zero()));
        assert_eq!(iter.next(), Some(Bit::one()));
        assert_eq!(iter.next(), Some(Bit::zero()));
        assert_eq!(iter.next(), Some(Bit::one()));
        assert_eq!(iter.next(), None);
    }
}