1 use crate::vec::{Idx, IndexVec};
2 use arrayvec::ArrayVec;
5 use std::marker::PhantomData;
7 use std::ops::{BitAnd, BitAndAssign, BitOrAssign, Bound, Not, Range, RangeBounds, Shl};
11 use rustc_macros::{Decodable, Encodable};
19 const WORD_BYTES: usize = mem::size_of::<Word>();
20 const WORD_BITS: usize = WORD_BYTES * 8;
22 // The choice of chunk size has some trade-offs.
24 // A big chunk size tends to favour cases where many large `ChunkedBitSet`s are
25 // present, because they require fewer `Chunk`s, reducing the number of
26 // allocations and reducing peak memory usage. Also, fewer chunk operations are
27 // required, though more of them might be `Mixed`.
29 // A small chunk size tends to favour cases where many small `ChunkedBitSet`s
30 // are present, because less space is wasted at the end of the final chunk (if
32 const CHUNK_WORDS: usize = 32;
33 const CHUNK_BITS: usize = CHUNK_WORDS * WORD_BITS; // 2048 bits
35 /// ChunkSize is small to keep `Chunk` small. The static assertion ensures it's
38 const _: () = assert!(CHUNK_BITS <= ChunkSize::MAX as usize);
40 pub trait BitRelations<Rhs> {
41 fn union(&mut self, other: &Rhs) -> bool;
42 fn subtract(&mut self, other: &Rhs) -> bool;
43 fn intersect(&mut self, other: &Rhs) -> bool;
47 fn inclusive_start_end<T: Idx>(
48 range: impl RangeBounds<T>,
50 ) -> Option<(usize, usize)> {
51 // Both start and end are inclusive.
52 let start = match range.start_bound().cloned() {
53 Bound::Included(start) => start.index(),
54 Bound::Excluded(start) => start.index() + 1,
55 Bound::Unbounded => 0,
57 let end = match range.end_bound().cloned() {
58 Bound::Included(end) => end.index(),
59 Bound::Excluded(end) => end.index().checked_sub(1)?,
60 Bound::Unbounded => domain - 1,
62 assert!(end < domain);
69 macro_rules! bit_relations_inherent_impls {
71 /// Sets `self = self | other` and returns `true` if `self` changed
72 /// (i.e., if new bits were added).
73 pub fn union<Rhs>(&mut self, other: &Rhs) -> bool
75 Self: BitRelations<Rhs>,
77 <Self as BitRelations<Rhs>>::union(self, other)
80 /// Sets `self = self - other` and returns `true` if `self` changed.
81 /// (i.e., if any bits were removed).
82 pub fn subtract<Rhs>(&mut self, other: &Rhs) -> bool
84 Self: BitRelations<Rhs>,
86 <Self as BitRelations<Rhs>>::subtract(self, other)
89 /// Sets `self = self & other` and return `true` if `self` changed.
90 /// (i.e., if any bits were removed).
91 pub fn intersect<Rhs>(&mut self, other: &Rhs) -> bool
93 Self: BitRelations<Rhs>,
95 <Self as BitRelations<Rhs>>::intersect(self, other)
100 /// A fixed-size bitset type with a dense representation.
102 /// NOTE: Use [`GrowableBitSet`] if you need support for resizing after creation.
104 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
107 /// All operations that involve an element will panic if the element is equal
108 /// to or greater than the domain size. All operations that involve two bitsets
109 /// will panic if the bitsets have differing domain sizes.
111 #[derive(Eq, PartialEq, Hash, Decodable, Encodable)]
112 pub struct BitSet<T> {
115 marker: PhantomData<T>,
119 /// Gets the domain size.
120 pub fn domain_size(&self) -> usize {
125 impl<T: Idx> BitSet<T> {
126 /// Creates a new, empty bitset with a given `domain_size`.
128 pub fn new_empty(domain_size: usize) -> BitSet<T> {
129 let num_words = num_words(domain_size);
130 BitSet { domain_size, words: vec![0; num_words], marker: PhantomData }
133 /// Creates a new, filled bitset with a given `domain_size`.
135 pub fn new_filled(domain_size: usize) -> BitSet<T> {
136 let num_words = num_words(domain_size);
137 let mut result = BitSet { domain_size, words: vec![!0; num_words], marker: PhantomData };
138 result.clear_excess_bits();
142 /// Clear all elements.
144 pub fn clear(&mut self) {
148 /// Clear excess bits in the final word.
149 fn clear_excess_bits(&mut self) {
150 clear_excess_bits_in_final_word(self.domain_size, &mut self.words);
153 /// Count the number of set bits in the set.
154 pub fn count(&self) -> usize {
155 self.words.iter().map(|e| e.count_ones() as usize).sum()
158 /// Returns `true` if `self` contains `elem`.
160 pub fn contains(&self, elem: T) -> bool {
161 assert!(elem.index() < self.domain_size);
162 let (word_index, mask) = word_index_and_mask(elem);
163 (self.words[word_index] & mask) != 0
166 /// Is `self` is a (non-strict) superset of `other`?
168 pub fn superset(&self, other: &BitSet<T>) -> bool {
169 assert_eq!(self.domain_size, other.domain_size);
170 self.words.iter().zip(&other.words).all(|(a, b)| (a & b) == *b)
173 /// Is the set empty?
175 pub fn is_empty(&self) -> bool {
176 self.words.iter().all(|a| *a == 0)
179 /// Insert `elem`. Returns whether the set has changed.
181 pub fn insert(&mut self, elem: T) -> bool {
182 assert!(elem.index() < self.domain_size);
183 let (word_index, mask) = word_index_and_mask(elem);
184 let word_ref = &mut self.words[word_index];
185 let word = *word_ref;
186 let new_word = word | mask;
187 *word_ref = new_word;
192 pub fn insert_range(&mut self, elems: impl RangeBounds<T>) {
193 let Some((start, end)) = inclusive_start_end(elems, self.domain_size) else {
197 let (start_word_index, start_mask) = word_index_and_mask(start);
198 let (end_word_index, end_mask) = word_index_and_mask(end);
200 // Set all words in between start and end (exclusively of both).
201 for word_index in (start_word_index + 1)..end_word_index {
202 self.words[word_index] = !0;
205 if start_word_index != end_word_index {
206 // Start and end are in different words, so we handle each in turn.
208 // We set all leading bits. This includes the start_mask bit.
209 self.words[start_word_index] |= !(start_mask - 1);
210 // And all trailing bits (i.e. from 0..=end) in the end word,
211 // including the end.
212 self.words[end_word_index] |= end_mask | end_mask - 1;
214 self.words[start_word_index] |= end_mask | (end_mask - start_mask);
218 /// Sets all bits to true.
219 pub fn insert_all(&mut self) {
221 self.clear_excess_bits();
224 /// Returns `true` if the set has changed.
226 pub fn remove(&mut self, elem: T) -> bool {
227 assert!(elem.index() < self.domain_size);
228 let (word_index, mask) = word_index_and_mask(elem);
229 let word_ref = &mut self.words[word_index];
230 let word = *word_ref;
231 let new_word = word & !mask;
232 *word_ref = new_word;
236 /// Gets a slice of the underlying words.
237 pub fn words(&self) -> &[Word] {
241 /// Iterates over the indices of set bits in a sorted order.
243 pub fn iter(&self) -> BitIter<'_, T> {
244 BitIter::new(&self.words)
247 /// Duplicates the set as a hybrid set.
248 pub fn to_hybrid(&self) -> HybridBitSet<T> {
249 // Note: we currently don't bother trying to make a Sparse set.
250 HybridBitSet::Dense(self.to_owned())
253 /// Set `self = self | other`. In contrast to `union` returns `true` if the set contains at
254 /// least one bit that is not in `other` (i.e. `other` is not a superset of `self`).
256 /// This is an optimization for union of a hybrid bitset.
257 fn reverse_union_sparse(&mut self, sparse: &SparseBitSet<T>) -> bool {
258 assert!(sparse.domain_size == self.domain_size);
259 self.clear_excess_bits();
261 let mut not_already = false;
262 // Index of the current word not yet merged.
263 let mut current_index = 0;
264 // Mask of bits that came from the sparse set in the current word.
265 let mut new_bit_mask = 0;
266 for (word_index, mask) in sparse.iter().map(|x| word_index_and_mask(*x)) {
267 // Next bit is in a word not inspected yet.
268 if word_index > current_index {
269 self.words[current_index] |= new_bit_mask;
270 // Were there any bits in the old word that did not occur in the sparse set?
271 not_already |= (self.words[current_index] ^ new_bit_mask) != 0;
272 // Check all words we skipped for any set bit.
273 not_already |= self.words[current_index + 1..word_index].iter().any(|&x| x != 0);
275 current_index = word_index;
276 // Reset bit mask, no bits have been merged yet.
279 // Add bit and mark it as coming from the sparse set.
280 // self.words[word_index] |= mask;
281 new_bit_mask |= mask;
283 self.words[current_index] |= new_bit_mask;
284 // Any bits in the last inspected word that were not in the sparse set?
285 not_already |= (self.words[current_index] ^ new_bit_mask) != 0;
286 // Any bits in the tail? Note `clear_excess_bits` before.
287 not_already |= self.words[current_index + 1..].iter().any(|&x| x != 0);
292 fn last_set_in(&self, range: impl RangeBounds<T>) -> Option<T> {
293 let (start, end) = inclusive_start_end(range, self.domain_size)?;
294 let (start_word_index, _) = word_index_and_mask(start);
295 let (end_word_index, end_mask) = word_index_and_mask(end);
297 let end_word = self.words[end_word_index] & (end_mask | (end_mask - 1));
299 let pos = max_bit(end_word) + WORD_BITS * end_word_index;
301 return Some(T::new(pos));
305 // We exclude end_word_index from the range here, because we don't want
306 // to limit ourselves to *just* the last word: the bits set it in may be
307 // after `end`, so it may not work out.
308 if let Some(offset) =
309 self.words[start_word_index..end_word_index].iter().rposition(|&w| w != 0)
311 let word_idx = start_word_index + offset;
312 let start_word = self.words[word_idx];
313 let pos = max_bit(start_word) + WORD_BITS * word_idx;
315 return Some(T::new(pos));
322 bit_relations_inherent_impls! {}
326 impl<T: Idx> BitRelations<BitSet<T>> for BitSet<T> {
327 fn union(&mut self, other: &BitSet<T>) -> bool {
328 assert_eq!(self.domain_size, other.domain_size);
329 bitwise(&mut self.words, &other.words, |a, b| a | b)
332 fn subtract(&mut self, other: &BitSet<T>) -> bool {
333 assert_eq!(self.domain_size, other.domain_size);
334 bitwise(&mut self.words, &other.words, |a, b| a & !b)
337 fn intersect(&mut self, other: &BitSet<T>) -> bool {
338 assert_eq!(self.domain_size, other.domain_size);
339 bitwise(&mut self.words, &other.words, |a, b| a & b)
343 impl<T: Idx> From<GrowableBitSet<T>> for BitSet<T> {
344 fn from(bit_set: GrowableBitSet<T>) -> Self {
349 /// A fixed-size bitset type with a partially dense, partially sparse
350 /// representation. The bitset is broken into chunks, and chunks that are all
351 /// zeros or all ones are represented and handled very efficiently.
353 /// This type is especially efficient for sets that typically have a large
354 /// `domain_size` with significant stretches of all zeros or all ones, and also
355 /// some stretches with lots of 0s and 1s mixed in a way that causes trouble
356 /// for `IntervalSet`.
358 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
361 /// All operations that involve an element will panic if the element is equal
362 /// to or greater than the domain size. All operations that involve two bitsets
363 /// will panic if the bitsets have differing domain sizes.
364 #[derive(Debug, PartialEq, Eq)]
365 pub struct ChunkedBitSet<T> {
368 /// The chunks. Each one contains exactly CHUNK_BITS values, except the
369 /// last one which contains 1..=CHUNK_BITS values.
370 chunks: Box<[Chunk]>,
372 marker: PhantomData<T>,
375 // Note: the chunk domain size is duplicated in each variant. This is a bit
376 // inconvenient, but it allows the type size to be smaller than if we had an
377 // outer struct containing a chunk domain size plus the `Chunk`, because the
378 // compiler can place the chunk domain size after the tag.
379 #[derive(Clone, Debug, PartialEq, Eq)]
381 /// A chunk that is all zeros; we don't represent the zeros explicitly.
384 /// A chunk that is all ones; we don't represent the ones explicitly.
387 /// A chunk that has a mix of zeros and ones, which are represented
388 /// explicitly and densely. It never has all zeros or all ones.
390 /// If this is the final chunk there may be excess, unused words. This
391 /// turns out to be both simpler and have better performance than
392 /// allocating the minimum number of words, largely because we avoid having
393 /// to store the length, which would make this type larger. These excess
394 /// words are always be zero, as are any excess bits in the final in-use
397 /// The second field is the count of 1s set in the chunk, and must satisfy
398 /// `0 < count < chunk_domain_size`.
400 /// The words are within an `Rc` because it's surprisingly common to
401 /// duplicate an entire chunk, e.g. in `ChunkedBitSet::clone_from()`, or
402 /// when a `Mixed` chunk is union'd into a `Zeros` chunk. When we do need
403 /// to modify a chunk we use `Rc::make_mut`.
404 Mixed(ChunkSize, ChunkSize, Rc<[Word; CHUNK_WORDS]>),
407 // This type is used a lot. Make sure it doesn't unintentionally get bigger.
408 #[cfg(all(target_arch = "x86_64", target_pointer_width = "64"))]
409 crate::static_assert_size!(Chunk, 16);
411 impl<T> ChunkedBitSet<T> {
412 pub fn domain_size(&self) -> usize {
417 fn assert_valid(&self) {
418 if self.domain_size == 0 {
419 assert!(self.chunks.is_empty());
423 assert!((self.chunks.len() - 1) * CHUNK_BITS <= self.domain_size);
424 assert!(self.chunks.len() * CHUNK_BITS >= self.domain_size);
425 for chunk in self.chunks.iter() {
426 chunk.assert_valid();
431 impl<T: Idx> ChunkedBitSet<T> {
432 /// Creates a new bitset with a given `domain_size` and chunk kind.
433 fn new(domain_size: usize, is_empty: bool) -> Self {
434 let chunks = if domain_size == 0 {
437 // All the chunks have a chunk_domain_size of `CHUNK_BITS` except
439 let final_chunk_domain_size = {
440 let n = domain_size % CHUNK_BITS;
441 if n == 0 { CHUNK_BITS } else { n }
444 vec![Chunk::new(CHUNK_BITS, is_empty); num_chunks(domain_size)].into_boxed_slice();
445 *chunks.last_mut().unwrap() = Chunk::new(final_chunk_domain_size, is_empty);
448 ChunkedBitSet { domain_size, chunks, marker: PhantomData }
451 /// Creates a new, empty bitset with a given `domain_size`.
453 pub fn new_empty(domain_size: usize) -> Self {
454 ChunkedBitSet::new(domain_size, /* is_empty */ true)
457 /// Creates a new, filled bitset with a given `domain_size`.
459 pub fn new_filled(domain_size: usize) -> Self {
460 ChunkedBitSet::new(domain_size, /* is_empty */ false)
464 fn chunks(&self) -> &[Chunk] {
468 /// Count the number of bits in the set.
469 pub fn count(&self) -> usize {
470 self.chunks.iter().map(|chunk| chunk.count()).sum()
473 /// Returns `true` if `self` contains `elem`.
475 pub fn contains(&self, elem: T) -> bool {
476 assert!(elem.index() < self.domain_size);
477 let chunk = &self.chunks[chunk_index(elem)];
481 Mixed(_, _, words) => {
482 let (word_index, mask) = chunk_word_index_and_mask(elem);
483 (words[word_index] & mask) != 0
489 pub fn iter(&self) -> ChunkedBitIter<'_, T> {
490 ChunkedBitIter::new(self)
493 /// Insert `elem`. Returns whether the set has changed.
494 pub fn insert(&mut self, elem: T) -> bool {
495 assert!(elem.index() < self.domain_size);
496 let chunk_index = chunk_index(elem);
497 let chunk = &mut self.chunks[chunk_index];
499 Zeros(chunk_domain_size) => {
500 if chunk_domain_size > 1 {
501 // We take some effort to avoid copying the words.
502 let words = Rc::<[Word; CHUNK_WORDS]>::new_zeroed();
503 // SAFETY: `words` can safely be all zeroes.
504 let mut words = unsafe { words.assume_init() };
505 let words_ref = Rc::get_mut(&mut words).unwrap();
507 let (word_index, mask) = chunk_word_index_and_mask(elem);
508 words_ref[word_index] |= mask;
509 *chunk = Mixed(chunk_domain_size, 1, words);
511 *chunk = Ones(chunk_domain_size);
516 Mixed(chunk_domain_size, ref mut count, ref mut words) => {
517 // We skip all the work if the bit is already set.
518 let (word_index, mask) = chunk_word_index_and_mask(elem);
519 if (words[word_index] & mask) == 0 {
521 if *count < chunk_domain_size {
522 let words = Rc::make_mut(words);
523 words[word_index] |= mask;
525 *chunk = Ones(chunk_domain_size);
535 /// Sets all bits to true.
536 pub fn insert_all(&mut self) {
537 for chunk in self.chunks.iter_mut() {
538 *chunk = match *chunk {
539 Zeros(chunk_domain_size)
540 | Ones(chunk_domain_size)
541 | Mixed(chunk_domain_size, ..) => Ones(chunk_domain_size),
546 /// Returns `true` if the set has changed.
547 pub fn remove(&mut self, elem: T) -> bool {
548 assert!(elem.index() < self.domain_size);
549 let chunk_index = chunk_index(elem);
550 let chunk = &mut self.chunks[chunk_index];
553 Ones(chunk_domain_size) => {
554 if chunk_domain_size > 1 {
555 // We take some effort to avoid copying the words.
556 let words = Rc::<[Word; CHUNK_WORDS]>::new_zeroed();
557 // SAFETY: `words` can safely be all zeroes.
558 let mut words = unsafe { words.assume_init() };
559 let words_ref = Rc::get_mut(&mut words).unwrap();
561 // Set only the bits in use.
562 let num_words = num_words(chunk_domain_size as usize);
563 words_ref[..num_words].fill(!0);
564 clear_excess_bits_in_final_word(
565 chunk_domain_size as usize,
566 &mut words_ref[..num_words],
568 let (word_index, mask) = chunk_word_index_and_mask(elem);
569 words_ref[word_index] &= !mask;
570 *chunk = Mixed(chunk_domain_size, chunk_domain_size - 1, words);
572 *chunk = Zeros(chunk_domain_size);
576 Mixed(chunk_domain_size, ref mut count, ref mut words) => {
577 // We skip all the work if the bit is already clear.
578 let (word_index, mask) = chunk_word_index_and_mask(elem);
579 if (words[word_index] & mask) != 0 {
582 let words = Rc::make_mut(words);
583 words[word_index] &= !mask;
585 *chunk = Zeros(chunk_domain_size);
595 bit_relations_inherent_impls! {}
598 impl<T: Idx> BitRelations<ChunkedBitSet<T>> for ChunkedBitSet<T> {
599 fn union(&mut self, other: &ChunkedBitSet<T>) -> bool {
600 assert_eq!(self.domain_size, other.domain_size);
601 debug_assert_eq!(self.chunks.len(), other.chunks.len());
603 let mut changed = false;
604 for (mut self_chunk, other_chunk) in self.chunks.iter_mut().zip(other.chunks.iter()) {
605 match (&mut self_chunk, &other_chunk) {
606 (_, Zeros(_)) | (Ones(_), _) => {}
607 (Zeros(self_chunk_domain_size), Ones(other_chunk_domain_size))
608 | (Mixed(self_chunk_domain_size, ..), Ones(other_chunk_domain_size))
609 | (Zeros(self_chunk_domain_size), Mixed(other_chunk_domain_size, ..)) => {
610 // `other_chunk` fully overwrites `self_chunk`
611 debug_assert_eq!(self_chunk_domain_size, other_chunk_domain_size);
612 *self_chunk = other_chunk.clone();
617 self_chunk_domain_size,
618 ref mut self_chunk_count,
619 ref mut self_chunk_words,
621 Mixed(_other_chunk_domain_size, _other_chunk_count, other_chunk_words),
623 // First check if the operation would change
624 // `self_chunk.words`. If not, we can avoid allocating some
625 // words, and this happens often enough that it's a
626 // performance win. Also, we only need to operate on the
627 // in-use words, hence the slicing.
628 let op = |a, b| a | b;
629 let num_words = num_words(*self_chunk_domain_size as usize);
631 &self_chunk_words[0..num_words],
632 &other_chunk_words[0..num_words],
635 let self_chunk_words = Rc::make_mut(self_chunk_words);
636 let has_changed = bitwise(
637 &mut self_chunk_words[0..num_words],
638 &other_chunk_words[0..num_words],
641 debug_assert!(has_changed);
642 *self_chunk_count = self_chunk_words[0..num_words]
644 .map(|w| w.count_ones() as ChunkSize)
646 if *self_chunk_count == *self_chunk_domain_size {
647 *self_chunk = Ones(*self_chunk_domain_size);
657 fn subtract(&mut self, _other: &ChunkedBitSet<T>) -> bool {
658 unimplemented!("implement if/when necessary");
661 fn intersect(&mut self, _other: &ChunkedBitSet<T>) -> bool {
662 unimplemented!("implement if/when necessary");
666 impl<T: Idx> BitRelations<HybridBitSet<T>> for ChunkedBitSet<T> {
667 fn union(&mut self, other: &HybridBitSet<T>) -> bool {
668 // FIXME: This is slow if `other` is dense, but it hasn't been a problem
669 // in practice so far.
670 // If a faster implementation of this operation is required, consider
671 // reopening https://github.com/rust-lang/rust/pull/94625
672 assert_eq!(self.domain_size, other.domain_size());
673 sequential_update(|elem| self.insert(elem), other.iter())
676 fn subtract(&mut self, other: &HybridBitSet<T>) -> bool {
677 // FIXME: This is slow if `other` is dense, but it hasn't been a problem
678 // in practice so far.
679 // If a faster implementation of this operation is required, consider
680 // reopening https://github.com/rust-lang/rust/pull/94625
681 assert_eq!(self.domain_size, other.domain_size());
682 sequential_update(|elem| self.remove(elem), other.iter())
685 fn intersect(&mut self, _other: &HybridBitSet<T>) -> bool {
686 unimplemented!("implement if/when necessary");
690 impl<T: Idx> BitRelations<ChunkedBitSet<T>> for BitSet<T> {
691 fn union(&mut self, other: &ChunkedBitSet<T>) -> bool {
692 sequential_update(|elem| self.insert(elem), other.iter())
695 fn subtract(&mut self, _other: &ChunkedBitSet<T>) -> bool {
696 unimplemented!("implement if/when necessary");
699 fn intersect(&mut self, other: &ChunkedBitSet<T>) -> bool {
700 assert_eq!(self.domain_size(), other.domain_size);
701 let mut changed = false;
702 for (i, chunk) in other.chunks.iter().enumerate() {
703 let mut words = &mut self.words[i * CHUNK_WORDS..];
704 if words.len() > CHUNK_WORDS {
705 words = &mut words[..CHUNK_WORDS];
708 Chunk::Zeros(..) => {
716 Chunk::Ones(..) => (),
717 Chunk::Mixed(_, _, data) => {
718 for (i, word) in words.iter_mut().enumerate() {
719 let new_val = *word & data[i];
720 if new_val != *word {
732 impl<T> Clone for ChunkedBitSet<T> {
733 fn clone(&self) -> Self {
735 domain_size: self.domain_size,
736 chunks: self.chunks.clone(),
741 /// WARNING: this implementation of clone_from will panic if the two
742 /// bitsets have different domain sizes. This constraint is not inherent to
743 /// `clone_from`, but it works with the existing call sites and allows a
744 /// faster implementation, which is important because this function is hot.
745 fn clone_from(&mut self, from: &Self) {
746 assert_eq!(self.domain_size, from.domain_size);
747 debug_assert_eq!(self.chunks.len(), from.chunks.len());
749 self.chunks.clone_from(&from.chunks)
753 pub struct ChunkedBitIter<'a, T: Idx> {
755 bitset: &'a ChunkedBitSet<T>,
758 impl<'a, T: Idx> ChunkedBitIter<'a, T> {
760 fn new(bitset: &'a ChunkedBitSet<T>) -> ChunkedBitIter<'a, T> {
761 ChunkedBitIter { index: 0, bitset }
765 impl<'a, T: Idx> Iterator for ChunkedBitIter<'a, T> {
767 fn next(&mut self) -> Option<T> {
768 while self.index < self.bitset.domain_size() {
769 let elem = T::new(self.index);
770 let chunk = &self.bitset.chunks[chunk_index(elem)];
772 Zeros(chunk_domain_size) => {
773 self.index += *chunk_domain_size as usize;
775 Ones(_chunk_domain_size) => {
779 Mixed(_chunk_domain_size, _, words) => loop {
780 let elem = T::new(self.index);
782 let (word_index, mask) = chunk_word_index_and_mask(elem);
783 if (words[word_index] & mask) != 0 {
786 if self.index % CHUNK_BITS == 0 {
795 fn fold<B, F>(mut self, mut init: B, mut f: F) -> B
797 F: FnMut(B, Self::Item) -> B,
799 // If `next` has already been called, we may not be at the start of a chunk, so we first
800 // advance the iterator to the start of the next chunk, before proceeding in chunk sized
802 while self.index % CHUNK_BITS != 0 {
803 let Some(item) = self.next() else {
806 init = f(init, item);
808 let start_chunk = self.index / CHUNK_BITS;
809 let chunks = &self.bitset.chunks[start_chunk..];
810 for (i, chunk) in chunks.iter().enumerate() {
811 let base = (start_chunk + i) * CHUNK_BITS;
813 Chunk::Zeros(_) => (),
814 Chunk::Ones(limit) => {
815 for j in 0..(*limit as usize) {
816 init = f(init, T::new(base + j));
819 Chunk::Mixed(_, _, words) => {
820 init = BitIter::new(&**words).fold(init, |val, mut item: T| {
821 item.increment_by(base);
833 fn assert_valid(&self) {
835 Zeros(chunk_domain_size) | Ones(chunk_domain_size) => {
836 assert!(chunk_domain_size as usize <= CHUNK_BITS);
838 Mixed(chunk_domain_size, count, ref words) => {
839 assert!(chunk_domain_size as usize <= CHUNK_BITS);
840 assert!(0 < count && count < chunk_domain_size);
842 // Check the number of set bits matches `count`.
844 words.iter().map(|w| w.count_ones() as ChunkSize).sum::<ChunkSize>(),
848 // Check the not-in-use words are all zeroed.
849 let num_words = num_words(chunk_domain_size as usize);
850 if num_words < CHUNK_WORDS {
854 .map(|w| w.count_ones() as ChunkSize)
863 fn new(chunk_domain_size: usize, is_empty: bool) -> Self {
864 debug_assert!(chunk_domain_size <= CHUNK_BITS);
865 let chunk_domain_size = chunk_domain_size as ChunkSize;
866 if is_empty { Zeros(chunk_domain_size) } else { Ones(chunk_domain_size) }
869 /// Count the number of 1s in the chunk.
870 fn count(&self) -> usize {
873 Ones(chunk_domain_size) => chunk_domain_size as usize,
874 Mixed(_, count, _) => count as usize,
879 // Applies a function to mutate a bitset, and returns true if any
880 // of the applications return true
881 fn sequential_update<T: Idx>(
882 mut self_update: impl FnMut(T) -> bool,
883 it: impl Iterator<Item = T>,
885 it.fold(false, |changed, elem| self_update(elem) | changed)
888 // Optimization of intersection for SparseBitSet that's generic
890 fn sparse_intersect<T: Idx>(
891 set: &mut SparseBitSet<T>,
892 other_contains: impl Fn(&T) -> bool,
894 let size = set.elems.len();
895 set.elems.retain(|elem| other_contains(elem));
896 set.elems.len() != size
899 // Optimization of dense/sparse intersection. The resulting set is
900 // guaranteed to be at most the size of the sparse set, and hence can be
901 // represented as a sparse set. Therefore the sparse set is copied and filtered,
902 // then returned as the new set.
903 fn dense_sparse_intersect<T: Idx>(
905 sparse: &SparseBitSet<T>,
906 ) -> (SparseBitSet<T>, bool) {
907 let mut sparse_copy = sparse.clone();
908 sparse_intersect(&mut sparse_copy, |el| dense.contains(*el));
909 let n = sparse_copy.len();
910 (sparse_copy, n != dense.count())
914 impl<T: Idx> BitRelations<BitSet<T>> for HybridBitSet<T> {
915 fn union(&mut self, other: &BitSet<T>) -> bool {
916 assert_eq!(self.domain_size(), other.domain_size);
918 HybridBitSet::Sparse(sparse) => {
919 // `self` is sparse and `other` is dense. To
920 // merge them, we have two available strategies:
921 // * Densify `self` then merge other
922 // * Clone other then integrate bits from `self`
923 // The second strategy requires dedicated method
924 // since the usual `union` returns the wrong
925 // result. In the dedicated case the computation
926 // is slightly faster if the bits of the sparse
927 // bitset map to only few words of the dense
928 // representation, i.e. indices are near each
931 // Benchmarking seems to suggest that the second
932 // option is worth it.
933 let mut new_dense = other.clone();
934 let changed = new_dense.reverse_union_sparse(sparse);
935 *self = HybridBitSet::Dense(new_dense);
939 HybridBitSet::Dense(dense) => dense.union(other),
943 fn subtract(&mut self, other: &BitSet<T>) -> bool {
944 assert_eq!(self.domain_size(), other.domain_size);
946 HybridBitSet::Sparse(sparse) => {
947 sequential_update(|elem| sparse.remove(elem), other.iter())
949 HybridBitSet::Dense(dense) => dense.subtract(other),
953 fn intersect(&mut self, other: &BitSet<T>) -> bool {
954 assert_eq!(self.domain_size(), other.domain_size);
956 HybridBitSet::Sparse(sparse) => sparse_intersect(sparse, |elem| other.contains(*elem)),
957 HybridBitSet::Dense(dense) => dense.intersect(other),
963 impl<T: Idx> BitRelations<HybridBitSet<T>> for BitSet<T> {
964 fn union(&mut self, other: &HybridBitSet<T>) -> bool {
965 assert_eq!(self.domain_size, other.domain_size());
967 HybridBitSet::Sparse(sparse) => {
968 sequential_update(|elem| self.insert(elem), sparse.iter().cloned())
970 HybridBitSet::Dense(dense) => self.union(dense),
974 fn subtract(&mut self, other: &HybridBitSet<T>) -> bool {
975 assert_eq!(self.domain_size, other.domain_size());
977 HybridBitSet::Sparse(sparse) => {
978 sequential_update(|elem| self.remove(elem), sparse.iter().cloned())
980 HybridBitSet::Dense(dense) => self.subtract(dense),
984 fn intersect(&mut self, other: &HybridBitSet<T>) -> bool {
985 assert_eq!(self.domain_size, other.domain_size());
987 HybridBitSet::Sparse(sparse) => {
988 let (updated, changed) = dense_sparse_intersect(self, sparse);
990 // We can't directly assign the SparseBitSet to the BitSet, and
991 // doing `*self = updated.to_dense()` would cause a drop / reallocation. Instead,
992 // the BitSet is cleared and `updated` is copied into `self`.
994 for elem in updated.iter() {
999 HybridBitSet::Dense(dense) => self.intersect(dense),
1004 // hybrid REL hybrid
1005 impl<T: Idx> BitRelations<HybridBitSet<T>> for HybridBitSet<T> {
1006 fn union(&mut self, other: &HybridBitSet<T>) -> bool {
1007 assert_eq!(self.domain_size(), other.domain_size());
1009 HybridBitSet::Sparse(_) => {
1011 HybridBitSet::Sparse(other_sparse) => {
1012 // Both sets are sparse. Add the elements in
1013 // `other_sparse` to `self` one at a time. This
1014 // may or may not cause `self` to be densified.
1015 let mut changed = false;
1016 for elem in other_sparse.iter() {
1017 changed |= self.insert(*elem);
1022 HybridBitSet::Dense(other_dense) => self.union(other_dense),
1026 HybridBitSet::Dense(self_dense) => self_dense.union(other),
1030 fn subtract(&mut self, other: &HybridBitSet<T>) -> bool {
1031 assert_eq!(self.domain_size(), other.domain_size());
1033 HybridBitSet::Sparse(self_sparse) => {
1034 sequential_update(|elem| self_sparse.remove(elem), other.iter())
1036 HybridBitSet::Dense(self_dense) => self_dense.subtract(other),
1040 fn intersect(&mut self, other: &HybridBitSet<T>) -> bool {
1041 assert_eq!(self.domain_size(), other.domain_size());
1043 HybridBitSet::Sparse(self_sparse) => {
1044 sparse_intersect(self_sparse, |elem| other.contains(*elem))
1046 HybridBitSet::Dense(self_dense) => match other {
1047 HybridBitSet::Sparse(other_sparse) => {
1048 let (updated, changed) = dense_sparse_intersect(self_dense, other_sparse);
1049 *self = HybridBitSet::Sparse(updated);
1052 HybridBitSet::Dense(other_dense) => self_dense.intersect(other_dense),
1058 impl<T> Clone for BitSet<T> {
1059 fn clone(&self) -> Self {
1060 BitSet { domain_size: self.domain_size, words: self.words.clone(), marker: PhantomData }
1063 fn clone_from(&mut self, from: &Self) {
1064 if self.domain_size != from.domain_size {
1065 self.words.resize(from.domain_size, 0);
1066 self.domain_size = from.domain_size;
1069 self.words.copy_from_slice(&from.words);
1073 impl<T: Idx> fmt::Debug for BitSet<T> {
1074 fn fmt(&self, w: &mut fmt::Formatter<'_>) -> fmt::Result {
1075 w.debug_list().entries(self.iter()).finish()
1079 impl<T: Idx> ToString for BitSet<T> {
1080 fn to_string(&self) -> String {
1081 let mut result = String::new();
1084 // Note: this is a little endian printout of bytes.
1086 // i tracks how many bits we have printed so far.
1088 for word in &self.words {
1089 let mut word = *word;
1090 for _ in 0..WORD_BYTES {
1091 // for each byte in `word`:
1092 let remain = self.domain_size - i;
1093 // If less than a byte remains, then mask just that many bits.
1094 let mask = if remain <= 8 { (1 << remain) - 1 } else { 0xFF };
1095 assert!(mask <= 0xFF);
1096 let byte = word & mask;
1098 result.push_str(&format!("{}{:02x}", sep, byte));
1115 pub struct BitIter<'a, T: Idx> {
1116 /// A copy of the current word, but with any already-visited bits cleared.
1117 /// (This lets us use `trailing_zeros()` to find the next set bit.) When it
1118 /// is reduced to 0, we move onto the next word.
1121 /// The offset (measured in bits) of the current word.
1124 /// Underlying iterator over the words.
1125 iter: slice::Iter<'a, Word>,
1127 marker: PhantomData<T>,
1130 impl<'a, T: Idx> BitIter<'a, T> {
1132 fn new(words: &'a [Word]) -> BitIter<'a, T> {
1133 // We initialize `word` and `offset` to degenerate values. On the first
1134 // call to `next()` we will fall through to getting the first word from
1135 // `iter`, which sets `word` to the first word (if there is one) and
1136 // `offset` to 0. Doing it this way saves us from having to maintain
1137 // additional state about whether we have started.
1140 offset: usize::MAX - (WORD_BITS - 1),
1142 marker: PhantomData,
1147 impl<'a, T: Idx> Iterator for BitIter<'a, T> {
1149 fn next(&mut self) -> Option<T> {
1152 // Get the position of the next set bit in the current word,
1153 // then clear the bit.
1154 let bit_pos = self.word.trailing_zeros() as usize;
1155 let bit = 1 << bit_pos;
1157 return Some(T::new(bit_pos + self.offset));
1160 // Move onto the next word. `wrapping_add()` is needed to handle
1161 // the degenerate initial value given to `offset` in `new()`.
1162 let word = self.iter.next()?;
1164 self.offset = self.offset.wrapping_add(WORD_BITS);
1170 fn bitwise<Op>(out_vec: &mut [Word], in_vec: &[Word], op: Op) -> bool
1172 Op: Fn(Word, Word) -> Word,
1174 assert_eq!(out_vec.len(), in_vec.len());
1175 let mut changed = 0;
1176 for (out_elem, in_elem) in iter::zip(out_vec, in_vec) {
1177 let old_val = *out_elem;
1178 let new_val = op(old_val, *in_elem);
1179 *out_elem = new_val;
1180 // This is essentially equivalent to a != with changed being a bool, but
1181 // in practice this code gets auto-vectorized by the compiler for most
1182 // operators. Using != here causes us to generate quite poor code as the
1183 // compiler tries to go back to a boolean on each loop iteration.
1184 changed |= old_val ^ new_val;
1189 /// Does this bitwise operation change `out_vec`?
1191 fn bitwise_changes<Op>(out_vec: &[Word], in_vec: &[Word], op: Op) -> bool
1193 Op: Fn(Word, Word) -> Word,
1195 assert_eq!(out_vec.len(), in_vec.len());
1196 for (out_elem, in_elem) in iter::zip(out_vec, in_vec) {
1197 let old_val = *out_elem;
1198 let new_val = op(old_val, *in_elem);
1199 if old_val != new_val {
1206 const SPARSE_MAX: usize = 8;
1208 /// A fixed-size bitset type with a sparse representation and a maximum of
1209 /// `SPARSE_MAX` elements. The elements are stored as a sorted `ArrayVec` with
1212 /// This type is used by `HybridBitSet`; do not use directly.
1213 #[derive(Clone, Debug)]
1214 pub struct SparseBitSet<T> {
1216 elems: ArrayVec<T, SPARSE_MAX>,
1219 impl<T: Idx> SparseBitSet<T> {
1220 fn new_empty(domain_size: usize) -> Self {
1221 SparseBitSet { domain_size, elems: ArrayVec::new() }
1224 fn len(&self) -> usize {
1228 fn is_empty(&self) -> bool {
1229 self.elems.len() == 0
1232 fn contains(&self, elem: T) -> bool {
1233 assert!(elem.index() < self.domain_size);
1234 self.elems.contains(&elem)
1237 fn insert(&mut self, elem: T) -> bool {
1238 assert!(elem.index() < self.domain_size);
1239 let changed = if let Some(i) = self.elems.iter().position(|&e| e.index() >= elem.index()) {
1240 if self.elems[i] == elem {
1241 // `elem` is already in the set.
1244 // `elem` is smaller than one or more existing elements.
1245 self.elems.insert(i, elem);
1249 // `elem` is larger than all existing elements.
1250 self.elems.push(elem);
1253 assert!(self.len() <= SPARSE_MAX);
1257 fn remove(&mut self, elem: T) -> bool {
1258 assert!(elem.index() < self.domain_size);
1259 if let Some(i) = self.elems.iter().position(|&e| e == elem) {
1260 self.elems.remove(i);
1267 fn to_dense(&self) -> BitSet<T> {
1268 let mut dense = BitSet::new_empty(self.domain_size);
1269 for elem in self.elems.iter() {
1270 dense.insert(*elem);
1275 fn iter(&self) -> slice::Iter<'_, T> {
1279 bit_relations_inherent_impls! {}
1282 impl<T: Idx + Ord> SparseBitSet<T> {
1283 fn last_set_in(&self, range: impl RangeBounds<T>) -> Option<T> {
1284 let mut last_leq = None;
1285 for e in self.iter() {
1286 if range.contains(e) {
1287 last_leq = Some(*e);
1294 /// A fixed-size bitset type with a hybrid representation: sparse when there
1295 /// are up to a `SPARSE_MAX` elements in the set, but dense when there are more
1296 /// than `SPARSE_MAX`.
1298 /// This type is especially efficient for sets that typically have a small
1299 /// number of elements, but a large `domain_size`, and are cleared frequently.
1301 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
1302 /// just be `usize`.
1304 /// All operations that involve an element will panic if the element is equal
1305 /// to or greater than the domain size. All operations that involve two bitsets
1306 /// will panic if the bitsets have differing domain sizes.
1308 pub enum HybridBitSet<T> {
1309 Sparse(SparseBitSet<T>),
1313 impl<T: Idx> fmt::Debug for HybridBitSet<T> {
1314 fn fmt(&self, w: &mut fmt::Formatter<'_>) -> fmt::Result {
1316 Self::Sparse(b) => b.fmt(w),
1317 Self::Dense(b) => b.fmt(w),
1322 impl<T: Idx> HybridBitSet<T> {
1323 pub fn new_empty(domain_size: usize) -> Self {
1324 HybridBitSet::Sparse(SparseBitSet::new_empty(domain_size))
1327 pub fn domain_size(&self) -> usize {
1329 HybridBitSet::Sparse(sparse) => sparse.domain_size,
1330 HybridBitSet::Dense(dense) => dense.domain_size,
1334 pub fn clear(&mut self) {
1335 let domain_size = self.domain_size();
1336 *self = HybridBitSet::new_empty(domain_size);
1339 pub fn contains(&self, elem: T) -> bool {
1341 HybridBitSet::Sparse(sparse) => sparse.contains(elem),
1342 HybridBitSet::Dense(dense) => dense.contains(elem),
1346 pub fn superset(&self, other: &HybridBitSet<T>) -> bool {
1347 match (self, other) {
1348 (HybridBitSet::Dense(self_dense), HybridBitSet::Dense(other_dense)) => {
1349 self_dense.superset(other_dense)
1352 assert!(self.domain_size() == other.domain_size());
1353 other.iter().all(|elem| self.contains(elem))
1358 pub fn is_empty(&self) -> bool {
1360 HybridBitSet::Sparse(sparse) => sparse.is_empty(),
1361 HybridBitSet::Dense(dense) => dense.is_empty(),
1365 /// Returns the previous element present in the bitset from `elem`,
1366 /// inclusively of elem. That is, will return `Some(elem)` if elem is in the
1368 pub fn last_set_in(&self, range: impl RangeBounds<T>) -> Option<T>
1373 HybridBitSet::Sparse(sparse) => sparse.last_set_in(range),
1374 HybridBitSet::Dense(dense) => dense.last_set_in(range),
1378 pub fn insert(&mut self, elem: T) -> bool {
1379 // No need to check `elem` against `self.domain_size` here because all
1380 // the match cases check it, one way or another.
1382 HybridBitSet::Sparse(sparse) if sparse.len() < SPARSE_MAX => {
1383 // The set is sparse and has space for `elem`.
1386 HybridBitSet::Sparse(sparse) if sparse.contains(elem) => {
1387 // The set is sparse and does not have space for `elem`, but
1388 // that doesn't matter because `elem` is already present.
1391 HybridBitSet::Sparse(sparse) => {
1392 // The set is sparse and full. Convert to a dense set.
1393 let mut dense = sparse.to_dense();
1394 let changed = dense.insert(elem);
1396 *self = HybridBitSet::Dense(dense);
1399 HybridBitSet::Dense(dense) => dense.insert(elem),
1403 pub fn insert_range(&mut self, elems: impl RangeBounds<T>) {
1404 // No need to check `elem` against `self.domain_size` here because all
1405 // the match cases check it, one way or another.
1406 let start = match elems.start_bound().cloned() {
1407 Bound::Included(start) => start.index(),
1408 Bound::Excluded(start) => start.index() + 1,
1409 Bound::Unbounded => 0,
1411 let end = match elems.end_bound().cloned() {
1412 Bound::Included(end) => end.index() + 1,
1413 Bound::Excluded(end) => end.index(),
1414 Bound::Unbounded => self.domain_size() - 1,
1416 let Some(len) = end.checked_sub(start) else { return };
1418 HybridBitSet::Sparse(sparse) if sparse.len() + len < SPARSE_MAX => {
1419 // The set is sparse and has space for `elems`.
1420 for elem in start..end {
1421 sparse.insert(T::new(elem));
1424 HybridBitSet::Sparse(sparse) => {
1425 // The set is sparse and full. Convert to a dense set.
1426 let mut dense = sparse.to_dense();
1427 dense.insert_range(elems);
1428 *self = HybridBitSet::Dense(dense);
1430 HybridBitSet::Dense(dense) => dense.insert_range(elems),
1434 pub fn insert_all(&mut self) {
1435 let domain_size = self.domain_size();
1437 HybridBitSet::Sparse(_) => {
1438 *self = HybridBitSet::Dense(BitSet::new_filled(domain_size));
1440 HybridBitSet::Dense(dense) => dense.insert_all(),
1444 pub fn remove(&mut self, elem: T) -> bool {
1445 // Note: we currently don't bother going from Dense back to Sparse.
1447 HybridBitSet::Sparse(sparse) => sparse.remove(elem),
1448 HybridBitSet::Dense(dense) => dense.remove(elem),
1452 /// Converts to a dense set, consuming itself in the process.
1453 pub fn to_dense(self) -> BitSet<T> {
1455 HybridBitSet::Sparse(sparse) => sparse.to_dense(),
1456 HybridBitSet::Dense(dense) => dense,
1460 pub fn iter(&self) -> HybridIter<'_, T> {
1462 HybridBitSet::Sparse(sparse) => HybridIter::Sparse(sparse.iter()),
1463 HybridBitSet::Dense(dense) => HybridIter::Dense(dense.iter()),
1467 bit_relations_inherent_impls! {}
1470 pub enum HybridIter<'a, T: Idx> {
1471 Sparse(slice::Iter<'a, T>),
1472 Dense(BitIter<'a, T>),
1475 impl<'a, T: Idx> Iterator for HybridIter<'a, T> {
1478 fn next(&mut self) -> Option<T> {
1480 HybridIter::Sparse(sparse) => sparse.next().copied(),
1481 HybridIter::Dense(dense) => dense.next(),
1486 /// A resizable bitset type with a dense representation.
1488 /// `T` is an index type, typically a newtyped `usize` wrapper, but it can also
1489 /// just be `usize`.
1491 /// All operations that involve an element will panic if the element is equal
1492 /// to or greater than the domain size.
1493 #[derive(Clone, Debug, PartialEq)]
1494 pub struct GrowableBitSet<T: Idx> {
1498 impl<T: Idx> Default for GrowableBitSet<T> {
1499 fn default() -> Self {
1500 GrowableBitSet::new_empty()
1504 impl<T: Idx> GrowableBitSet<T> {
1505 /// Ensure that the set can hold at least `min_domain_size` elements.
1506 pub fn ensure(&mut self, min_domain_size: usize) {
1507 if self.bit_set.domain_size < min_domain_size {
1508 self.bit_set.domain_size = min_domain_size;
1511 let min_num_words = num_words(min_domain_size);
1512 if self.bit_set.words.len() < min_num_words {
1513 self.bit_set.words.resize(min_num_words, 0)
1517 pub fn new_empty() -> GrowableBitSet<T> {
1518 GrowableBitSet { bit_set: BitSet::new_empty(0) }
1521 pub fn with_capacity(capacity: usize) -> GrowableBitSet<T> {
1522 GrowableBitSet { bit_set: BitSet::new_empty(capacity) }
1525 /// Returns `true` if the set has changed.
1527 pub fn insert(&mut self, elem: T) -> bool {
1528 self.ensure(elem.index() + 1);
1529 self.bit_set.insert(elem)
1532 /// Returns `true` if the set has changed.
1534 pub fn remove(&mut self, elem: T) -> bool {
1535 self.ensure(elem.index() + 1);
1536 self.bit_set.remove(elem)
1540 pub fn is_empty(&self) -> bool {
1541 self.bit_set.is_empty()
1545 pub fn contains(&self, elem: T) -> bool {
1546 let (word_index, mask) = word_index_and_mask(elem);
1547 self.bit_set.words.get(word_index).map_or(false, |word| (word & mask) != 0)
1551 pub fn iter(&self) -> BitIter<'_, T> {
1556 pub fn len(&self) -> usize {
1557 self.bit_set.count()
1561 impl<T: Idx> From<BitSet<T>> for GrowableBitSet<T> {
1562 fn from(bit_set: BitSet<T>) -> Self {
1567 /// A fixed-size 2D bit matrix type with a dense representation.
1569 /// `R` and `C` are index types used to identify rows and columns respectively;
1570 /// typically newtyped `usize` wrappers, but they can also just be `usize`.
1572 /// All operations that involve a row and/or column index will panic if the
1573 /// index exceeds the relevant bound.
1574 #[derive(Clone, Eq, PartialEq, Hash, Decodable, Encodable)]
1575 pub struct BitMatrix<R: Idx, C: Idx> {
1579 marker: PhantomData<(R, C)>,
1582 impl<R: Idx, C: Idx> BitMatrix<R, C> {
1583 /// Creates a new `rows x columns` matrix, initially empty.
1584 pub fn new(num_rows: usize, num_columns: usize) -> BitMatrix<R, C> {
1585 // For every element, we need one bit for every other
1586 // element. Round up to an even number of words.
1587 let words_per_row = num_words(num_columns);
1591 words: vec![0; num_rows * words_per_row],
1592 marker: PhantomData,
1596 /// Creates a new matrix, with `row` used as the value for every row.
1597 pub fn from_row_n(row: &BitSet<C>, num_rows: usize) -> BitMatrix<R, C> {
1598 let num_columns = row.domain_size();
1599 let words_per_row = num_words(num_columns);
1600 assert_eq!(words_per_row, row.words().len());
1604 words: iter::repeat(row.words()).take(num_rows).flatten().cloned().collect(),
1605 marker: PhantomData,
1609 pub fn rows(&self) -> impl Iterator<Item = R> {
1610 (0..self.num_rows).map(R::new)
1613 /// The range of bits for a given row.
1614 fn range(&self, row: R) -> (usize, usize) {
1615 let words_per_row = num_words(self.num_columns);
1616 let start = row.index() * words_per_row;
1617 (start, start + words_per_row)
1620 /// Sets the cell at `(row, column)` to true. Put another way, insert
1621 /// `column` to the bitset for `row`.
1623 /// Returns `true` if this changed the matrix.
1624 pub fn insert(&mut self, row: R, column: C) -> bool {
1625 assert!(row.index() < self.num_rows && column.index() < self.num_columns);
1626 let (start, _) = self.range(row);
1627 let (word_index, mask) = word_index_and_mask(column);
1628 let words = &mut self.words[..];
1629 let word = words[start + word_index];
1630 let new_word = word | mask;
1631 words[start + word_index] = new_word;
1635 /// Do the bits from `row` contain `column`? Put another way, is
1636 /// the matrix cell at `(row, column)` true? Put yet another way,
1637 /// if the matrix represents (transitive) reachability, can
1638 /// `row` reach `column`?
1639 pub fn contains(&self, row: R, column: C) -> bool {
1640 assert!(row.index() < self.num_rows && column.index() < self.num_columns);
1641 let (start, _) = self.range(row);
1642 let (word_index, mask) = word_index_and_mask(column);
1643 (self.words[start + word_index] & mask) != 0
1646 /// Returns those indices that are true in rows `a` and `b`. This
1647 /// is an *O*(*n*) operation where *n* is the number of elements
1648 /// (somewhat independent from the actual size of the
1649 /// intersection, in particular).
1650 pub fn intersect_rows(&self, row1: R, row2: R) -> Vec<C> {
1651 assert!(row1.index() < self.num_rows && row2.index() < self.num_rows);
1652 let (row1_start, row1_end) = self.range(row1);
1653 let (row2_start, row2_end) = self.range(row2);
1654 let mut result = Vec::with_capacity(self.num_columns);
1655 for (base, (i, j)) in (row1_start..row1_end).zip(row2_start..row2_end).enumerate() {
1656 let mut v = self.words[i] & self.words[j];
1657 for bit in 0..WORD_BITS {
1662 result.push(C::new(base * WORD_BITS + bit));
1670 /// Adds the bits from row `read` to the bits from row `write`, and
1671 /// returns `true` if anything changed.
1673 /// This is used when computing transitive reachability because if
1674 /// you have an edge `write -> read`, because in that case
1675 /// `write` can reach everything that `read` can (and
1676 /// potentially more).
1677 pub fn union_rows(&mut self, read: R, write: R) -> bool {
1678 assert!(read.index() < self.num_rows && write.index() < self.num_rows);
1679 let (read_start, read_end) = self.range(read);
1680 let (write_start, write_end) = self.range(write);
1681 let words = &mut self.words[..];
1682 let mut changed = false;
1683 for (read_index, write_index) in iter::zip(read_start..read_end, write_start..write_end) {
1684 let word = words[write_index];
1685 let new_word = word | words[read_index];
1686 words[write_index] = new_word;
1687 changed |= word != new_word;
1692 /// Adds the bits from `with` to the bits from row `write`, and
1693 /// returns `true` if anything changed.
1694 pub fn union_row_with(&mut self, with: &BitSet<C>, write: R) -> bool {
1695 assert!(write.index() < self.num_rows);
1696 assert_eq!(with.domain_size(), self.num_columns);
1697 let (write_start, write_end) = self.range(write);
1698 let mut changed = false;
1699 for (read_index, write_index) in iter::zip(0..with.words().len(), write_start..write_end) {
1700 let word = self.words[write_index];
1701 let new_word = word | with.words()[read_index];
1702 self.words[write_index] = new_word;
1703 changed |= word != new_word;
1708 /// Sets every cell in `row` to true.
1709 pub fn insert_all_into_row(&mut self, row: R) {
1710 assert!(row.index() < self.num_rows);
1711 let (start, end) = self.range(row);
1712 let words = &mut self.words[..];
1713 for index in start..end {
1716 clear_excess_bits_in_final_word(self.num_columns, &mut self.words[..end]);
1719 /// Gets a slice of the underlying words.
1720 pub fn words(&self) -> &[Word] {
1724 /// Iterates through all the columns set to true in a given row of
1726 pub fn iter(&self, row: R) -> BitIter<'_, C> {
1727 assert!(row.index() < self.num_rows);
1728 let (start, end) = self.range(row);
1729 BitIter::new(&self.words[start..end])
1732 /// Returns the number of elements in `row`.
1733 pub fn count(&self, row: R) -> usize {
1734 let (start, end) = self.range(row);
1735 self.words[start..end].iter().map(|e| e.count_ones() as usize).sum()
1739 impl<R: Idx, C: Idx> fmt::Debug for BitMatrix<R, C> {
1740 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1741 /// Forces its contents to print in regular mode instead of alternate mode.
1742 struct OneLinePrinter<T>(T);
1743 impl<T: fmt::Debug> fmt::Debug for OneLinePrinter<T> {
1744 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
1745 write!(fmt, "{:?}", self.0)
1749 write!(fmt, "BitMatrix({}x{}) ", self.num_rows, self.num_columns)?;
1750 let items = self.rows().flat_map(|r| self.iter(r).map(move |c| (r, c)));
1751 fmt.debug_set().entries(items.map(OneLinePrinter)).finish()
1755 /// A fixed-column-size, variable-row-size 2D bit matrix with a moderately
1756 /// sparse representation.
1758 /// Initially, every row has no explicit representation. If any bit within a
1759 /// row is set, the entire row is instantiated as `Some(<HybridBitSet>)`.
1760 /// Furthermore, any previously uninstantiated rows prior to it will be
1761 /// instantiated as `None`. Those prior rows may themselves become fully
1762 /// instantiated later on if any of their bits are set.
1764 /// `R` and `C` are index types used to identify rows and columns respectively;
1765 /// typically newtyped `usize` wrappers, but they can also just be `usize`.
1766 #[derive(Clone, Debug)]
1767 pub struct SparseBitMatrix<R, C>
1773 rows: IndexVec<R, Option<HybridBitSet<C>>>,
1776 impl<R: Idx, C: Idx> SparseBitMatrix<R, C> {
1777 /// Creates a new empty sparse bit matrix with no rows or columns.
1778 pub fn new(num_columns: usize) -> Self {
1779 Self { num_columns, rows: IndexVec::new() }
1782 fn ensure_row(&mut self, row: R) -> &mut HybridBitSet<C> {
1783 // Instantiate any missing rows up to and including row `row` with an empty HybridBitSet.
1784 // Then replace row `row` with a full HybridBitSet if necessary.
1785 self.rows.get_or_insert_with(row, || HybridBitSet::new_empty(self.num_columns))
1788 /// Sets the cell at `(row, column)` to true. Put another way, insert
1789 /// `column` to the bitset for `row`.
1791 /// Returns `true` if this changed the matrix.
1792 pub fn insert(&mut self, row: R, column: C) -> bool {
1793 self.ensure_row(row).insert(column)
1796 /// Sets the cell at `(row, column)` to false. Put another way, delete
1797 /// `column` from the bitset for `row`. Has no effect if `row` does not
1800 /// Returns `true` if this changed the matrix.
1801 pub fn remove(&mut self, row: R, column: C) -> bool {
1802 match self.rows.get_mut(row) {
1803 Some(Some(row)) => row.remove(column),
1808 /// Sets all columns at `row` to false. Has no effect if `row` does
1810 pub fn clear(&mut self, row: R) {
1811 if let Some(Some(row)) = self.rows.get_mut(row) {
1816 /// Do the bits from `row` contain `column`? Put another way, is
1817 /// the matrix cell at `(row, column)` true? Put yet another way,
1818 /// if the matrix represents (transitive) reachability, can
1819 /// `row` reach `column`?
1820 pub fn contains(&self, row: R, column: C) -> bool {
1821 self.row(row).map_or(false, |r| r.contains(column))
1824 /// Adds the bits from row `read` to the bits from row `write`, and
1825 /// returns `true` if anything changed.
1827 /// This is used when computing transitive reachability because if
1828 /// you have an edge `write -> read`, because in that case
1829 /// `write` can reach everything that `read` can (and
1830 /// potentially more).
1831 pub fn union_rows(&mut self, read: R, write: R) -> bool {
1832 if read == write || self.row(read).is_none() {
1836 self.ensure_row(write);
1837 if let (Some(read_row), Some(write_row)) = self.rows.pick2_mut(read, write) {
1838 write_row.union(read_row)
1844 /// Insert all bits in the given row.
1845 pub fn insert_all_into_row(&mut self, row: R) {
1846 self.ensure_row(row).insert_all();
1849 pub fn rows(&self) -> impl Iterator<Item = R> {
1853 /// Iterates through all the columns set to true in a given row of
1855 pub fn iter<'a>(&'a self, row: R) -> impl Iterator<Item = C> + 'a {
1856 self.row(row).into_iter().flat_map(|r| r.iter())
1859 pub fn row(&self, row: R) -> Option<&HybridBitSet<C>> {
1860 self.rows.get(row)?.as_ref()
1863 /// Intersects `row` with `set`. `set` can be either `BitSet` or
1864 /// `HybridBitSet`. Has no effect if `row` does not exist.
1866 /// Returns true if the row was changed.
1867 pub fn intersect_row<Set>(&mut self, row: R, set: &Set) -> bool
1869 HybridBitSet<C>: BitRelations<Set>,
1871 match self.rows.get_mut(row) {
1872 Some(Some(row)) => row.intersect(set),
1877 /// Subtracts `set from `row`. `set` can be either `BitSet` or
1878 /// `HybridBitSet`. Has no effect if `row` does not exist.
1880 /// Returns true if the row was changed.
1881 pub fn subtract_row<Set>(&mut self, row: R, set: &Set) -> bool
1883 HybridBitSet<C>: BitRelations<Set>,
1885 match self.rows.get_mut(row) {
1886 Some(Some(row)) => row.subtract(set),
1891 /// Unions `row` with `set`. `set` can be either `BitSet` or
1894 /// Returns true if the row was changed.
1895 pub fn union_row<Set>(&mut self, row: R, set: &Set) -> bool
1897 HybridBitSet<C>: BitRelations<Set>,
1899 self.ensure_row(row).union(set)
1904 fn num_words<T: Idx>(domain_size: T) -> usize {
1905 (domain_size.index() + WORD_BITS - 1) / WORD_BITS
1909 fn num_chunks<T: Idx>(domain_size: T) -> usize {
1910 assert!(domain_size.index() > 0);
1911 (domain_size.index() + CHUNK_BITS - 1) / CHUNK_BITS
1915 fn word_index_and_mask<T: Idx>(elem: T) -> (usize, Word) {
1916 let elem = elem.index();
1917 let word_index = elem / WORD_BITS;
1918 let mask = 1 << (elem % WORD_BITS);
1923 fn chunk_index<T: Idx>(elem: T) -> usize {
1924 elem.index() / CHUNK_BITS
1928 fn chunk_word_index_and_mask<T: Idx>(elem: T) -> (usize, Word) {
1929 let chunk_elem = elem.index() % CHUNK_BITS;
1930 word_index_and_mask(chunk_elem)
1933 fn clear_excess_bits_in_final_word(domain_size: usize, words: &mut [Word]) {
1934 let num_bits_in_final_word = domain_size % WORD_BITS;
1935 if num_bits_in_final_word > 0 {
1936 let mask = (1 << num_bits_in_final_word) - 1;
1937 words[words.len() - 1] &= mask;
1942 fn max_bit(word: Word) -> usize {
1943 WORD_BITS - 1 - word.leading_zeros() as usize
1946 /// Integral type used to represent the bit set.
1947 pub trait FiniteBitSetTy:
1948 BitAnd<Output = Self>
1954 + Not<Output = Self>
1958 /// Size of the domain representable by this type, e.g. 64 for `u64`.
1959 const DOMAIN_SIZE: u32;
1961 /// Value which represents the `FiniteBitSet` having every bit set.
1963 /// Value which represents the `FiniteBitSet` having no bits set.
1966 /// Value for one as the integral type.
1968 /// Value for zero as the integral type.
1971 /// Perform a checked left shift on the integral type.
1972 fn checked_shl(self, rhs: u32) -> Option<Self>;
1973 /// Perform a checked right shift on the integral type.
1974 fn checked_shr(self, rhs: u32) -> Option<Self>;
1977 impl FiniteBitSetTy for u32 {
1978 const DOMAIN_SIZE: u32 = 32;
1980 const FILLED: Self = Self::MAX;
1981 const EMPTY: Self = Self::MIN;
1983 const ONE: Self = 1u32;
1984 const ZERO: Self = 0u32;
1986 fn checked_shl(self, rhs: u32) -> Option<Self> {
1987 self.checked_shl(rhs)
1990 fn checked_shr(self, rhs: u32) -> Option<Self> {
1991 self.checked_shr(rhs)
1995 impl std::fmt::Debug for FiniteBitSet<u32> {
1996 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
1997 write!(f, "{:032b}", self.0)
2001 impl FiniteBitSetTy for u64 {
2002 const DOMAIN_SIZE: u32 = 64;
2004 const FILLED: Self = Self::MAX;
2005 const EMPTY: Self = Self::MIN;
2007 const ONE: Self = 1u64;
2008 const ZERO: Self = 0u64;
2010 fn checked_shl(self, rhs: u32) -> Option<Self> {
2011 self.checked_shl(rhs)
2014 fn checked_shr(self, rhs: u32) -> Option<Self> {
2015 self.checked_shr(rhs)
2019 impl std::fmt::Debug for FiniteBitSet<u64> {
2020 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2021 write!(f, "{:064b}", self.0)
2025 impl FiniteBitSetTy for u128 {
2026 const DOMAIN_SIZE: u32 = 128;
2028 const FILLED: Self = Self::MAX;
2029 const EMPTY: Self = Self::MIN;
2031 const ONE: Self = 1u128;
2032 const ZERO: Self = 0u128;
2034 fn checked_shl(self, rhs: u32) -> Option<Self> {
2035 self.checked_shl(rhs)
2038 fn checked_shr(self, rhs: u32) -> Option<Self> {
2039 self.checked_shr(rhs)
2043 impl std::fmt::Debug for FiniteBitSet<u128> {
2044 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2045 write!(f, "{:0128b}", self.0)
2049 /// A fixed-sized bitset type represented by an integer type. Indices outwith than the range
2050 /// representable by `T` are considered set.
2051 #[derive(Copy, Clone, Eq, PartialEq, Decodable, Encodable)]
2052 pub struct FiniteBitSet<T: FiniteBitSetTy>(pub T);
2054 impl<T: FiniteBitSetTy> FiniteBitSet<T> {
2055 /// Creates a new, empty bitset.
2056 pub fn new_empty() -> Self {
2060 /// Sets the `index`th bit.
2061 pub fn set(&mut self, index: u32) {
2062 self.0 |= T::ONE.checked_shl(index).unwrap_or(T::ZERO);
2065 /// Unsets the `index`th bit.
2066 pub fn clear(&mut self, index: u32) {
2067 self.0 &= !T::ONE.checked_shl(index).unwrap_or(T::ZERO);
2070 /// Sets the `i`th to `j`th bits.
2071 pub fn set_range(&mut self, range: Range<u32>) {
2072 let bits = T::FILLED
2073 .checked_shl(range.end - range.start)
2076 .checked_shl(range.start)
2077 .unwrap_or(T::ZERO);
2081 /// Is the set empty?
2082 pub fn is_empty(&self) -> bool {
2086 /// Returns the domain size of the bitset.
2087 pub fn within_domain(&self, index: u32) -> bool {
2088 index < T::DOMAIN_SIZE
2091 /// Returns if the `index`th bit is set.
2092 pub fn contains(&self, index: u32) -> Option<bool> {
2093 self.within_domain(index)
2094 .then(|| ((self.0.checked_shr(index).unwrap_or(T::ONE)) & T::ONE) == T::ONE)
2098 impl<T: FiniteBitSetTy> Default for FiniteBitSet<T> {
2099 fn default() -> Self {