wickra_core/indicators/
true_range.rs

1//! True Range.
2
3use crate::ohlcv::Candle;
4use crate::traits::Indicator;
5
6/// True Range — the single-bar building block of every ATR-based indicator.
7///
8/// ```text
9/// TR = max( high − low, |high − close_prev|, |low − close_prev| )
10/// ```
11///
12/// True Range is the greatest of the bar's own range and the two gaps to the
13/// previous close, so it captures volatility that opens *between* bars rather
14/// than only within them. The first bar has no previous close and falls back
15/// to `high − low`. Where [`Atr`](crate::Atr) smooths this series, `TrueRange`
16/// exposes it raw, one value per bar.
17///
18/// # Example
19///
20/// ```
21/// use wickra_core::{Candle, Indicator, TrueRange};
22///
23/// let mut indicator = TrueRange::new();
24/// let mut last = None;
25/// for i in 0..80 {
26///     let base = 100.0 + f64::from(i);
27///     let candle =
28///         Candle::new(base, base + 2.0, base - 2.0, base + 1.0, 10.0, i64::from(i)).unwrap();
29///     last = indicator.update(candle);
30/// }
31/// assert!(last.is_some());
32/// ```
33#[derive(Debug, Clone, Default)]
34pub struct TrueRange {
35    prev_close: Option<f64>,
36    has_emitted: bool,
37}
38
39impl TrueRange {
40    /// Construct a new True Range indicator.
41    pub const fn new() -> Self {
42        Self {
43            prev_close: None,
44            has_emitted: false,
45        }
46    }
47}
48
49impl Indicator for TrueRange {
50    type Input = Candle;
51    type Output = f64;
52
53    fn update(&mut self, candle: Candle) -> Option<f64> {
54        let tr = candle.true_range(self.prev_close);
55        self.prev_close = Some(candle.close);
56        self.has_emitted = true;
57        Some(tr)
58    }
59
60    fn reset(&mut self) {
61        self.prev_close = None;
62        self.has_emitted = false;
63    }
64
65    fn warmup_period(&self) -> usize {
66        1
67    }
68
69    fn is_ready(&self) -> bool {
70        self.has_emitted
71    }
72
73    fn name(&self) -> &'static str {
74        "TrueRange"
75    }
76}
77
78#[cfg(test)]
79mod tests {
80    use super::*;
81    use crate::traits::BatchExt;
82    use approx::assert_relative_eq;
83
84    fn c(high: f64, low: f64, close: f64, ts: i64) -> Candle {
85        Candle::new(f64::midpoint(high, low), high, low, close, 1.0, ts).unwrap()
86    }
87
88    #[test]
89    fn reference_values() {
90        // Bar 1 has no previous close -> TR = high - low = 12 - 8 = 4.
91        // Bar 2: prev close 11, TR = max(10-9, |10-11|, |9-11|) = max(1, 1, 2) = 2.
92        let mut tr = TrueRange::new();
93        let out = tr.batch(&[c(12.0, 8.0, 11.0, 0), c(10.0, 9.0, 9.5, 1)]);
94        assert_relative_eq!(out[0].unwrap(), 4.0, epsilon = 1e-12);
95        assert_relative_eq!(out[1].unwrap(), 2.0, epsilon = 1e-12);
96    }
97
98    /// Cover the Indicator-impl `name` body (73-75).
99    #[test]
100    fn name_metadata() {
101        let tr = TrueRange::new();
102        assert_eq!(tr.name(), "TrueRange");
103    }
104
105    #[test]
106    fn emits_from_first_candle() {
107        let mut tr = TrueRange::new();
108        assert_eq!(tr.warmup_period(), 1);
109        assert!(!tr.is_ready());
110        assert!(tr.update(c(11.0, 9.0, 10.0, 0)).is_some());
111        assert!(tr.is_ready());
112    }
113
114    #[test]
115    fn never_negative() {
116        let candles: Vec<Candle> = (0..120)
117            .map(|i| {
118                let base = 100.0 + (i as f64 * 0.3).sin() * 5.0;
119                c(base + 1.0, base - 1.0, base, i)
120            })
121            .collect();
122        let mut tr = TrueRange::new();
123        for v in tr.batch(&candles).into_iter().flatten() {
124            assert!(v >= 0.0, "true range must be non-negative, got {v}");
125        }
126    }
127
128    #[test]
129    fn reset_clears_state() {
130        let mut tr = TrueRange::new();
131        tr.batch(&[c(12.0, 8.0, 10.0, 0), c(13.0, 9.0, 11.0, 1)]);
132        assert!(tr.is_ready());
133        tr.reset();
134        assert!(!tr.is_ready());
135        // After reset the next bar again has no previous close.
136        assert_relative_eq!(
137            tr.update(c(12.0, 8.0, 10.0, 0)).unwrap(),
138            4.0,
139            epsilon = 1e-12
140        );
141    }
142
143    #[test]
144    fn batch_equals_streaming() {
145        let candles: Vec<Candle> = (0..60)
146            .map(|i| {
147                let mid = 100.0 + (i as f64 * 0.3).sin() * 8.0;
148                c(mid + 1.5, mid - 1.5, mid + 0.5, i)
149            })
150            .collect();
151        let mut a = TrueRange::new();
152        let mut b = TrueRange::new();
153        assert_eq!(
154            a.batch(&candles),
155            candles.iter().map(|x| b.update(*x)).collect::<Vec<_>>()
156        );
157    }
158}
wickra_core/indicators/true_range.rs

wickra_core/indicators/
true_range.rs
