acls-rs 0.1.1

Algebraically-correct permissions system with RBAC, ABAC, and temporal support
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110

//! Monoid algebraic structure.
//!
//! A monoid is a semigroup with an identity element.
//!
//! # Algebraic Laws
//!
//! For a type to implement `Monoid`, it must satisfy:
//!
//! - **Associativity**: `(a ∘ b) ∘ c = a ∘ (b ∘ c)` (inherited from Semigroup)
//! - **Left Identity**: `e ∘ a = a` for all `a`
//! - **Right Identity**: `a ∘ e = a` for all `a`
//!
//! where `e` is the identity element.

use super::Semigroup;
use std::collections::BTreeSet;

/// A monoid: a semigroup with an identity element.
///
/// # Laws
///
/// Implementations must satisfy (in addition to semigroup laws):
/// - **Left Identity**: `Monoid::identity().combine(a) == a`
/// - **Right Identity**: `a.combine(Monoid::identity()) == a`
pub trait Monoid: Semigroup {
    /// Return the identity element.
    ///
    /// The identity element must satisfy:
    /// - `identity().combine(a) == a` (left identity)
    /// - `a.combine(identity()) == a` (right identity)
    ///
    /// # Examples
    ///
    /// ```
    /// use acls_rs::algebra::Monoid;
    /// use acls_rs::permission::PermissionSet;
    ///
    /// let empty = PermissionSet::identity();
    /// assert!(empty.is_empty());
    /// ```
    fn identity() -> Self;

    /// Combine all elements from an iterator, using identity for empty iterators.
    ///
    /// Unlike `Semigroup::combine_all`, this always returns a value, using the
    /// identity element when the iterator is empty.
    ///
    /// # Examples
    ///
    /// ```
    /// use acls_rs::algebra::Monoid;
    /// use acls_rs::permission::PermissionSet;
    ///
    /// let empty: Vec<PermissionSet> = vec![];
    /// let result = PermissionSet::combine_all_with_identity(empty);
    /// assert_eq!(result, PermissionSet::identity());
    /// ```
    fn combine_all_with_identity<I: IntoIterator<Item = Self>>(iter: I) -> Self {
        Self::combine_all(iter).unwrap_or_else(Self::identity)
    }
}

// Blanket implementation for BTreeSet
impl<T: Ord + Clone> Monoid for BTreeSet<T> {
    #[inline]
    fn identity() -> Self {
        BTreeSet::new()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::algebra::Semigroup;

    #[test]
    fn test_btreeset_left_identity() {
        let a: BTreeSet<i32> = [1, 2, 3].iter().cloned().collect();
        let e = BTreeSet::identity();

        assert_eq!(e.combine(a.clone()), a);
    }

    #[test]
    fn test_btreeset_right_identity() {
        let a: BTreeSet<i32> = [1, 2, 3].iter().cloned().collect();
        let e = BTreeSet::identity();

        assert_eq!(a.clone().combine(e), a);
    }

    #[test]
    fn test_combine_all_with_identity_empty() {
        let empty: Vec<BTreeSet<i32>> = vec![];
        let result = BTreeSet::combine_all_with_identity(empty);

        assert_eq!(result, BTreeSet::identity());
    }

    #[test]
    fn test_combine_all_with_identity_nonempty() {
        let sets = vec![
            [1, 2].iter().cloned().collect::<BTreeSet<_>>(),
            [3, 4].iter().cloned().collect::<BTreeSet<_>>(),
        ];

        let result = BTreeSet::combine_all_with_identity(sets);
        assert_eq!(result, [1, 2, 3, 4].iter().cloned().collect());
    }
}