Skip to main content

ferrochart_orderflow/
levels.rs

1//! Price levels: prices are stored as level numbers
2//! `floor(price / step + 0.5)`, where `step = tick_size × row_size`.
3
4use ferrochart_core::error::{Error, Result};
5
6/// The price grid of an order flow series.
7///
8/// # Examples
9///
10/// ```
11/// use ferrochart_orderflow::PriceLevels;
12///
13/// // 0.25 ticks, two ticks per row: rows 0.5 apart.
14/// let levels = PriceLevels::new(0.25, 2)?;
15/// assert_eq!(levels.level(100.2), Some(200));
16/// assert_eq!(levels.level(100.26), Some(201));
17/// assert_eq!(levels.price(201), 100.5);
18/// assert_eq!(levels.edges(201), (100.25, 100.75));
19/// # Ok::<(), ferrochart_core::Error>(())
20/// ```
21#[derive(Clone, Copy, Debug, PartialEq)]
22pub struct PriceLevels {
23    step: f64,
24}
25
26impl PriceLevels {
27    /// Rows of `row_size` ticks of `tick_size`.
28    ///
29    /// # Errors
30    ///
31    /// [`Error::InvalidArgument`] if `tick_size` is not finite and positive
32    /// or `row_size` is 0.
33    pub fn new(tick_size: f64, row_size: u32) -> Result<Self> {
34        let step = tick_size * f64::from(row_size);
35        if !(tick_size.is_finite() && tick_size > 0.0) || row_size == 0 || !step.is_finite() {
36            return Err(Error::InvalidArgument(
37                "tick_size must be finite and positive, row_size at least 1",
38            ));
39        }
40        Ok(Self { step })
41    }
42
43    /// Height of a row in price.
44    pub fn step(&self) -> f64 {
45        self.step
46    }
47
48    /// The level of `price`; `None` if it is not finite or out of range.
49    pub fn level(&self, price: f64) -> Option<i32> {
50        let l = (price / self.step + 0.5).floor();
51        (l.is_finite() && l >= f64::from(i32::MIN) && l <= f64::from(i32::MAX)).then_some(l as i32)
52    }
53
54    /// The price at the center of `level`.
55    pub fn price(&self, level: i32) -> f64 {
56        f64::from(level) * self.step
57    }
58
59    /// The lower and upper edge of `level`.
60    pub fn edges(&self, level: i32) -> (f64, f64) {
61        let p = self.price(level);
62        (p - self.step / 2.0, p + self.step / 2.0)
63    }
64}
65
66#[cfg(test)]
67mod tests {
68    use super::*;
69
70    #[test]
71    fn rejects_bad_grids() {
72        for (tick, rows) in [
73            (0.0, 1),
74            (-1.0, 1),
75            (f64::NAN, 1),
76            (f64::INFINITY, 1),
77            (1.0, 0),
78        ] {
79            assert!(PriceLevels::new(tick, rows).is_err(), "{tick} {rows}");
80        }
81        let l = PriceLevels::new(1.0, 1).unwrap();
82        assert_eq!(l.level(f64::NAN), None);
83        assert_eq!(l.level(1e300), None);
84        assert_eq!(l.level(-0.6), Some(-1));
85        assert_eq!(l.level(-0.5), Some(0));
86    }
87}