wickra_core/indicators/
donchian.rs

1//! Donchian Channels.
2
3use std::collections::VecDeque;
4
5use crate::error::{Error, Result};
6use crate::ohlcv::Candle;
7use crate::traits::Indicator;
8
9/// Donchian Channels output.
10#[derive(Debug, Clone, Copy, PartialEq)]
11pub struct DonchianOutput {
12    /// Highest high over the lookback.
13    pub upper: f64,
14    /// Average of upper and lower.
15    pub middle: f64,
16    /// Lowest low over the lookback.
17    pub lower: f64,
18}
19
20/// Donchian Channels: rolling highest high / lowest low envelopes.
21///
22/// # Example
23///
24/// ```
25/// use wickra_core::{Candle, Indicator, Donchian};
26///
27/// let mut indicator = Donchian::new(5).unwrap();
28/// let mut last = None;
29/// for i in 0..80 {
30///     let base = 100.0 + f64::from(i);
31///     let candle =
32///         Candle::new(base, base + 2.0, base - 2.0, base + 1.0, 10.0, i64::from(i)).unwrap();
33///     last = indicator.update(candle);
34/// }
35/// assert!(last.is_some());
36/// ```
37#[derive(Debug, Clone)]
38pub struct Donchian {
39    period: usize,
40    candles: VecDeque<Candle>,
41}
42
43impl Donchian {
44    /// # Errors
45    /// Returns [`Error::PeriodZero`] if `period == 0`.
46    pub fn new(period: usize) -> Result<Self> {
47        if period == 0 {
48            return Err(Error::PeriodZero);
49        }
50        if period > crate::error::MAX_PERIOD {
51            return Err(Error::InvalidPeriod {
52                message: crate::error::PERIOD_ABOVE_MAX,
53            });
54        }
55        Ok(Self {
56            period,
57            candles: VecDeque::with_capacity(period),
58        })
59    }
60
61    /// Configured period.
62    pub const fn period(&self) -> usize {
63        self.period
64    }
65}
66
67impl Indicator for Donchian {
68    type Input = Candle;
69    type Output = DonchianOutput;
70
71    #[inline]
72    fn update(&mut self, candle: Candle) -> Option<DonchianOutput> {
73        if self.candles.len() == self.period {
74            self.candles.pop_front();
75        }
76        self.candles.push_back(candle);
77        if self.candles.len() < self.period {
78            return None;
79        }
80        let upper = self
81            .candles
82            .iter()
83            .map(|c| c.high)
84            .fold(f64::NEG_INFINITY, f64::max);
85        let lower = self
86            .candles
87            .iter()
88            .map(|c| c.low)
89            .fold(f64::INFINITY, f64::min);
90        Some(DonchianOutput {
91            upper,
92            middle: f64::midpoint(upper, lower),
93            lower,
94        })
95    }
96
97    fn reset(&mut self) {
98        self.candles.clear();
99    }
100
101    #[inline]
102    fn warmup_period(&self) -> usize {
103        self.period
104    }
105
106    #[inline]
107    fn is_ready(&self) -> bool {
108        self.candles.len() == self.period
109    }
110
111    #[inline]
112    fn name(&self) -> &'static str {
113        "DonchianChannels"
114    }
115}
116
117#[cfg(test)]
118mod tests {
119    use super::*;
120    use crate::traits::BatchExt;
121    use approx::assert_relative_eq;
122
123    fn c(h: f64, l: f64, cl: f64) -> Candle {
124        Candle::new(cl, h, l, cl, 1.0, 0).unwrap()
125    }
126
127    #[test]
128    fn flat_market_yields_equal_bands() {
129        let candles: Vec<Candle> = (0..20).map(|_| c(11.0, 9.0, 10.0)).collect();
130        let mut d = Donchian::new(5).unwrap();
131        let last = d.batch(&candles).into_iter().flatten().last().unwrap();
132        assert_relative_eq!(last.upper, 11.0, epsilon = 1e-12);
133        assert_relative_eq!(last.lower, 9.0, epsilon = 1e-12);
134        assert_relative_eq!(last.middle, 10.0, epsilon = 1e-12);
135    }
136
137    #[test]
138    fn batch_equals_streaming() {
139        let candles: Vec<Candle> = (0..40)
140            .map(|i| c(f64::from(i) + 2.0, f64::from(i), f64::from(i) + 1.0))
141            .collect();
142        let mut a = Donchian::new(10).unwrap();
143        let mut b = Donchian::new(10).unwrap();
144        assert_eq!(
145            a.batch(&candles),
146            candles.iter().map(|x| b.update(*x)).collect::<Vec<_>>()
147        );
148    }
149
150    #[test]
151    fn upper_above_middle_above_lower() {
152        let candles: Vec<Candle> = (0..50)
153            .map(|i| c(f64::from(i) + 1.0, f64::from(i) - 1.0, f64::from(i)))
154            .collect();
155        let mut d = Donchian::new(10).unwrap();
156        for o in d.batch(&candles).into_iter().flatten() {
157            assert!(o.upper >= o.middle);
158            assert!(o.middle >= o.lower);
159        }
160    }
161
162    #[test]
163    fn rejects_zero_period() {
164        assert!(Donchian::new(0).is_err());
165    }
166
167    /// Cover the const accessor `period` (57-59) and the Indicator-impl
168    /// `warmup_period` (95-97) + `name` (103-105). Existing tests never
169    /// inspect these metadata methods.
170    #[test]
171    fn accessors_and_metadata() {
172        let d = Donchian::new(20).unwrap();
173        assert_eq!(d.period(), 20);
174        assert_eq!(d.warmup_period(), 20);
175        assert_eq!(d.name(), "DonchianChannels");
176    }
177
178    #[test]
179    fn reset_clears_state() {
180        let candles: Vec<Candle> = (0..20)
181            .map(|i| c(f64::from(i) + 1.0, f64::from(i) - 1.0, f64::from(i)))
182            .collect();
183        let mut d = Donchian::new(5).unwrap();
184        d.batch(&candles);
185        assert!(d.is_ready());
186        d.reset();
187        assert!(!d.is_ready());
188        assert_eq!(d.update(candles[0]), None);
189    }
190}
wickra_core/indicators/donchian.rs

wickra_core/indicators/
donchian.rs
