enum_rotate/
lib.rs

1extern crate self as enum_rotate;
2
3pub use derive_enum_rotate::EnumRotate;
4
5/// Trait implementing iterator-like behavior for enums.
6///
7/// Implementing this trait provides the
8/// [`next`], [`prev`], [`rotate_next`], [`rotate_prev`], [`iter`], and [`iter_from`] methods on any enum.
9///
10/// An implementation of this trait describes an *iteration order* of the enum's variants.
11/// An iteration order is simply an ordering of **all** the variants of the enum with each variant
12/// appearing exactly once. Any given implementation of this trait must ensure that all functions
13/// respect the same iteration order.
14///
15/// This trait should only be implemented for enums, if this trait is implemented for a struct or
16/// a union, its requirements are unspecified and the behavior of some of the default implementations
17/// is also unspecified.
18///
19/// Note that this trait currently excludes enums with non-empty (and not effectively unit) tuple or struct
20/// variants due to how the [`next`], [`prev`], [`rotate_next`], and [`rotate_prev`] functions are defined.
21/// This is because any information carried by a variant would be overridden by calling `.next().prev()`,
22/// which would break an invariant. This part of the specification might change in the future.
23///
24/// It is recommended to implement this trait using the provided derive macro like this:
25/// ```rust
26/// use enum_rotate::EnumRotate;
27///
28/// #[derive(EnumRotate, Copy, Clone)]
29/// enum Enum { A, B, C }
30/// ```
31///
32/// Here is a brief overview of the functions in this trait:
33///
34///  - The [`next`] and [`prev`] functions cycle through the variants of the enum.
35///
36///    The implementation must
37///    ensure that
38///    - `x.next().prev() == x` is always true
39///    - `x.prev().next() == x` is always true
40///    - [`next`] and [`prev`] describe the same iteration order as all the other functions
41///
42///  - The [`rotate_next`] and [`rotate_prev`] functions are in-place versions of [`next`] and [`prev`] respectively.
43///    They modify the receiver they operate on and return a copy of the new value.
44///
45///    The implementation must ensure that
46///    - `x.rotate_next(); x.rotate_prev()` will leave `x` unchanged
47///    - `x.rotate_prev(); x.rotate_next()` will leave `x` unchanged
48///    - [`rotate_next`] and [`rotate_prev`] describe the same iteration order as all the other functions
49///
50///  - The [`iter`] function returns an iterator over the variants of the enum.
51///
52///    The implementation must ensure that the iterator returned by [`iter`]
53///    - Returns each variant of the enum **exactly once**
54///    - Describes the same iteration order as all the other functions
55///
56///    No guarantees are made about the precise type of the iterator.
57///
58///  - The [`iter_from`] function returns an iterator over the variants of the enum starting from a given variant.
59///    The implementation must ensure that the iterator returned by [`iter_from`]
60///    - Returns the variant passed to [`iter_from`] as its first element
61///    - Returns each variant of the enum **exactly once**
62///    - Describes the same iteration order as all the other functions
63///
64///     No guarantees are made about the precise type of the iterator
65///
66/// [`next`]: EnumRotate::next
67/// [`prev`]: EnumRotate::prev
68/// [`rotate_next`]: EnumRotate::rotate_next
69/// [`rotate_prev`]: EnumRotate::rotate_prev
70/// [`iter`]: EnumRotate::iter
71/// [`iter_from`]: EnumRotate::iter_from
72pub trait EnumRotate
73where
74    Self: Sized,
75{
76    /// This method returns the **next** variant in the *iteration order* described by this implementation.
77    ///
78    /// Example:
79    /// ```rust
80    /// use enum_rotate::EnumRotate;
81    /// use Enum::*;
82    ///
83    /// #[derive(EnumRotate, Copy, Clone, PartialEq, Debug)]
84    /// enum Enum { A, B, C }
85    ///
86    /// fn main() {
87    ///     assert_eq!(A.next(), B)
88    /// }
89    /// ```
90    #[must_use]
91    fn next(&self) -> Self;
92
93    /// This method returns the **previous** variant in the *iteration order* described by this implementation
94    #[must_use]
95    fn prev(&self) -> Self;
96
97    /// This method assigns the **next** variant in the *iteration order* described by this implementation
98    /// to the receiver and returns the new value
99    fn rotate_next(&mut self) -> &Self {
100        *self = self.next();
101        self
102    }
103
104    /// This method assigns the **previous** variant in the *iteration order* described by this implementation
105    /// to the receiver and returns the new value
106    fn rotate_prev(&mut self) -> &Self {
107        *self = self.prev();
108        self
109    }
110
111    // TODO: docs
112    fn iter() -> impl Iterator<Item = Self>;
113
114    // TODO: docs
115    fn iter_from(&self) -> impl Iterator<Item = Self>;
116}
enum_rotate/lib.rs

enum_rotate/
lib.rs
