    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

    use super::imp::{BitMaskWord, BITMASK_MASK, BITMASK_STRIDE};
    #[cfg(feature = "nightly")]
    use core::intrinsics;

    /// A bit mask which contains the result of a `Match` operation on a `Group` and
    /// allows iterating through them.
    ///
    /// The bit mask is arranged so that low-order bits represent lower memory
    /// addresses for group match results.
    ///
    /// For implementation reasons, the bits in the set may be sparsely packed, so
    /// that there is only one bit-per-byte used (the high bit, 7). If this is the
    /// case, `BITMASK_STRIDE` will be 8 to indicate a divide-by-8 should be
    /// performed on counts/indices to normalize this difference. `BITMASK_MASK` is
    /// similarly a mask of all the actually-used bits.
    #[derive(Copy, Clone)]
    pub struct BitMask(pub BitMaskWord);

    #[allow(clippy::use_self)]
    impl BitMask {
        /// Returns a new `BitMask` with all bits inverted.
        #[inline]
        #[must_use]
        pub fn invert(self) -> Self {
            BitMask(self.0 ^ BITMASK_MASK)
        }

        /// Flip the bit in the mask for the entry at the given index.
        ///
        /// Returns the bit's previous state.
        #[inline]
        #[allow(clippy::cast_ptr_alignment)]
        #[cfg(feature = "raw")]
        pub unsafe fn flip(&mut self, index: usize) -> bool {
            // NOTE: The + BITMASK_STRIDE - 1 is to set the high bit.
            let mask = 1 << (index * BITMASK_STRIDE + BITMASK_STRIDE - 1);
            self.0 ^= mask;
            // The bit was set if the bit is now 0.
            self.0 & mask == 0
        }

        /// Returns a new `BitMask` with the lowest bit removed.
        #[inline]
        #[must_use]
        pub fn remove_lowest_bit(self) -> Self {
            BitMask(self.0 & (self.0 - 1))
        }
        /// Returns whether the `BitMask` has at least one set bit.
        #[inline]
        pub fn any_bit_set(self) -> bool {
            self.0 != 0
        }

        /// Returns the first set bit in the `BitMask`, if there is one.
        #[inline]
        pub fn lowest_set_bit(self) -> Option<usize> {
            if self.0 == 0 {
                None
            } else {
                Some(unsafe { self.lowest_set_bit_nonzero() })
            }
        }

        /// Returns the first set bit in the `BitMask`, if there is one. The
        /// bitmask must not be empty.
        #[inline]
        #[cfg(feature = "nightly")]
        pub unsafe fn lowest_set_bit_nonzero(self) -> usize {
            intrinsics::cttz_nonzero(self.0) as usize / BITMASK_STRIDE
        }
        #[inline]
        #[cfg(not(feature = "nightly"))]
        pub unsafe fn lowest_set_bit_nonzero(self) -> usize {
            self.trailing_zeros()
        }

        /// Returns the number of trailing zeroes in the `BitMask`.
        #[inline]
        pub fn trailing_zeros(self) -> usize {
            // ARM doesn't have a trailing_zeroes instruction, and instead uses
            // reverse_bits (RBIT) + leading_zeroes (CLZ). However older ARM
            // versions (pre-ARMv7) don't have RBIT and need to emulate it
            // instead. Since we only have 1 bit set in each byte on ARM, we can
            // use swap_bytes (REV) + leading_zeroes instead.
            if cfg!(target_arch = "arm") && BITMASK_STRIDE % 8 == 0 {
                self.0.swap_bytes().leading_zeros() as usize / BITMASK_STRIDE
            } else {
                self.0.trailing_zeros() as usize / BITMASK_STRIDE
            }
        }

        /// Returns the number of leading zeroes in the `BitMask`.
        #[inline]
        pub fn leading_zeros(self) -> usize {
            self.0.leading_zeros() as usize / BITMASK_STRIDE
        }
    }

    impl IntoIterator for BitMask {
        type Item = usize;
        type IntoIter = BitMaskIter;

        #[inline]
        fn into_iter(self) -> BitMaskIter {
            BitMaskIter(self)
        }
    }

    /// Iterator over the contents of a `BitMask`, returning the indices of set
    /// bits.
    pub struct BitMaskIter(BitMask);

    impl Iterator for BitMaskIter {
        type Item = usize;

        #[inline]
        fn next(&mut self) -> Option<usize> {
            let bit = self.0.lowest_set_bit()?;
            self.0 = self.0.remove_lowest_bit();
            Some(bit)
        }
    }