ring_seq/
lib.rs

1//! Circular (ring) sequence operations for Rust slices.
2//!
3//! Reach the circular API by calling [`AsCircular::circular`] on any slice,
4//! [`Vec<T>`](alloc::vec::Vec), array, or [`Box<[T]>`](alloc::boxed::Box).
5//! The returned [`Circular`] wrapper is the single home for every circular
6//! operation; every transform it offers is lazy and allocation-free.
7//!
8//! # Quick start
9//!
10//! ```
11//! use ring_seq::AsCircular;
12//!
13//! let r = [10, 20, 30].circular();
14//!
15//! // Indexing wraps in both directions
16//! assert_eq!(*r.apply(4), 20);
17//! assert_eq!(*r.apply(-1), 30);
18//!
19//! // Reindexed views — no allocation
20//! let rotated: Vec<_> = r.rotate_right(1).iter().copied().collect();
21//! assert_eq!(rotated, vec![30, 10, 20]);
22//!
23//! // Comparisons up to rotation/reflection
24//! assert!(r.is_rotation_of(&[20, 30, 10]));
25//! assert!(r.is_reflection_of(&[10, 30, 20]));
26//!
27//! // Canonical (necklace) form — uses Booth's O(n)
28//! assert_eq!(r.canonical(), vec![10, 20, 30]);
29//!
30//! // Lazy iterators of views
31//! let firsts: Vec<i32> = r.rotations().map(|v| *v.apply(0)).collect();
32//! assert_eq!(firsts, vec![10, 20, 30]);
33//! ```
34//!
35//! # `no_std`
36//!
37//! The crate is `#![no_std]`. The default `alloc` feature enables the
38//! methods that return owned collections ([`Circular::to_vec`],
39//! [`Circular::canonical`], [`Circular::bracelet`],
40//! [`Circular::symmetry_indices`],
41//! [`Circular::reflectional_symmetry_axes`]) and the implementation of
42//! [`Circular::canonical_index`] (Booth's algorithm allocates internally).
43//! With `--no-default-features` the wrapper and its element/view iterators
44//! remain available and depend only on `core`.
45
46#![no_std]
47
48#[cfg(feature = "alloc")]
49extern crate alloc;
50
51mod circular;
52
53pub use circular::{
54    AsCircular, Circular, CircularIter, Enumerate, Reflections, Reversions, Rotations,
55    RotationsAndReflections, Windows,
56};
57
58// ============================================================================
59// AxisLocation
60// ============================================================================
61
62/// A location on a circular sequence where a reflectional-symmetry axis
63/// passes.
64///
65/// # Variants
66///
67/// * [`Vertex`](AxisLocation::Vertex) — the axis passes through the
68///   element at the given index.
69/// * [`Edge`](AxisLocation::Edge) — the axis passes between two
70///   consecutive elements.
71#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
72pub enum AxisLocation {
73    /// The axis passes through the element at this index.
74    Vertex(usize),
75    /// The axis passes between the elements at these two consecutive indices.
76    /// The invariant `j == (i + 1) % n` is maintained by
77    /// [`AxisLocation::edge`].
78    Edge(usize, usize),
79}
80
81impl AxisLocation {
82    /// Constructs an [`Edge`](AxisLocation::Edge) between consecutive
83    /// elements of a ring of size `n`, starting at index `i`.
84    ///
85    /// The second index is computed as `(i + 1) % n`.
86    ///
87    /// # Panics
88    ///
89    /// Panics if `n` is zero.
90    ///
91    /// # Examples
92    ///
93    /// ```
94    /// use ring_seq::AxisLocation;
95    ///
96    /// assert_eq!(AxisLocation::edge(2, 3), AxisLocation::Edge(2, 0));
97    /// assert_eq!(AxisLocation::edge(0, 4), AxisLocation::Edge(0, 1));
98    /// ```
99    #[must_use]
100    pub fn edge(i: usize, n: usize) -> Self {
101        assert!(n > 0, "ring size must be positive");
102        let ii = i % n;
103        AxisLocation::Edge(ii, (ii + 1) % n)
104    }
105}
106
107#[cfg(test)]
108mod axis_tests {
109    use super::*;
110
111    #[test]
112    fn edge_constructor() {
113        assert_eq!(AxisLocation::edge(2, 3), AxisLocation::Edge(2, 0));
114        assert_eq!(AxisLocation::edge(0, 4), AxisLocation::Edge(0, 1));
115        assert_eq!(AxisLocation::edge(3, 4), AxisLocation::Edge(3, 0));
116    }
117
118    #[test]
119    #[should_panic(expected = "ring size must be positive")]
120    fn edge_zero_size_panics() {
121        let _ = AxisLocation::edge(0, 0);
122    }
123}
ring_seq/lib.rs

ring_seq/
lib.rs
