Skip to main content

ferrochart_core/transform/
mod.rs

1//! Built-in series transforms: Renko, Range
2//! Bars, Kagi and Point & Figure. Their exact rules are in
3//! `docs/book/src/series.md`. Add one to a chart with
4//! [`Chart::add_transform_series`](crate::Chart::add_transform_series).
5
6use crate::error::{Error, Result};
7use crate::frame::SeriesKind;
8use crate::plugin::{TransformBar, TransformOutput};
9
10mod kagi;
11mod point_figure;
12mod range_bars;
13mod renko;
14pub(crate) mod store;
15
16pub use kagi::{Kagi, Reversal};
17pub use point_figure::PointFigure;
18pub use range_bars::RangeBars;
19pub use renko::Renko;
20
21/// `Err(InvalidArgument)` unless `x` is finite and positive.
22fn positive(x: f64, what: &'static str) -> Result<f64> {
23    if x.is_finite() && x > 0.0 {
24        Ok(x)
25    } else {
26        Err(Error::InvalidArgument(what))
27    }
28}
29
30/// `Ok` for the kinds an OHLC-producing transform can be drawn as.
31fn bar_kind(kind: SeriesKind) -> Result<SeriesKind> {
32    match kind {
33        SeriesKind::Candlestick | SeriesKind::OhlcBar => Ok(kind),
34        _ => Err(Error::InvalidArgument(
35            "this transform is drawn as candlesticks or OHLC bars",
36        )),
37    }
38}
39
40/// An element from `open` to `close`.
41fn element(open: f64, close: f64, volume: f64, flag: u8) -> TransformBar {
42    TransformBar {
43        open,
44        high: open.max(close),
45        low: open.min(close),
46        close,
47        volume,
48        flag,
49    }
50}
51
52/// Writes `bar`; `false` if the transform must stop.
53fn emit(out: &mut TransformOutput, bar: TransformBar) -> bool {
54    out.push(bar)
55}
56
57/// Volume of an element opened by an input with volume `v` (0, or NaN when
58/// the input has none).
59fn fresh_volume(v: f64) -> f64 {
60    if v.is_nan() { f64::NAN } else { 0.0 }
61}
62
63#[cfg(test)]
64pub(crate) mod tests {
65    use super::*;
66    use crate::plugin::{InputBar, SeriesTransform};
67
68    /// A tick: all four prices `p`.
69    pub(crate) fn tick(time: i64, p: f64) -> InputBar {
70        InputBar {
71            time,
72            open: p,
73            high: p,
74            low: p,
75            close: p,
76            volume: 1.0,
77        }
78    }
79
80    /// The output of `t` over `bars`: push all but the last, peek the last.
81    pub(crate) fn run(t: &mut dyn SeriesTransform, bars: &[InputBar]) -> Vec<TransformBar> {
82        t.reset();
83        let mut out = TransformOutput::default();
84        let mut all = Vec::new();
85        if let Some((last, rest)) = bars.split_last() {
86            for b in rest {
87                out.clear();
88                t.push(*b, &mut out);
89                all.extend_from_slice(out.as_slice());
90            }
91            out.clear();
92            t.peek(*last, &mut out);
93            all.extend_from_slice(out.as_slice());
94        }
95        all
96    }
97
98    /// `(open, close)` of each element.
99    pub(crate) fn oc(bars: &[TransformBar]) -> Vec<(f64, f64)> {
100        bars.iter().map(|b| (b.open, b.close)).collect()
101    }
102
103    #[test]
104    fn parameters_are_checked() {
105        assert!(Renko::fixed(0.0).is_err());
106        assert!(Renko::fixed(f64::NAN).is_err());
107        assert!(Renko::atr(0).is_err());
108        assert!(RangeBars::new(-1.0).is_err());
109        assert!(Kagi::new(Reversal::Percent(0.0)).is_err());
110        assert!(PointFigure::new(1.0, 0).is_err());
111        assert!(
112            Renko::fixed(1.0)
113                .and_then(|r| r.with_kind(SeriesKind::Kagi))
114                .is_err()
115        );
116    }
117
118    #[test]
119    fn output_stops_at_the_limit() {
120        let mut r = Renko::fixed(1e-9).unwrap();
121        let mut out = TransformOutput::default();
122        r.push(tick(0, 0.0), &mut out);
123        r.peek(tick(1, 1.0), &mut out);
124        assert_eq!(out.as_slice().len(), crate::plugin::MAX_OUTPUT_PER_CALL);
125        assert!(out.check().is_err());
126    }
127}