devela/num/quant/
cycle.rs

Help
1// devela::num::quant::cycle
2//
3//! Defines [`Cycle`], [`CycleCount`].
4//
5
6/// A repeating cycle defined by a fundamental period.
7///
8/// A `Cycle` encapsulates the basic unit over which any phenomenon repeats,
9/// whether in time, space, or any abstract domain. It is the foundation for
10/// constructing more complex periodic behaviors.
11#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
12pub struct Cycle<T> {
13    /// The fundamental period of the cycle.
14    pub period: T,
15}
16
17/// A cycle that repeats a fixed number of times.
18///
19/// `CycleCount` couples a fundamental `Cycle` with a discrete repetition count.
20///
21/// This is useful when the number of repetitions is significant.
22/// For example, when an animation should loop a specified number of times.
23#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
24pub struct CycleCount<T, N> {
25    /// The underlying repeating cycle.
26    pub cycle: Cycle<T>,
27    /// The total number of repetitions.
28    pub count: N,
29}
30
31// WIPZONE
32
33/// Cyclic behavior.
34///
35/// Defines operations common to periodic structures, such as retrieving
36/// the period, normalizing values within the cycle, applying offsets,
37/// and handling bounded or repeated cycles.
38pub trait Cycled<T> {
39    /// Returns the fundamental period of the cycle.
40    fn cycle_period(&self) -> T;
41
42    /// Normalizes a value within the cycle's periodic range.
43    ///
44    /// Ensures that the input `value` is wrapped within `[0, period)`.
45    fn cycle_normalize(&self, value: T) -> T;
46
47    ///
48    fn cycle_count(&self) -> T;
49
50    ///
51    fn cycle_offset(&self) -> T;
52
53    /// Advances the cycle by a given offset.
54    ///
55    /// This may modify internal state or return a new cycle with the offset applied.
56    fn with_offset(&self, offset: T) -> Self;
57
58    /// Determines how many complete cycles fit within a given range.
59    ///
60    /// This method is useful for bounded or counted cycles.
61    fn cycles_in_range(&self, range: T) -> T;
62}
devela/num/quant/cycle.rs

devela/num/quant/
cycle.rs
