fin_primitives/signals/indicators/
three_bar_pattern.rs

1//! Three Bar Pattern indicator.
2
3use crate::error::FinError;
4use crate::signals::{BarInput, Signal, SignalValue};
5use rust_decimal::Decimal;
6use std::collections::VecDeque;
7
8/// Three Bar Pattern — detects Three White Soldiers (bullish) and Three Black Crows
9/// (bearish) candlestick patterns.
10///
11/// **Three White Soldiers** (output `+1`):
12/// - Three consecutive bullish bars (`close > open`)
13/// - Each bar closes higher than the previous
14/// - Each bar opens within the prior bar's body
15///
16/// **Three Black Crows** (output `-1`):
17/// - Three consecutive bearish bars (`close < open`)
18/// - Each bar closes lower than the previous
19/// - Each bar opens within the prior bar's body
20///
21/// Outputs `0` if no pattern is detected.
22///
23/// Returns [`SignalValue::Unavailable`] until 3 bars have been seen.
24///
25/// # Example
26/// ```rust
27/// use fin_primitives::signals::indicators::ThreeBarPattern;
28/// use fin_primitives::signals::Signal;
29///
30/// let tbp = ThreeBarPattern::new("tbp").unwrap();
31/// assert_eq!(tbp.period(), 3);
32/// ```
33pub struct ThreeBarPattern {
34    name: String,
35    bars: VecDeque<(Decimal, Decimal)>, // (open, close) pairs
36}
37
38impl ThreeBarPattern {
39    /// # Errors
40    /// Never errors — provided for API consistency.
41    pub fn new(name: impl Into<String>) -> Result<Self, FinError> {
42        Ok(Self { name: name.into(), bars: VecDeque::with_capacity(3) })
43    }
44}
45
46impl Signal for ThreeBarPattern {
47    fn name(&self) -> &str { &self.name }
48    fn period(&self) -> usize { 3 }
49    fn is_ready(&self) -> bool { self.bars.len() >= 3 }
50
51    fn update(&mut self, bar: &BarInput) -> Result<SignalValue, FinError> {
52        self.bars.push_back((bar.open, bar.close));
53        if self.bars.len() > 3 { self.bars.pop_front(); }
54        if self.bars.len() < 3 { return Ok(SignalValue::Unavailable); }
55
56        let (o1, c1) = self.bars[0];
57        let (o2, c2) = self.bars[1];
58        let (o3, c3) = self.bars[2];
59
60        let body1_lo = o1.min(c1);
61        let body1_hi = o1.max(c1);
62        let body2_lo = o2.min(c2);
63        let body2_hi = o2.max(c2);
64
65        // Three White Soldiers
66        let three_white = c1 > o1 && c2 > o2 && c3 > o3  // all bullish
67            && c2 > c1 && c3 > c2                          // each closes higher
68            && o2 >= body1_lo && o2 <= body1_hi            // bar2 opens in bar1's body
69            && o3 >= body2_lo && o3 <= body2_hi;           // bar3 opens in bar2's body
70
71        // Three Black Crows
72        let three_black = c1 < o1 && c2 < o2 && c3 < o3  // all bearish
73            && c2 < c1 && c3 < c2                          // each closes lower
74            && o2 >= body1_lo && o2 <= body1_hi
75            && o3 >= body2_lo && o3 <= body2_hi;
76
77        let signal = if three_white { Decimal::ONE }
78            else if three_black { Decimal::NEGATIVE_ONE }
79            else { Decimal::ZERO };
80        Ok(SignalValue::Scalar(signal))
81    }
82
83    fn reset(&mut self) { self.bars.clear(); }
84}
85
86#[cfg(test)]
87mod tests {
88    use super::*;
89    use crate::ohlcv::OhlcvBar;
90    use crate::signals::Signal;
91    use crate::types::{NanoTimestamp, Price, Quantity, Symbol};
92    use rust_decimal_macros::dec;
93
94    fn bar(o: &str, c: &str) -> OhlcvBar {
95        let op = Price::new(o.parse().unwrap()).unwrap();
96        let cp = Price::new(c.parse().unwrap()).unwrap();
97        let hp = Price::new(cp.value().max(op.value()).to_string().parse().unwrap()).unwrap();
98        let lp = Price::new(cp.value().min(op.value()).to_string().parse().unwrap()).unwrap();
99        OhlcvBar {
100            symbol: Symbol::new("X").unwrap(),
101            open: op, high: hp, low: lp, close: cp,
102            volume: Quantity::zero(),
103            ts_open: NanoTimestamp::new(0),
104            ts_close: NanoTimestamp::new(1),
105            tick_count: 1,
106        }
107    }
108
109    #[test]
110    fn test_tbp_unavailable() {
111        let mut tbp = ThreeBarPattern::new("t").unwrap();
112        for _ in 0..2 {
113            assert_eq!(tbp.update_bar(&bar("100","105")).unwrap(), SignalValue::Unavailable);
114        }
115    }
116
117    #[test]
118    fn test_tbp_three_white_soldiers() {
119        let mut tbp = ThreeBarPattern::new("t").unwrap();
120        // Bar1: 100→108, Bar2: 105→113 (opens in bar1 body 100-108), Bar3: 110→118
121        tbp.update_bar(&bar("100","108")).unwrap();
122        tbp.update_bar(&bar("105","113")).unwrap();
123        let r = tbp.update_bar(&bar("110","118")).unwrap();
124        assert_eq!(r, SignalValue::Scalar(dec!(1)));
125    }
126
127    #[test]
128    fn test_tbp_three_black_crows() {
129        let mut tbp = ThreeBarPattern::new("t").unwrap();
130        // Bar1: 108→100, Bar2: 103→95, Bar3: 98→90
131        tbp.update_bar(&bar("108","100")).unwrap();
132        tbp.update_bar(&bar("103","95")).unwrap();
133        let r = tbp.update_bar(&bar("98","90")).unwrap();
134        assert_eq!(r, SignalValue::Scalar(dec!(-1)));
135    }
136
137    #[test]
138    fn test_tbp_no_pattern() {
139        let mut tbp = ThreeBarPattern::new("t").unwrap();
140        tbp.update_bar(&bar("100","105")).unwrap();
141        tbp.update_bar(&bar("103","108")).unwrap();
142        let r = tbp.update_bar(&bar("106","104")).unwrap(); // last bar bearish → no three whites
143        assert_eq!(r, SignalValue::Scalar(dec!(0)));
144    }
145
146    #[test]
147    fn test_tbp_reset() {
148        let mut tbp = ThreeBarPattern::new("t").unwrap();
149        for _ in 0..3 { tbp.update_bar(&bar("100","105")).unwrap(); }
150        tbp.reset();
151        assert!(!tbp.is_ready());
152    }
153}
fin_primitives/signals/indicators/three_bar_pattern.rs

fin_primitives/signals/indicators/
three_bar_pattern.rs
