1 use super::imp::{BitMaskWord, BITMASK_MASK, BITMASK_STRIDE}; 2 #[cfg(feature = "nightly")] 3 use core::intrinsics; 4 5 /// A bit mask which contains the result of a `Match` operation on a `Group` and 6 /// allows iterating through them. 7 /// 8 /// The bit mask is arranged so that low-order bits represent lower memory 9 /// addresses for group match results. 10 /// 11 /// For implementation reasons, the bits in the set may be sparsely packed, so 12 /// that there is only one bit-per-byte used (the high bit, 7). If this is the 13 /// case, `BITMASK_STRIDE` will be 8 to indicate a divide-by-8 should be 14 /// performed on counts/indices to normalize this difference. `BITMASK_MASK` is 15 /// similarly a mask of all the actually-used bits. 16 #[derive(Copy, Clone)] 17 pub struct BitMask(pub BitMaskWord); 18 19 #[allow(clippy::use_self)] 20 impl BitMask { 21 /// Returns a new `BitMask` with all bits inverted. 22 #[inline] 23 #[must_use] invert(self) -> Self24 pub fn invert(self) -> Self { 25 BitMask(self.0 ^ BITMASK_MASK) 26 } 27 28 /// Flip the bit in the mask for the entry at the given index. 29 /// 30 /// Returns the bit's previous state. 31 #[inline] 32 #[allow(clippy::cast_ptr_alignment)] 33 #[cfg(feature = "raw")] flip(&mut self, index: usize) -> bool34 pub unsafe fn flip(&mut self, index: usize) -> bool { 35 // NOTE: The + BITMASK_STRIDE - 1 is to set the high bit. 36 let mask = 1 << (index * BITMASK_STRIDE + BITMASK_STRIDE - 1); 37 self.0 ^= mask; 38 // The bit was set if the bit is now 0. 39 self.0 & mask == 0 40 } 41 42 /// Returns a new `BitMask` with the lowest bit removed. 43 #[inline] 44 #[must_use] remove_lowest_bit(self) -> Self45 pub fn remove_lowest_bit(self) -> Self { 46 BitMask(self.0 & (self.0 - 1)) 47 } 48 /// Returns whether the `BitMask` has at least one set bit. 49 #[inline] any_bit_set(self) -> bool50 pub fn any_bit_set(self) -> bool { 51 self.0 != 0 52 } 53 54 /// Returns the first set bit in the `BitMask`, if there is one. 55 #[inline] lowest_set_bit(self) -> Option<usize>56 pub fn lowest_set_bit(self) -> Option<usize> { 57 if self.0 == 0 { 58 None 59 } else { 60 Some(unsafe { self.lowest_set_bit_nonzero() }) 61 } 62 } 63 64 /// Returns the first set bit in the `BitMask`, if there is one. The 65 /// bitmask must not be empty. 66 #[inline] 67 #[cfg(feature = "nightly")] lowest_set_bit_nonzero(self) -> usize68 pub unsafe fn lowest_set_bit_nonzero(self) -> usize { 69 intrinsics::cttz_nonzero(self.0) as usize / BITMASK_STRIDE 70 } 71 #[inline] 72 #[cfg(not(feature = "nightly"))] lowest_set_bit_nonzero(self) -> usize73 pub unsafe fn lowest_set_bit_nonzero(self) -> usize { 74 self.trailing_zeros() 75 } 76 77 /// Returns the number of trailing zeroes in the `BitMask`. 78 #[inline] trailing_zeros(self) -> usize79 pub fn trailing_zeros(self) -> usize { 80 // ARM doesn't have a trailing_zeroes instruction, and instead uses 81 // reverse_bits (RBIT) + leading_zeroes (CLZ). However older ARM 82 // versions (pre-ARMv7) don't have RBIT and need to emulate it 83 // instead. Since we only have 1 bit set in each byte on ARM, we can 84 // use swap_bytes (REV) + leading_zeroes instead. 85 if cfg!(target_arch = "arm") && BITMASK_STRIDE % 8 == 0 { 86 self.0.swap_bytes().leading_zeros() as usize / BITMASK_STRIDE 87 } else { 88 self.0.trailing_zeros() as usize / BITMASK_STRIDE 89 } 90 } 91 92 /// Returns the number of leading zeroes in the `BitMask`. 93 #[inline] leading_zeros(self) -> usize94 pub fn leading_zeros(self) -> usize { 95 self.0.leading_zeros() as usize / BITMASK_STRIDE 96 } 97 } 98 99 impl IntoIterator for BitMask { 100 type Item = usize; 101 type IntoIter = BitMaskIter; 102 103 #[inline] into_iter(self) -> BitMaskIter104 fn into_iter(self) -> BitMaskIter { 105 BitMaskIter(self) 106 } 107 } 108 109 /// Iterator over the contents of a `BitMask`, returning the indicies of set 110 /// bits. 111 pub struct BitMaskIter(BitMask); 112 113 impl Iterator for BitMaskIter { 114 type Item = usize; 115 116 #[inline] next(&mut self) -> Option<usize>117 fn next(&mut self) -> Option<usize> { 118 let bit = self.0.lowest_set_bit()?; 119 self.0 = self.0.remove_lowest_bit(); 120 Some(bit) 121 } 122 } 123