pibs 0.1.2

A primitive integer bitset for high-performance combinatorics
Documentation
//! Set operations for [`BitSet`] that make sense over any universe.
//!
//! For methods specific to integer sets, see [`math`].

use crate::*;

impl<W: Word> BitSet<W> {
    /// An iterator over the elements in ascending order.
    ///
    /// Note that [`Self::iter`] takes the set by value and yields elements by value, making it
    /// equivalent to [`Self::into_iter`]. This is because [`BitSet`] implements [`Copy`] at a
    /// trivial cost and only stores elements in a compressed representation.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let set = set![7, 3..=5, 1];
    /// assert!(set.iter().eq([1, 3, 4, 5, 7]));
    /// assert!(set.iter().rev().eq([7, 5, 4, 3, 1]));
    /// ```
    #[inline]
    pub fn iter(self) -> BitSetIter<W> {
        BitSetIter::<W>(self.0)
    }

    /// The set with an element added to it (or left in).
    ///
    /// This is the same as `self + e`.
    ///
    /// # Preconditions
    ///
    /// The caller must ensure that `e <= Self::MAX`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let set = set![1..=3];
    /// assert_eq!(set.with(2), set![1..=3]); // Does nothing.
    /// assert_eq!(set.with(4), set![1..=4]);
    /// ```
    #[inline]
    pub fn with(self, e: Element) -> Self {
        Self::debug_bound_check(e);
        Self(self.0 | W::ONE << e)
    }

    /// The set with an element removed from it (if present).
    ///
    /// This is the same as `self - e`.
    ///
    /// # Preconditions
    ///
    /// The caller must ensure that `e <= Self::MAX`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let set = set![1..=3];
    /// assert_eq!(set.without(2), set![1, 3]);
    /// assert_eq!(set.without(4), set![1..=3]); // Does nothing.
    /// ```
    #[inline]
    pub fn without(self, e: Element) -> Self {
        Self::debug_bound_check(e);
        Self(self.0 & !(W::ONE << e))
    }

    /// The union of two sets.
    ///
    /// This is the same as `self | other`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let a = set![1..=5];
    /// let b = set![3..=7];
    /// assert_eq!(a.union(b), set![1..=7]);
    /// ```
    #[inline]
    pub fn union(self, other: Self) -> Self {
        Self(self.0 | other.0)
    }

    /// The intersection of two sets.
    ///
    /// This is the same as `self & other`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let a = set![1..=5];
    /// let b = set![3..=7];
    /// assert_eq!(a.intersection(b), set![3..=5]);
    /// ```
    #[inline]
    pub fn intersection(self, other: Self) -> Self {
        Self(self.0 & other.0)
    }

    /// The set with every element also present in another set removed.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let a = set![1..=5];
    /// let b = set![3..=7];
    /// assert_eq!(a.difference(b), set![1..=2]);
    /// ```
    #[inline]
    pub fn difference(self, other: Self) -> Self {
        Self(self.0 & !other.0)
    }

    /// The symmetric difference of two sets.
    ///
    /// This is the same as `self ^ other`.
    ///
    /// # Examples
    ///
    /// ```
    /// # use pibs::prelude::*;
    /// let a = set![1..=5];
    /// let b = set![3..=7];
    /// assert_eq!(a.symmetric_difference(b), set![1..=2, 6..=7]);
    /// ```
    #[inline]
    pub fn symmetric_difference(self, other: Self) -> Self {
        Self(self.0 ^ other.0)
    }
}