1 use crate::vec::{Idx, IndexVec};
2 use arrayvec::ArrayVec;
5 use std::marker::PhantomData;
7 use std::ops::{BitAnd, BitAndAssign, BitOrAssign, Not, Range, Shl};
14 pub const WORD_BYTES: usize = mem::size_of::<Word>();
15 pub const WORD_BITS: usize = WORD_BYTES * 8;
17 /// A fixed-size bitset type with a dense representation.
19 /// NOTE: Use [`GrowableBitSet`] if you need support for resizing after creation.
21 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
24 /// All operations that involve an element will panic if the element is equal
25 /// to or greater than the domain size. All operations that involve two bitsets
26 /// will panic if the bitsets have differing domain sizes.
28 /// [`GrowableBitSet`]: struct.GrowableBitSet.html
29 #[derive(Clone, Eq, PartialEq, RustcDecodable, RustcEncodable)]
30 pub struct BitSet<T: Idx> {
33 marker: PhantomData<T>,
36 impl<T: Idx> BitSet<T> {
37 /// Creates a new, empty bitset with a given `domain_size`.
39 pub fn new_empty(domain_size: usize) -> BitSet<T> {
40 let num_words = num_words(domain_size);
41 BitSet { domain_size, words: vec![0; num_words], marker: PhantomData }
44 /// Creates a new, filled bitset with a given `domain_size`.
46 pub fn new_filled(domain_size: usize) -> BitSet<T> {
47 let num_words = num_words(domain_size);
48 let mut result = BitSet { domain_size, words: vec![!0; num_words], marker: PhantomData };
49 result.clear_excess_bits();
53 /// Gets the domain size.
54 pub fn domain_size(&self) -> usize {
58 /// Clear all elements.
60 pub fn clear(&mut self) {
61 for word in &mut self.words {
66 /// Clear excess bits in the final word.
67 fn clear_excess_bits(&mut self) {
68 let num_bits_in_final_word = self.domain_size % WORD_BITS;
69 if num_bits_in_final_word > 0 {
70 let mask = (1 << num_bits_in_final_word) - 1;
71 let final_word_idx = self.words.len() - 1;
72 self.words[final_word_idx] &= mask;
76 /// Efficiently overwrite `self` with `other`.
77 pub fn overwrite(&mut self, other: &BitSet<T>) {
78 assert!(self.domain_size == other.domain_size);
79 self.words.clone_from_slice(&other.words);
82 /// Count the number of set bits in the set.
83 pub fn count(&self) -> usize {
84 self.words.iter().map(|e| e.count_ones() as usize).sum()
87 /// Returns `true` if `self` contains `elem`.
89 pub fn contains(&self, elem: T) -> bool {
90 assert!(elem.index() < self.domain_size);
91 let (word_index, mask) = word_index_and_mask(elem);
92 (self.words[word_index] & mask) != 0
95 /// Is `self` is a (non-strict) superset of `other`?
97 pub fn superset(&self, other: &BitSet<T>) -> bool {
98 assert_eq!(self.domain_size, other.domain_size);
99 self.words.iter().zip(&other.words).all(|(a, b)| (a & b) == *b)
102 /// Is the set empty?
104 pub fn is_empty(&self) -> bool {
105 self.words.iter().all(|a| *a == 0)
108 /// Insert `elem`. Returns whether the set has changed.
110 pub fn insert(&mut self, elem: T) -> bool {
111 assert!(elem.index() < self.domain_size);
112 let (word_index, mask) = word_index_and_mask(elem);
113 let word_ref = &mut self.words[word_index];
114 let word = *word_ref;
115 let new_word = word | mask;
116 *word_ref = new_word;
120 /// Sets all bits to true.
121 pub fn insert_all(&mut self) {
122 for word in &mut self.words {
125 self.clear_excess_bits();
128 /// Returns `true` if the set has changed.
130 pub fn remove(&mut self, elem: T) -> bool {
131 assert!(elem.index() < self.domain_size);
132 let (word_index, mask) = word_index_and_mask(elem);
133 let word_ref = &mut self.words[word_index];
134 let word = *word_ref;
135 let new_word = word & !mask;
136 *word_ref = new_word;
140 /// Sets `self = self | other` and returns `true` if `self` changed
141 /// (i.e., if new bits were added).
142 pub fn union(&mut self, other: &impl UnionIntoBitSet<T>) -> bool {
143 other.union_into(self)
146 /// Sets `self = self - other` and returns `true` if `self` changed.
147 /// (i.e., if any bits were removed).
148 pub fn subtract(&mut self, other: &impl SubtractFromBitSet<T>) -> bool {
149 other.subtract_from(self)
152 /// Sets `self = self & other` and return `true` if `self` changed.
153 /// (i.e., if any bits were removed).
154 pub fn intersect(&mut self, other: &BitSet<T>) -> bool {
155 assert_eq!(self.domain_size, other.domain_size);
156 bitwise(&mut self.words, &other.words, |a, b| a & b)
159 /// Gets a slice of the underlying words.
160 pub fn words(&self) -> &[Word] {
164 /// Iterates over the indices of set bits in a sorted order.
166 pub fn iter(&self) -> BitIter<'_, T> {
167 BitIter::new(&self.words)
170 /// Duplicates the set as a hybrid set.
171 pub fn to_hybrid(&self) -> HybridBitSet<T> {
172 // Note: we currently don't bother trying to make a Sparse set.
173 HybridBitSet::Dense(self.to_owned())
176 /// Set `self = self | other`. In contrast to `union` returns `true` if the set contains at
177 /// least one bit that is not in `other` (i.e. `other` is not a superset of `self`).
179 /// This is an optimization for union of a hybrid bitset.
180 fn reverse_union_sparse(&mut self, sparse: &SparseBitSet<T>) -> bool {
181 assert!(sparse.domain_size == self.domain_size);
182 self.clear_excess_bits();
184 let mut not_already = false;
185 // Index of the current word not yet merged.
186 let mut current_index = 0;
187 // Mask of bits that came from the sparse set in the current word.
188 let mut new_bit_mask = 0;
189 for (word_index, mask) in sparse.iter().map(|x| word_index_and_mask(*x)) {
190 // Next bit is in a word not inspected yet.
191 if word_index > current_index {
192 self.words[current_index] |= new_bit_mask;
193 // Were there any bits in the old word that did not occur in the sparse set?
194 not_already |= (self.words[current_index] ^ new_bit_mask) != 0;
195 // Check all words we skipped for any set bit.
196 not_already |= self.words[current_index + 1..word_index].iter().any(|&x| x != 0);
198 current_index = word_index;
199 // Reset bit mask, no bits have been merged yet.
202 // Add bit and mark it as coming from the sparse set.
203 // self.words[word_index] |= mask;
204 new_bit_mask |= mask;
206 self.words[current_index] |= new_bit_mask;
207 // Any bits in the last inspected word that were not in the sparse set?
208 not_already |= (self.words[current_index] ^ new_bit_mask) != 0;
209 // Any bits in the tail? Note `clear_excess_bits` before.
210 not_already |= self.words[current_index + 1..].iter().any(|&x| x != 0);
216 /// This is implemented by all the bitsets so that BitSet::union() can be
217 /// passed any type of bitset.
218 pub trait UnionIntoBitSet<T: Idx> {
219 // Performs `other = other | self`.
220 fn union_into(&self, other: &mut BitSet<T>) -> bool;
223 /// This is implemented by all the bitsets so that BitSet::subtract() can be
224 /// passed any type of bitset.
225 pub trait SubtractFromBitSet<T: Idx> {
226 // Performs `other = other - self`.
227 fn subtract_from(&self, other: &mut BitSet<T>) -> bool;
230 impl<T: Idx> UnionIntoBitSet<T> for BitSet<T> {
231 fn union_into(&self, other: &mut BitSet<T>) -> bool {
232 assert_eq!(self.domain_size, other.domain_size);
233 bitwise(&mut other.words, &self.words, |a, b| a | b)
237 impl<T: Idx> SubtractFromBitSet<T> for BitSet<T> {
238 fn subtract_from(&self, other: &mut BitSet<T>) -> bool {
239 assert_eq!(self.domain_size, other.domain_size);
240 bitwise(&mut other.words, &self.words, |a, b| a & !b)
244 impl<T: Idx> fmt::Debug for BitSet<T> {
245 fn fmt(&self, w: &mut fmt::Formatter<'_>) -> fmt::Result {
246 w.debug_list().entries(self.iter()).finish()
250 impl<T: Idx> ToString for BitSet<T> {
251 fn to_string(&self) -> String {
252 let mut result = String::new();
255 // Note: this is a little endian printout of bytes.
257 // i tracks how many bits we have printed so far.
259 for word in &self.words {
260 let mut word = *word;
261 for _ in 0..WORD_BYTES {
262 // for each byte in `word`:
263 let remain = self.domain_size - i;
264 // If less than a byte remains, then mask just that many bits.
265 let mask = if remain <= 8 { (1 << remain) - 1 } else { 0xFF };
266 assert!(mask <= 0xFF);
267 let byte = word & mask;
269 result.push_str(&format!("{}{:02x}", sep, byte));
286 pub struct BitIter<'a, T: Idx> {
287 /// A copy of the current word, but with any already-visited bits cleared.
288 /// (This lets us use `trailing_zeros()` to find the next set bit.) When it
289 /// is reduced to 0, we move onto the next word.
292 /// The offset (measured in bits) of the current word.
295 /// Underlying iterator over the words.
296 iter: slice::Iter<'a, Word>,
298 marker: PhantomData<T>,
301 impl<'a, T: Idx> BitIter<'a, T> {
303 fn new(words: &'a [Word]) -> BitIter<'a, T> {
304 // We initialize `word` and `offset` to degenerate values. On the first
305 // call to `next()` we will fall through to getting the first word from
306 // `iter`, which sets `word` to the first word (if there is one) and
307 // `offset` to 0. Doing it this way saves us from having to maintain
308 // additional state about whether we have started.
311 offset: usize::MAX - (WORD_BITS - 1),
318 impl<'a, T: Idx> Iterator for BitIter<'a, T> {
320 fn next(&mut self) -> Option<T> {
323 // Get the position of the next set bit in the current word,
324 // then clear the bit.
325 let bit_pos = self.word.trailing_zeros() as usize;
326 let bit = 1 << bit_pos;
328 return Some(T::new(bit_pos + self.offset));
331 // Move onto the next word. `wrapping_add()` is needed to handle
332 // the degenerate initial value given to `offset` in `new()`.
333 let word = self.iter.next()?;
335 self.offset = self.offset.wrapping_add(WORD_BITS);
341 fn bitwise<Op>(out_vec: &mut [Word], in_vec: &[Word], op: Op) -> bool
343 Op: Fn(Word, Word) -> Word,
345 assert_eq!(out_vec.len(), in_vec.len());
346 let mut changed = false;
347 for (out_elem, in_elem) in out_vec.iter_mut().zip(in_vec.iter()) {
348 let old_val = *out_elem;
349 let new_val = op(old_val, *in_elem);
351 changed |= old_val != new_val;
356 const SPARSE_MAX: usize = 8;
358 /// A fixed-size bitset type with a sparse representation and a maximum of
359 /// `SPARSE_MAX` elements. The elements are stored as a sorted `ArrayVec` with
362 /// This type is used by `HybridBitSet`; do not use directly.
363 #[derive(Clone, Debug)]
364 pub struct SparseBitSet<T: Idx> {
366 elems: ArrayVec<[T; SPARSE_MAX]>,
369 impl<T: Idx> SparseBitSet<T> {
370 fn new_empty(domain_size: usize) -> Self {
371 SparseBitSet { domain_size, elems: ArrayVec::new() }
374 fn len(&self) -> usize {
378 fn is_empty(&self) -> bool {
379 self.elems.len() == 0
382 fn contains(&self, elem: T) -> bool {
383 assert!(elem.index() < self.domain_size);
384 self.elems.contains(&elem)
387 fn insert(&mut self, elem: T) -> bool {
388 assert!(elem.index() < self.domain_size);
389 let changed = if let Some(i) = self.elems.iter().position(|&e| e >= elem) {
390 if self.elems[i] == elem {
391 // `elem` is already in the set.
394 // `elem` is smaller than one or more existing elements.
395 self.elems.insert(i, elem);
399 // `elem` is larger than all existing elements.
400 self.elems.push(elem);
403 assert!(self.len() <= SPARSE_MAX);
407 fn remove(&mut self, elem: T) -> bool {
408 assert!(elem.index() < self.domain_size);
409 if let Some(i) = self.elems.iter().position(|&e| e == elem) {
410 self.elems.remove(i);
417 fn to_dense(&self) -> BitSet<T> {
418 let mut dense = BitSet::new_empty(self.domain_size);
419 for elem in self.elems.iter() {
425 fn iter(&self) -> slice::Iter<'_, T> {
430 impl<T: Idx> UnionIntoBitSet<T> for SparseBitSet<T> {
431 fn union_into(&self, other: &mut BitSet<T>) -> bool {
432 assert_eq!(self.domain_size, other.domain_size);
433 let mut changed = false;
434 for elem in self.iter() {
435 changed |= other.insert(*elem);
441 impl<T: Idx> SubtractFromBitSet<T> for SparseBitSet<T> {
442 fn subtract_from(&self, other: &mut BitSet<T>) -> bool {
443 assert_eq!(self.domain_size, other.domain_size);
444 let mut changed = false;
445 for elem in self.iter() {
446 changed |= other.remove(*elem);
452 /// A fixed-size bitset type with a hybrid representation: sparse when there
453 /// are up to a `SPARSE_MAX` elements in the set, but dense when there are more
454 /// than `SPARSE_MAX`.
456 /// This type is especially efficient for sets that typically have a small
457 /// number of elements, but a large `domain_size`, and are cleared frequently.
459 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
462 /// All operations that involve an element will panic if the element is equal
463 /// to or greater than the domain size. All operations that involve two bitsets
464 /// will panic if the bitsets have differing domain sizes.
465 #[derive(Clone, Debug)]
466 pub enum HybridBitSet<T: Idx> {
467 Sparse(SparseBitSet<T>),
471 impl<T: Idx> HybridBitSet<T> {
472 pub fn new_empty(domain_size: usize) -> Self {
473 HybridBitSet::Sparse(SparseBitSet::new_empty(domain_size))
476 fn domain_size(&self) -> usize {
478 HybridBitSet::Sparse(sparse) => sparse.domain_size,
479 HybridBitSet::Dense(dense) => dense.domain_size,
483 pub fn clear(&mut self) {
484 let domain_size = self.domain_size();
485 *self = HybridBitSet::new_empty(domain_size);
488 pub fn contains(&self, elem: T) -> bool {
490 HybridBitSet::Sparse(sparse) => sparse.contains(elem),
491 HybridBitSet::Dense(dense) => dense.contains(elem),
495 pub fn superset(&self, other: &HybridBitSet<T>) -> bool {
496 match (self, other) {
497 (HybridBitSet::Dense(self_dense), HybridBitSet::Dense(other_dense)) => {
498 self_dense.superset(other_dense)
501 assert!(self.domain_size() == other.domain_size());
502 other.iter().all(|elem| self.contains(elem))
507 pub fn is_empty(&self) -> bool {
509 HybridBitSet::Sparse(sparse) => sparse.is_empty(),
510 HybridBitSet::Dense(dense) => dense.is_empty(),
514 pub fn insert(&mut self, elem: T) -> bool {
515 // No need to check `elem` against `self.domain_size` here because all
516 // the match cases check it, one way or another.
518 HybridBitSet::Sparse(sparse) if sparse.len() < SPARSE_MAX => {
519 // The set is sparse and has space for `elem`.
522 HybridBitSet::Sparse(sparse) if sparse.contains(elem) => {
523 // The set is sparse and does not have space for `elem`, but
524 // that doesn't matter because `elem` is already present.
527 HybridBitSet::Sparse(sparse) => {
528 // The set is sparse and full. Convert to a dense set.
529 let mut dense = sparse.to_dense();
530 let changed = dense.insert(elem);
532 *self = HybridBitSet::Dense(dense);
535 HybridBitSet::Dense(dense) => dense.insert(elem),
539 pub fn insert_all(&mut self) {
540 let domain_size = self.domain_size();
542 HybridBitSet::Sparse(_) => {
543 *self = HybridBitSet::Dense(BitSet::new_filled(domain_size));
545 HybridBitSet::Dense(dense) => dense.insert_all(),
549 pub fn remove(&mut self, elem: T) -> bool {
550 // Note: we currently don't bother going from Dense back to Sparse.
552 HybridBitSet::Sparse(sparse) => sparse.remove(elem),
553 HybridBitSet::Dense(dense) => dense.remove(elem),
557 pub fn union(&mut self, other: &HybridBitSet<T>) -> bool {
559 HybridBitSet::Sparse(self_sparse) => {
561 HybridBitSet::Sparse(other_sparse) => {
562 // Both sets are sparse. Add the elements in
563 // `other_sparse` to `self` one at a time. This
564 // may or may not cause `self` to be densified.
565 assert_eq!(self.domain_size(), other.domain_size());
566 let mut changed = false;
567 for elem in other_sparse.iter() {
568 changed |= self.insert(*elem);
572 HybridBitSet::Dense(other_dense) => {
573 // `self` is sparse and `other` is dense. To
574 // merge them, we have two available strategies:
575 // * Densify `self` then merge other
576 // * Clone other then integrate bits from `self`
577 // The second strategy requires dedicated method
578 // since the usual `union` returns the wrong
579 // result. In the dedicated case the computation
580 // is slightly faster if the bits of the sparse
581 // bitset map to only few words of the dense
582 // representation, i.e. indices are near each
585 // Benchmarking seems to suggest that the second
586 // option is worth it.
587 let mut new_dense = other_dense.clone();
588 let changed = new_dense.reverse_union_sparse(self_sparse);
589 *self = HybridBitSet::Dense(new_dense);
595 HybridBitSet::Dense(self_dense) => self_dense.union(other),
599 /// Converts to a dense set, consuming itself in the process.
600 pub fn to_dense(self) -> BitSet<T> {
602 HybridBitSet::Sparse(sparse) => sparse.to_dense(),
603 HybridBitSet::Dense(dense) => dense,
607 pub fn iter(&self) -> HybridIter<'_, T> {
609 HybridBitSet::Sparse(sparse) => HybridIter::Sparse(sparse.iter()),
610 HybridBitSet::Dense(dense) => HybridIter::Dense(dense.iter()),
615 impl<T: Idx> UnionIntoBitSet<T> for HybridBitSet<T> {
616 fn union_into(&self, other: &mut BitSet<T>) -> bool {
618 HybridBitSet::Sparse(sparse) => sparse.union_into(other),
619 HybridBitSet::Dense(dense) => dense.union_into(other),
624 impl<T: Idx> SubtractFromBitSet<T> for HybridBitSet<T> {
625 fn subtract_from(&self, other: &mut BitSet<T>) -> bool {
627 HybridBitSet::Sparse(sparse) => sparse.subtract_from(other),
628 HybridBitSet::Dense(dense) => dense.subtract_from(other),
633 pub enum HybridIter<'a, T: Idx> {
634 Sparse(slice::Iter<'a, T>),
635 Dense(BitIter<'a, T>),
638 impl<'a, T: Idx> Iterator for HybridIter<'a, T> {
641 fn next(&mut self) -> Option<T> {
643 HybridIter::Sparse(sparse) => sparse.next().copied(),
644 HybridIter::Dense(dense) => dense.next(),
649 /// A resizable bitset type with a dense representation.
651 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
654 /// All operations that involve an element will panic if the element is equal
655 /// to or greater than the domain size.
656 #[derive(Clone, Debug, PartialEq)]
657 pub struct GrowableBitSet<T: Idx> {
661 impl<T: Idx> GrowableBitSet<T> {
662 /// Ensure that the set can hold at least `min_domain_size` elements.
663 pub fn ensure(&mut self, min_domain_size: usize) {
664 if self.bit_set.domain_size < min_domain_size {
665 self.bit_set.domain_size = min_domain_size;
668 let min_num_words = num_words(min_domain_size);
669 if self.bit_set.words.len() < min_num_words {
670 self.bit_set.words.resize(min_num_words, 0)
674 pub fn new_empty() -> GrowableBitSet<T> {
675 GrowableBitSet { bit_set: BitSet::new_empty(0) }
678 pub fn with_capacity(capacity: usize) -> GrowableBitSet<T> {
679 GrowableBitSet { bit_set: BitSet::new_empty(capacity) }
682 /// Returns `true` if the set has changed.
684 pub fn insert(&mut self, elem: T) -> bool {
685 self.ensure(elem.index() + 1);
686 self.bit_set.insert(elem)
690 pub fn contains(&self, elem: T) -> bool {
691 let (word_index, mask) = word_index_and_mask(elem);
692 if let Some(word) = self.bit_set.words.get(word_index) { (word & mask) != 0 } else { false }
696 /// A fixed-size 2D bit matrix type with a dense representation.
698 /// `R` and `C` are index types used to identify rows and columns respectively;
699 /// typically newtyped `usize` wrappers, but they can also just be `usize`.
701 /// All operations that involve a row and/or column index will panic if the
702 /// index exceeds the relevant bound.
703 #[derive(Clone, Eq, PartialEq, RustcDecodable, RustcEncodable)]
704 pub struct BitMatrix<R: Idx, C: Idx> {
708 marker: PhantomData<(R, C)>,
711 impl<R: Idx, C: Idx> BitMatrix<R, C> {
712 /// Creates a new `rows x columns` matrix, initially empty.
713 pub fn new(num_rows: usize, num_columns: usize) -> BitMatrix<R, C> {
714 // For every element, we need one bit for every other
715 // element. Round up to an even number of words.
716 let words_per_row = num_words(num_columns);
720 words: vec![0; num_rows * words_per_row],
725 /// Creates a new matrix, with `row` used as the value for every row.
726 pub fn from_row_n(row: &BitSet<C>, num_rows: usize) -> BitMatrix<R, C> {
727 let num_columns = row.domain_size();
728 let words_per_row = num_words(num_columns);
729 assert_eq!(words_per_row, row.words().len());
733 words: iter::repeat(row.words()).take(num_rows).flatten().cloned().collect(),
738 pub fn rows(&self) -> impl Iterator<Item = R> {
739 (0..self.num_rows).map(R::new)
742 /// The range of bits for a given row.
743 fn range(&self, row: R) -> (usize, usize) {
744 let words_per_row = num_words(self.num_columns);
745 let start = row.index() * words_per_row;
746 (start, start + words_per_row)
749 /// Sets the cell at `(row, column)` to true. Put another way, insert
750 /// `column` to the bitset for `row`.
752 /// Returns `true` if this changed the matrix.
753 pub fn insert(&mut self, row: R, column: C) -> bool {
754 assert!(row.index() < self.num_rows && column.index() < self.num_columns);
755 let (start, _) = self.range(row);
756 let (word_index, mask) = word_index_and_mask(column);
757 let words = &mut self.words[..];
758 let word = words[start + word_index];
759 let new_word = word | mask;
760 words[start + word_index] = new_word;
764 /// Do the bits from `row` contain `column`? Put another way, is
765 /// the matrix cell at `(row, column)` true? Put yet another way,
766 /// if the matrix represents (transitive) reachability, can
767 /// `row` reach `column`?
768 pub fn contains(&self, row: R, column: C) -> bool {
769 assert!(row.index() < self.num_rows && column.index() < self.num_columns);
770 let (start, _) = self.range(row);
771 let (word_index, mask) = word_index_and_mask(column);
772 (self.words[start + word_index] & mask) != 0
775 /// Returns those indices that are true in rows `a` and `b`. This
776 /// is an *O*(*n*) operation where *n* is the number of elements
777 /// (somewhat independent from the actual size of the
778 /// intersection, in particular).
779 pub fn intersect_rows(&self, row1: R, row2: R) -> Vec<C> {
780 assert!(row1.index() < self.num_rows && row2.index() < self.num_rows);
781 let (row1_start, row1_end) = self.range(row1);
782 let (row2_start, row2_end) = self.range(row2);
783 let mut result = Vec::with_capacity(self.num_columns);
784 for (base, (i, j)) in (row1_start..row1_end).zip(row2_start..row2_end).enumerate() {
785 let mut v = self.words[i] & self.words[j];
786 for bit in 0..WORD_BITS {
791 result.push(C::new(base * WORD_BITS + bit));
799 /// Adds the bits from row `read` to the bits from row `write`, and
800 /// returns `true` if anything changed.
802 /// This is used when computing transitive reachability because if
803 /// you have an edge `write -> read`, because in that case
804 /// `write` can reach everything that `read` can (and
805 /// potentially more).
806 pub fn union_rows(&mut self, read: R, write: R) -> bool {
807 assert!(read.index() < self.num_rows && write.index() < self.num_rows);
808 let (read_start, read_end) = self.range(read);
809 let (write_start, write_end) = self.range(write);
810 let words = &mut self.words[..];
811 let mut changed = false;
812 for (read_index, write_index) in (read_start..read_end).zip(write_start..write_end) {
813 let word = words[write_index];
814 let new_word = word | words[read_index];
815 words[write_index] = new_word;
816 changed |= word != new_word;
821 /// Adds the bits from `with` to the bits from row `write`, and
822 /// returns `true` if anything changed.
823 pub fn union_row_with(&mut self, with: &BitSet<C>, write: R) -> bool {
824 assert!(write.index() < self.num_rows);
825 assert_eq!(with.domain_size(), self.num_columns);
826 let (write_start, write_end) = self.range(write);
827 let mut changed = false;
828 for (read_index, write_index) in (0..with.words().len()).zip(write_start..write_end) {
829 let word = self.words[write_index];
830 let new_word = word | with.words()[read_index];
831 self.words[write_index] = new_word;
832 changed |= word != new_word;
837 /// Sets every cell in `row` to true.
838 pub fn insert_all_into_row(&mut self, row: R) {
839 assert!(row.index() < self.num_rows);
840 let (start, end) = self.range(row);
841 let words = &mut self.words[..];
842 for index in start..end {
845 self.clear_excess_bits(row);
848 /// Clear excess bits in the final word of the row.
849 fn clear_excess_bits(&mut self, row: R) {
850 let num_bits_in_final_word = self.num_columns % WORD_BITS;
851 if num_bits_in_final_word > 0 {
852 let mask = (1 << num_bits_in_final_word) - 1;
853 let (_, end) = self.range(row);
854 let final_word_idx = end - 1;
855 self.words[final_word_idx] &= mask;
859 /// Gets a slice of the underlying words.
860 pub fn words(&self) -> &[Word] {
864 /// Iterates through all the columns set to true in a given row of
866 pub fn iter(&self, row: R) -> BitIter<'_, C> {
867 assert!(row.index() < self.num_rows);
868 let (start, end) = self.range(row);
869 BitIter::new(&self.words[start..end])
872 /// Returns the number of elements in `row`.
873 pub fn count(&self, row: R) -> usize {
874 let (start, end) = self.range(row);
875 self.words[start..end].iter().map(|e| e.count_ones() as usize).sum()
879 impl<R: Idx, C: Idx> fmt::Debug for BitMatrix<R, C> {
880 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
881 /// Forces its contents to print in regular mode instead of alternate mode.
882 struct OneLinePrinter<T>(T);
883 impl<T: fmt::Debug> fmt::Debug for OneLinePrinter<T> {
884 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
885 write!(fmt, "{:?}", self.0)
889 write!(fmt, "BitMatrix({}x{}) ", self.num_rows, self.num_columns)?;
890 let items = self.rows().flat_map(|r| self.iter(r).map(move |c| (r, c)));
891 fmt.debug_set().entries(items.map(OneLinePrinter)).finish()
895 /// A fixed-column-size, variable-row-size 2D bit matrix with a moderately
896 /// sparse representation.
898 /// Initially, every row has no explicit representation. If any bit within a
899 /// row is set, the entire row is instantiated as `Some(<HybridBitSet>)`.
900 /// Furthermore, any previously uninstantiated rows prior to it will be
901 /// instantiated as `None`. Those prior rows may themselves become fully
902 /// instantiated later on if any of their bits are set.
904 /// `R` and `C` are index types used to identify rows and columns respectively;
905 /// typically newtyped `usize` wrappers, but they can also just be `usize`.
906 #[derive(Clone, Debug)]
907 pub struct SparseBitMatrix<R, C>
913 rows: IndexVec<R, Option<HybridBitSet<C>>>,
916 impl<R: Idx, C: Idx> SparseBitMatrix<R, C> {
917 /// Creates a new empty sparse bit matrix with no rows or columns.
918 pub fn new(num_columns: usize) -> Self {
919 Self { num_columns, rows: IndexVec::new() }
922 fn ensure_row(&mut self, row: R) -> &mut HybridBitSet<C> {
923 // Instantiate any missing rows up to and including row `row` with an
924 // empty HybridBitSet.
925 self.rows.ensure_contains_elem(row, || None);
927 // Then replace row `row` with a full HybridBitSet if necessary.
928 let num_columns = self.num_columns;
929 self.rows[row].get_or_insert_with(|| HybridBitSet::new_empty(num_columns))
932 /// Sets the cell at `(row, column)` to true. Put another way, insert
933 /// `column` to the bitset for `row`.
935 /// Returns `true` if this changed the matrix.
936 pub fn insert(&mut self, row: R, column: C) -> bool {
937 self.ensure_row(row).insert(column)
940 /// Do the bits from `row` contain `column`? Put another way, is
941 /// the matrix cell at `(row, column)` true? Put yet another way,
942 /// if the matrix represents (transitive) reachability, can
943 /// `row` reach `column`?
944 pub fn contains(&self, row: R, column: C) -> bool {
945 self.row(row).map_or(false, |r| r.contains(column))
948 /// Adds the bits from row `read` to the bits from row `write`, and
949 /// returns `true` if anything changed.
951 /// This is used when computing transitive reachability because if
952 /// you have an edge `write -> read`, because in that case
953 /// `write` can reach everything that `read` can (and
954 /// potentially more).
955 pub fn union_rows(&mut self, read: R, write: R) -> bool {
956 if read == write || self.row(read).is_none() {
960 self.ensure_row(write);
961 if let (Some(read_row), Some(write_row)) = self.rows.pick2_mut(read, write) {
962 write_row.union(read_row)
968 /// Union a row, `from`, into the `into` row.
969 pub fn union_into_row(&mut self, into: R, from: &HybridBitSet<C>) -> bool {
970 self.ensure_row(into).union(from)
973 /// Insert all bits in the given row.
974 pub fn insert_all_into_row(&mut self, row: R) {
975 self.ensure_row(row).insert_all();
978 pub fn rows(&self) -> impl Iterator<Item = R> {
982 /// Iterates through all the columns set to true in a given row of
984 pub fn iter<'a>(&'a self, row: R) -> impl Iterator<Item = C> + 'a {
985 self.row(row).into_iter().flat_map(|r| r.iter())
988 pub fn row(&self, row: R) -> Option<&HybridBitSet<C>> {
989 if let Some(Some(row)) = self.rows.get(row) { Some(row) } else { None }
994 fn num_words<T: Idx>(domain_size: T) -> usize {
995 (domain_size.index() + WORD_BITS - 1) / WORD_BITS
999 fn word_index_and_mask<T: Idx>(elem: T) -> (usize, Word) {
1000 let elem = elem.index();
1001 let word_index = elem / WORD_BITS;
1002 let mask = 1 << (elem % WORD_BITS);
1006 /// Integral type used to represent the bit set.
1007 pub trait FiniteBitSetTy:
1008 BitAnd<Output = Self>
1014 + Not<Output = Self>
1018 /// Size of the domain representable by this type, e.g. 64 for `u64`.
1019 const DOMAIN_SIZE: u32;
1021 /// Value which represents the `FiniteBitSet` having every bit set.
1023 /// Value which represents the `FiniteBitSet` having no bits set.
1026 /// Value for one as the integral type.
1028 /// Value for zero as the integral type.
1031 /// Perform a checked left shift on the integral type.
1032 fn checked_shl(self, rhs: u32) -> Option<Self>;
1033 /// Perform a checked right shift on the integral type.
1034 fn checked_shr(self, rhs: u32) -> Option<Self>;
1037 impl FiniteBitSetTy for u32 {
1038 const DOMAIN_SIZE: u32 = 32;
1040 const FILLED: Self = Self::MAX;
1041 const EMPTY: Self = Self::MIN;
1043 const ONE: Self = 1u32;
1044 const ZERO: Self = 0u32;
1046 fn checked_shl(self, rhs: u32) -> Option<Self> {
1047 self.checked_shl(rhs)
1050 fn checked_shr(self, rhs: u32) -> Option<Self> {
1051 self.checked_shr(rhs)
1055 impl std::fmt::Debug for FiniteBitSet<u32> {
1056 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1057 write!(f, "{:032b}", self.0)
1061 impl FiniteBitSetTy for u64 {
1062 const DOMAIN_SIZE: u32 = 64;
1064 const FILLED: Self = Self::MAX;
1065 const EMPTY: Self = Self::MIN;
1067 const ONE: Self = 1u64;
1068 const ZERO: Self = 0u64;
1070 fn checked_shl(self, rhs: u32) -> Option<Self> {
1071 self.checked_shl(rhs)
1074 fn checked_shr(self, rhs: u32) -> Option<Self> {
1075 self.checked_shr(rhs)
1079 impl std::fmt::Debug for FiniteBitSet<u64> {
1080 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1081 write!(f, "{:064b}", self.0)
1085 impl FiniteBitSetTy for u128 {
1086 const DOMAIN_SIZE: u32 = 128;
1088 const FILLED: Self = Self::MAX;
1089 const EMPTY: Self = Self::MIN;
1091 const ONE: Self = 1u128;
1092 const ZERO: Self = 0u128;
1094 fn checked_shl(self, rhs: u32) -> Option<Self> {
1095 self.checked_shl(rhs)
1098 fn checked_shr(self, rhs: u32) -> Option<Self> {
1099 self.checked_shr(rhs)
1103 impl std::fmt::Debug for FiniteBitSet<u128> {
1104 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1105 write!(f, "{:0128b}", self.0)
1109 /// A fixed-sized bitset type represented by an integer type. Indices outwith than the range
1110 /// representable by `T` are considered set.
1111 #[derive(Copy, Clone, Eq, PartialEq, RustcDecodable, RustcEncodable)]
1112 pub struct FiniteBitSet<T: FiniteBitSetTy>(pub T);
1114 impl<T: FiniteBitSetTy> FiniteBitSet<T> {
1115 /// Creates a new, empty bitset.
1116 pub fn new_empty() -> Self {
1120 /// Sets the `index`th bit.
1121 pub fn set(&mut self, index: u32) {
1122 self.0 |= T::ONE.checked_shl(index).unwrap_or(T::ZERO);
1125 /// Unsets the `index`th bit.
1126 pub fn clear(&mut self, index: u32) {
1127 self.0 &= !T::ONE.checked_shl(index).unwrap_or(T::ZERO);
1130 /// Sets the `i`th to `j`th bits.
1131 pub fn set_range(&mut self, range: Range<u32>) {
1132 let bits = T::FILLED
1133 .checked_shl(range.end - range.start)
1136 .checked_shl(range.start)
1137 .unwrap_or(T::ZERO);
1141 /// Is the set empty?
1142 pub fn is_empty(&self) -> bool {
1146 /// Returns the domain size of the bitset.
1147 pub fn within_domain(&self, index: u32) -> bool {
1148 index < T::DOMAIN_SIZE
1151 /// Returns if the `index`th bit is set.
1152 pub fn contains(&self, index: u32) -> Option<bool> {
1153 self.within_domain(index)
1154 .then(|| ((self.0.checked_shr(index).unwrap_or(T::ONE)) & T::ONE) == T::ONE)
1158 impl<T: FiniteBitSetTy> Default for FiniteBitSet<T> {
1159 fn default() -> Self {