set_theory 1.0.0

//! # MathSet Trait
//!
//! Defines the core interface for mathematical set operations.
//!
//! This trait abstracts common set operations, allowing different
//! implementations (CustomSet, FrozenSet, MultiSet) to share a common API.

use std::hash::Hash;

/// Core trait for mathematical set operations.
///
/// All set implementations should implement this trait to ensure
/// consistent behavior across the library.
///
/// # Type Parameters
///
/// * `T` - The type of elements in the set. Must implement `Eq + Hash + Clone`
///
/// # Examples
///
/// ```rust
/// use set_theory::traits::MathSet;
/// use set_theory::models::CustomSet;
///
/// let set = CustomSet::from(vec![1, 2, 3]);
/// assert_eq!(set.cardinality(), 3);
/// assert!(set.contains(&2));
/// ```
pub trait MathSet<T: Eq + Hash + Clone> {
    /// Returns the cardinality (number of elements) in the set.
    ///
    /// # Notation
    ///
    /// |A| or n(A)
    ///
    /// # Returns
    ///
    /// The number of unique elements in the set.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let set = CustomSet::from(vec![1, 2, 3]);
    /// assert_eq!(set.cardinality(), 3);
    /// ```
    fn cardinality(&self) -> usize;

    /// Checks if an element is a member of this set.
    ///
    /// # Notation
    ///
    /// x ∈ A
    ///
    /// # Arguments
    ///
    /// * `element` - Reference to the element to check
    ///
    /// # Returns
    ///
    /// `true` if the element is in the set, `false` otherwise.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let set = CustomSet::from(vec![1, 2, 3]);
    /// assert!(set.contains(&2));
    /// assert!(!set.contains(&5));
    /// ```
    fn contains(&self, element: &T) -> bool;

    /// Checks if this set is a subset of another set.
    ///
    /// # Notation
    ///
    /// A ⊆ B
    ///
    /// # Arguments
    ///
    /// * `other` - Reference to the other set
    ///
    /// # Returns
    ///
    /// `true` if every element of this set is also in the other set.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let a = CustomSet::from(vec![1, 2, 3]);
    /// let b = CustomSet::from(vec![1, 2, 3, 4, 5]);
    /// assert!(a.is_subset_of(&b));
    /// ```
    fn is_subset_of(&self, other: &Self) -> bool;

    /// Checks if this set is a proper subset of another set.
    ///
    /// # Notation
    ///
    /// A ⊂ B
    ///
    /// # Arguments
    ///
    /// * `other` - Reference to the other set
    ///
    /// # Returns
    ///
    /// `true` if this set is a subset of other and not equal to other.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let a = CustomSet::from(vec![1, 2, 3]);
    /// let b = CustomSet::from(vec![1, 2, 3]);
    /// let c = CustomSet::from(vec![1, 2, 3, 4]);
    /// assert!(!a.is_proper_subset_of(&b));
    /// assert!(a.is_proper_subset_of(&c));
    /// ```
    fn is_proper_subset_of(&self, other: &Self) -> bool;

    /// Checks if this set is equal to another set.
    ///
    /// # Notation
    ///
    /// A = B
    ///
    /// # Arguments
    ///
    /// * `other` - Reference to the other set
    ///
    /// # Returns
    ///
    /// `true` if both sets contain exactly the same elements.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let a = CustomSet::from(vec![1, 2, 3]);
    /// let b = CustomSet::from(vec![3, 2, 1]);
    /// assert!(a.equals(&b));
    /// ```
    fn equals(&self, other: &Self) -> bool;

    /// Checks if this set is disjoint from another set.
    ///
    /// # Notation
    ///
    /// A // B
    ///
    /// # Arguments
    ///
    /// * `other` - Reference to the other set
    ///
    /// # Returns
    ///
    /// `true` if the sets have no elements in common.
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let a = CustomSet::from(vec![1, 2, 3]);
    /// let b = CustomSet::from(vec![4, 5, 6]);
    /// assert!(a.is_disjoint_from(&b));
    /// ```
    fn is_disjoint_from(&self, other: &Self) -> bool;

    /// Returns true if the set contains no elements.
    ///
    /// # Notation
    ///
    /// A = ∅
    ///
    /// # Examples
    ///
    /// ```rust
    /// use set_theory::models::CustomSet;
    ///
    /// let empty = CustomSet::<i32>::empty();
    /// assert!(empty.is_empty());
    /// ```
    fn is_empty(&self) -> bool;
}