Skip to main content

ferrochart_core/
series.rs

1//! Per-series storage and the data operations of `set_data`, `append`,
2//! `prepend` and `update_last` for every built-in series kind.
3//!
4//! The global time index is the union of the times of all series. The
5//! chart extends or rebuilds it **before** an operation runs here, so every
6//! time an operation sees is a slot of the index. Each series is stored
7//! densely over its own span of slots: value series fill the slots they skip
8//! by interpolation or NaN (see [`data::value`](crate::data::value)), OHLC
9//! series with gap bars (all prices NaN). Heikin-Ashi candles are computed
10//! here, in the data layer, from the OHLC data the user sets.
11//!
12
13use crate::data::lod::Lod;
14use crate::data::ohlc::{OhlcStore, check_columns};
15use crate::data::value::{ValueStore, check_values, densify};
16use crate::data::{
17    BarUpdate, ChangeLog, DataChange, OhlcColumns, OhlcLevelView, SeriesMapping, TimeIndex,
18    Timestamp, ValidationMode, ValueColumns,
19};
20use crate::error::{Error, Result};
21use crate::frame::SeriesKind;
22use crate::plugin::CustomStore;
23use crate::transform::store::TransformStore;
24
25/// Data for `set_data` / `append` / `prepend`.
26///
27/// Custom (plugin) series data arrives with the plugin
28/// interface in M5.
29#[derive(Clone, Debug, PartialEq)]
30#[non_exhaustive]
31pub enum SeriesData {
32    /// OHLC(V) bars: `Candlestick`, `OhlcBar`, `HeikinAshi`.
33    Ohlc(OhlcColumns),
34    /// Single values: `Line`, `Area`, `Baseline`, `Histogram`.
35    Value(ValueColumns),
36}
37
38impl From<OhlcColumns> for SeriesData {
39    fn from(c: OhlcColumns) -> Self {
40        Self::Ohlc(c)
41    }
42}
43
44impl From<ValueColumns> for SeriesData {
45    fn from(c: ValueColumns) -> Self {
46        Self::Value(c)
47    }
48}
49
50impl SeriesData {
51    /// The point times.
52    pub(crate) fn times(&self) -> &[Timestamp] {
53        match self {
54            Self::Ohlc(c) => &c.time,
55            Self::Value(c) => &c.time,
56        }
57    }
58
59    /// Takes the time column out (for a series that becomes the whole time
60    /// axis), after checking that it has one time per point.
61    pub(crate) fn take_times(mut self) -> Result<(Vec<Timestamp>, Self)> {
62        let (time, n, column) = match &mut self {
63            Self::Ohlc(c) => (&mut c.time, c.open.len(), "open"),
64            Self::Value(c) => (&mut c.time, c.value.len(), "value"),
65        };
66        if time.len() != n {
67            return Err(Error::LengthMismatch { column });
68        }
69        let times = core::mem::take(time);
70        Ok((times, self))
71    }
72
73    /// One point at `bar.time` (value series take `bar.close`).
74    pub(crate) fn point(kind: SeriesKind, bar: BarUpdate) -> Self {
75        if is_value_kind(kind) {
76            Self::Value(ValueColumns {
77                time: vec![bar.time],
78                value: vec![bar.close],
79                color: None,
80            })
81        } else {
82            Self::Ohlc(OhlcStore::bar_columns(bar, true))
83        }
84    }
85
86    /// `self` followed by `later` (same kind; per-point colors are filled
87    /// with 0 where one side has none).
88    pub(crate) fn concat(self, later: Self) -> Result<Self> {
89        match (self, later) {
90            (Self::Ohlc(mut a), Self::Ohlc(b)) => {
91                if a.volume.is_some() != b.volume.is_some() {
92                    return Err(Error::LengthMismatch { column: "volume" });
93                }
94                a.time.extend_from_slice(&b.time);
95                a.open.extend_from_slice(&b.open);
96                a.high.extend_from_slice(&b.high);
97                a.low.extend_from_slice(&b.low);
98                a.close.extend_from_slice(&b.close);
99                if let (Some(x), Some(y)) = (a.volume.as_mut(), b.volume.as_ref()) {
100                    x.extend_from_slice(y);
101                }
102                Ok(Self::Ohlc(a))
103            }
104            (Self::Value(mut a), Self::Value(b)) => {
105                let (na, nb) = (a.value.len(), b.value.len());
106                a.color = match (a.color.take(), b.color) {
107                    (None, None) => None,
108                    (x, y) => {
109                        let mut c = x.unwrap_or_else(|| vec![0; na]);
110                        c.extend(y.unwrap_or_else(|| vec![0; nb]));
111                        Some(c)
112                    }
113                };
114                a.time.extend_from_slice(&b.time);
115                a.value.extend_from_slice(&b.value);
116                Ok(Self::Value(a))
117            }
118            (Self::Ohlc(_), _) => Err(Error::InvalidArgument("this series needs OHLC data")),
119            (Self::Value(_), _) => Err(Error::InvalidArgument("this series needs value data")),
120        }
121    }
122}
123
124const NOT_ON_AXIS: Error =
125    Error::InvalidArgument("the times must be bars of the chart's time axis");
126const NO_OWN_DATA: Error =
127    Error::InvalidArgument("this series has no data of its own; use its source series");
128
129/// What a series stores.
130#[derive(Debug)]
131// One `Store` per series, never in a hot array: boxing would only add an
132// indirection to every data access.
133#[allow(clippy::large_enum_variant)]
134pub(crate) enum Store {
135    /// No data of its own (volume series read their source).
136    None,
137    Ohlc(OhlcStore),
138    /// The OHLC data as set by the user and the Heikin-Ashi candles drawn.
139    HeikinAshi {
140        raw: OhlcStore,
141        ha: OhlcStore,
142    },
143    Value(ValueStore),
144    /// A plugin that owns its data.
145    Custom(Box<CustomStore>),
146    /// A transform series: its inputs and outputs.
147    Transform(Box<TransformStore>),
148}
149
150/// A series' data as indicators read it.
151#[derive(Clone, Copy)]
152pub(crate) enum Source<'a> {
153    /// Built-in data: no plugin involved, so it can be read from several
154    /// threads (parallel full recomputation).
155    Plain(PlainSource<'a>),
156    /// A custom series: read through its plugin.
157    Custom(&'a Store),
158}
159
160/// Built-in data of a series (`Sync`).
161#[derive(Clone, Copy)]
162pub(crate) enum PlainSource<'a> {
163    None,
164    /// OHLC data: `span` gives the covered indices, `bars` the values (the
165    /// drawn candles: Heikin-Ashi, transform output).
166    Ohlc {
167        span: &'a OhlcStore,
168        bars: &'a OhlcStore,
169    },
170    Value(&'a ValueStore),
171}
172
173impl Source<'_> {
174    /// First logical index and end, `None` without data.
175    pub(crate) fn span(&self) -> Option<(i64, i64)> {
176        match self {
177            Self::Custom(s) => s.span(),
178            Self::Plain(PlainSource::None) => None,
179            Self::Plain(PlainSource::Ohlc { span: s, .. }) => {
180                (s.len() > 0).then(|| (s.first(), s.end()))
181            }
182            Self::Plain(PlainSource::Value(s)) => (s.len() > 0).then(|| (s.first(), s.end())),
183        }
184    }
185
186    /// As [`Store::bar_at`].
187    pub(crate) fn bar_at(&self, j: i64) -> Option<[f64; 4]> {
188        match self {
189            Self::Custom(s) => s.bar_at(j),
190            Self::Plain(PlainSource::None) => None,
191            Self::Plain(PlainSource::Ohlc { bars, .. }) => bars.bar_at(j),
192            Self::Plain(PlainSource::Value(s)) => {
193                s.value_at(j).filter(|v| !v.is_nan()).map(|v| [v; 4])
194            }
195        }
196    }
197
198    /// As [`Store::volume_at`].
199    pub(crate) fn volume_at(&self, j: i64) -> Option<f64> {
200        match self {
201            Self::Plain(PlainSource::Ohlc { bars, .. }) => bars.volume_at(j),
202            Self::Custom(s) => s.volume_at(j),
203            Self::Plain(_) => None,
204        }
205    }
206
207    /// As [`Store::has_volume`].
208    pub(crate) fn has_volume(&self) -> bool {
209        match self {
210            Self::Plain(PlainSource::Ohlc { bars, .. }) => bars.has_volume(),
211            Self::Custom(s) => s.has_volume(),
212            Self::Plain(_) => false,
213        }
214    }
215}
216
217/// Whether a kind takes OHLC data.
218pub(crate) fn is_ohlc_kind(kind: SeriesKind) -> bool {
219    matches!(
220        kind,
221        SeriesKind::Candlestick | SeriesKind::OhlcBar | SeriesKind::HeikinAshi
222    )
223}
224
225/// Whether a kind takes single values.
226pub(crate) fn is_value_kind(kind: SeriesKind) -> bool {
227    matches!(
228        kind,
229        SeriesKind::Line
230            | SeriesKind::Area
231            | SeriesKind::Baseline
232            | SeriesKind::Histogram
233            | SeriesKind::Points
234    )
235}
236
237/// Heikin-Ashi bar from the previous Heikin-Ashi bar and a raw bar.
238fn ha_bar(prev: Option<[f64; 4]>, raw: [f64; 4]) -> [f64; 4] {
239    let [o, h, l, c] = raw;
240    let close = (o + h + l + c) * 0.25;
241    let open = match prev {
242        Some([po, _, _, pc]) => (po + pc) * 0.5,
243        None => (o + c) * 0.5,
244    };
245    [open, h.max(open).max(close), l.min(open).min(close), close]
246}
247
248/// Heikin-Ashi bars of raw logical indices `from..to`, continuing from `prev`
249/// (the last Heikin-Ashi bar before `from`). Gaps stay gaps and do not break
250/// the chain.
251fn ha_columns(raw: &OhlcStore, from: i64, to: i64, mut prev: Option<[f64; 4]>) -> OhlcColumns {
252    let n = usize::try_from(to - from).unwrap_or(0);
253    let mut cols = OhlcColumns {
254        time: Vec::new(),
255        open: Vec::with_capacity(n),
256        high: Vec::with_capacity(n),
257        low: Vec::with_capacity(n),
258        close: Vec::with_capacity(n),
259        volume: raw.has_volume().then(|| Vec::with_capacity(n)),
260    };
261    for j in from..to {
262        let x = match raw.bar_at(j) {
263            Some(bar) => {
264                let x = ha_bar(prev, bar);
265                prev = Some(x);
266                x
267            }
268            None => [f64::NAN; 4],
269        };
270        cols.open.push(x[0]);
271        cols.high.push(x[1]);
272        cols.low.push(x[2]);
273        cols.close.push(x[3]);
274        if let Some(v) = cols.volume.as_mut() {
275            v.push(raw.volume_at(j).unwrap_or(0.0));
276        }
277    }
278    cols
279}
280
281/// The last bar (not a gap) of `s` before logical index `j`.
282fn last_bar_before(s: &OhlcStore, j: i64) -> Option<[f64; 4]> {
283    (s.first()..j.min(s.end())).rev().find_map(|k| s.bar_at(k))
284}
285
286/// Recomputes all Heikin-Ashi candles (O(n)).
287fn rebuild_ha(raw: &OhlcStore, ha: &mut OhlcStore) -> Result<()> {
288    ha.replace_at(
289        raw.first(),
290        ha_columns(raw, raw.first(), raw.end(), None),
291        ValidationMode::Repair,
292    )?;
293    Ok(())
294}
295
296/// Adds the Heikin-Ashi candles of raw bars `from..raw.end()`.
297fn extend_ha(raw: &OhlcStore, ha: &mut OhlcStore, from: i64) -> Result<()> {
298    if ha.len() == 0 || ha.first() != raw.first() || ha.end() != from {
299        return rebuild_ha(raw, ha);
300    }
301    let prev = last_bar_before(ha, from);
302    ha.append(
303        None,
304        ha_columns(raw, from, raw.end(), prev),
305        ValidationMode::Repair,
306    )?;
307    Ok(())
308}
309
310/// OHLC columns with point `i` at slot `lead + offsets[i]` (`lead + i`
311/// without offsets), gap bars between the points, and `lead` gap bars before
312/// and `trail` after them. The time column is dropped.
313fn densify_ohlc(
314    offsets: Option<&[u32]>,
315    cols: &OhlcColumns,
316    lead: usize,
317    trail: usize,
318) -> Result<OhlcColumns> {
319    let span = match offsets {
320        Some(o) => o.last().map_or(0, |&x| x as usize + 1),
321        None => cols.open.len(),
322    };
323    let n = lead + span + trail;
324    let column = |v: f64| -> Result<Vec<f64>> {
325        let mut c = Vec::new();
326        c.try_reserve_exact(n).map_err(|_| Error::OutOfMemory)?;
327        c.resize(n, v);
328        Ok(c)
329    };
330    let mut out = OhlcColumns {
331        time: Vec::new(),
332        open: column(f64::NAN)?,
333        high: column(f64::NAN)?,
334        low: column(f64::NAN)?,
335        close: column(f64::NAN)?,
336        volume: match cols.volume {
337            Some(_) => Some(column(0.0)?),
338            None => None,
339        },
340    };
341    for i in 0..cols.open.len() {
342        let at = lead + offsets.and_then(|o| o.get(i)).map_or(i, |&x| x as usize);
343        out.open[at] = cols.open[i];
344        out.high[at] = cols.high[i];
345        out.low[at] = cols.low[i];
346        out.close[at] = cols.close[i];
347        if let (Some(dst), Some(src)) = (out.volume.as_mut(), cols.volume.as_ref()) {
348            dst[at] = src[i];
349        }
350    }
351    Ok(out)
352}
353
354fn bar_update(time: i64, x: [f64; 4], volume: Option<f64>) -> BarUpdate {
355    BarUpdate {
356        time,
357        open: x[0],
358        high: x[1],
359        low: x[2],
360        close: x[3],
361        volume,
362    }
363}
364
365fn check_value_cols(c: &ValueColumns) -> Result<()> {
366    if c.value.len() != c.time.len() {
367        return Err(Error::LengthMismatch { column: "value" });
368    }
369    if c.color.as_ref().is_some_and(|k| k.len() != c.time.len()) {
370        return Err(Error::LengthMismatch { column: "color" });
371    }
372    check_values(&c.value)
373}
374
375/// `(first, offsets)` of a mapping; `None` offsets for the aligned fast path.
376fn split(m: SeriesMapping) -> (i64, Option<Vec<u32>>) {
377    match m {
378        SeriesMapping::Aligned { first } => (first, None),
379        SeriesMapping::Mapped { first, offsets } => (first, Some(offsets)),
380    }
381}
382
383/// Dense values (and colors) for points at `first + offsets[i]`, with an
384/// optional anchor point at relative slot `anchor.0` that is used for
385/// interpolation and then removed.
386fn dense_with_anchor(
387    offsets: Option<&[u32]>,
388    cols: &ValueColumns,
389    anchor: Option<(i64, f64)>,
390    interpolate: bool,
391) -> Result<(Vec<f64>, Option<Vec<u32>>)> {
392    let n = cols.value.len();
393    let mut offs: Vec<i64> = match offsets {
394        Some(o) => o.iter().map(|&x| i64::from(x)).collect(),
395        None => (0..i64::try_from(n).unwrap_or(0)).collect(),
396    };
397    let mut values = cols.value.clone();
398    let mut colors = cols.color.clone();
399    let before = anchor.is_some_and(|(at, _)| at < 0);
400    if let Some((at, v)) = anchor {
401        if before {
402            offs.insert(0, at);
403            values.insert(0, v);
404            if let Some(c) = colors.as_mut() {
405                c.insert(0, 0);
406            }
407        } else {
408            offs.push(at);
409            values.push(v);
410            if let Some(c) = colors.as_mut() {
411                c.push(0);
412            }
413        }
414    }
415    let base = offs.first().copied().unwrap_or(0);
416    let rel: Vec<u32> = offs
417        .iter()
418        .map(|&o| u32::try_from(o - base).map_err(|_| NOT_ON_AXIS))
419        .collect::<Result<_>>()?;
420    let (mut v, mut c) = densify(&rel, &values, colors.as_deref(), interpolate)?;
421    if anchor.is_some() {
422        if before {
423            v.remove(0);
424            if let Some(c) = c.as_mut() {
425                c.remove(0);
426            }
427        } else {
428            v.pop();
429            if let Some(c) = c.as_mut() {
430                c.pop();
431            }
432        }
433    }
434    Ok((v, c))
435}
436
437impl Store {
438    pub(crate) fn for_kind(kind: SeriesKind) -> Self {
439        match kind {
440            SeriesKind::HeikinAshi => Self::HeikinAshi {
441                raw: OhlcStore::default(),
442                ha: OhlcStore::default(),
443            },
444            k if is_ohlc_kind(k) => Self::Ohlc(OhlcStore::default()),
445            k if is_value_kind(k) => Self::Value(ValueStore::default()),
446            _ => Self::None,
447        }
448    }
449
450    /// The store that is drawn (Heikin-Ashi: the transformed bars).
451    /// The data as indicators read it.
452    pub(crate) fn source(&self) -> Source<'_> {
453        Source::Plain(match self {
454            Self::None => PlainSource::None,
455            Self::Ohlc(s) => PlainSource::Ohlc { span: s, bars: s },
456            Self::HeikinAshi { raw, ha } => PlainSource::Ohlc {
457                span: raw,
458                bars: ha,
459            },
460            Self::Transform(t) => PlainSource::Ohlc {
461                span: &t.out,
462                bars: &t.out,
463            },
464            Self::Value(s) => PlainSource::Value(s),
465            Self::Custom(_) => return Source::Custom(self),
466        })
467    }
468
469    fn drawn(&self) -> Option<&OhlcStore> {
470        match self {
471            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => Some(s),
472            Self::Transform(t) => Some(&t.out),
473            _ => None,
474        }
475    }
476
477    /// The transform series' data.
478    pub(crate) fn transform(&self) -> Option<&TransformStore> {
479        match self {
480            Self::Transform(t) => Some(t),
481            _ => None,
482        }
483    }
484
485    pub(crate) fn len(&self) -> usize {
486        match self {
487            Self::None => 0,
488            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => s.len(),
489            Self::Value(s) => s.len(),
490            Self::Custom(c) => c.len(),
491            Self::Transform(t) => t.out.len(),
492        }
493    }
494
495    pub(crate) fn is_empty(&self) -> bool {
496        self.len() == 0
497    }
498
499    /// Logical indices `first..end` the series covers (gaps included).
500    pub(crate) fn span(&self) -> Option<(i64, i64)> {
501        match self {
502            Self::None => None,
503            Self::Ohlc(s) | Self::HeikinAshi { raw: s, .. } => {
504                (s.len() > 0).then(|| (s.first(), s.end()))
505            }
506            Self::Transform(t) => (t.out.len() > 0).then(|| (t.out.first(), t.out.end())),
507            Self::Value(s) => (s.len() > 0).then(|| (s.first(), s.end())),
508            Self::Custom(c) => c.span(),
509        }
510    }
511
512    /// Whether the series takes data (volume series read their source).
513    pub(crate) fn takes_data(&self) -> bool {
514        matches!(
515            self,
516            Self::Ohlc(_) | Self::HeikinAshi { .. } | Self::Value(_) | Self::Transform(_)
517        )
518    }
519
520    /// The plugin of a custom series.
521    pub(crate) fn custom(&self) -> Option<&CustomStore> {
522        match self {
523            Self::Custom(c) => Some(c),
524            _ => None,
525        }
526    }
527
528    pub(crate) fn log(&self) -> Option<&ChangeLog> {
529        match self {
530            Self::None => None,
531            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => Some(s.log()),
532            Self::Value(s) => Some(s.log()),
533            Self::Custom(c) => Some(&c.log),
534            Self::Transform(t) => Some(t.out.log()),
535        }
536    }
537
538    pub(crate) fn lod(&self) -> Option<&Lod> {
539        match self {
540            Self::None | Self::Custom(_) => None,
541            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => Some(s.lod()),
542            Self::Transform(t) => Some(t.out.lod()),
543            Self::Value(s) => Some(s.lod()),
544        }
545    }
546
547    pub(crate) fn has_volume(&self) -> bool {
548        self.drawn().is_some_and(OhlcStore::has_volume)
549    }
550
551    pub(crate) fn level_view(&self, level: u8) -> Option<OhlcLevelView<'_>> {
552        match self {
553            Self::None | Self::Custom(_) => None,
554            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => s.level_view(level),
555            Self::Transform(t) => t.out.level_view(level),
556            Self::Value(s) => s.level_view(level),
557        }
558    }
559
560    /// Level-0 per-point colors and the logical index of the first one.
561    pub(crate) fn colors(&self) -> Option<(i64, &[u32])> {
562        match self {
563            Self::Value(s) => s.colors().map(|c| (s.first(), c)),
564            _ => None,
565        }
566    }
567
568    /// `[open, high, low, close]` at logical index `j` (value series: the
569    /// value four times); `None` for gaps.
570    pub(crate) fn bar_at(&self, j: i64) -> Option<[f64; 4]> {
571        match self {
572            Self::None => None,
573            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => s.bar_at(j),
574            Self::Transform(t) => t.out.bar_at(j),
575            Self::Value(s) => s.value_at(j).filter(|v| !v.is_nan()).map(|v| [v; 4]),
576            Self::Custom(c) => c.value_at(j).map(|v| [v; 4]),
577        }
578    }
579
580    pub(crate) fn volume_at(&self, j: i64) -> Option<f64> {
581        self.drawn()?.volume_at(j)
582    }
583
584    /// Minimum and maximum over logical indices `from..to`.
585    pub(crate) fn extremes(&mut self, from: i64, to: i64) -> Option<(f64, f64)> {
586        match self {
587            // Custom series need the time index (`CustomStore::extremes`).
588            Self::None | Self::Custom(_) => None,
589            Self::Ohlc(s) | Self::HeikinAshi { ha: s, .. } => s.extremes(from, to),
590            Self::Transform(t) => t.out.extremes(from, to),
591            Self::Value(s) => s.extremes(from, to),
592        }
593    }
594
595    pub(crate) fn heap_bytes(&self) -> usize {
596        match self {
597            Self::None => 0,
598            Self::Ohlc(s) => s.heap_bytes(),
599            Self::HeikinAshi { raw, ha } => raw.heap_bytes() + ha.heap_bytes(),
600            Self::Value(s) => s.heap_bytes(),
601            Self::Custom(c) => c.heap_bytes(),
602            Self::Transform(t) => t.heap_bytes(),
603        }
604    }
605
606    /// The series' data with times taken from `index`, to re-map it after the
607    /// index was rebuilt. Gaps are left out.
608    pub(crate) fn snapshot(&self, index: &TimeIndex) -> Option<SeriesData> {
609        match self {
610            // Custom series are re-mapped from their own times; a transform
611            // series is never next to another series with data.
612            Self::None | Self::Custom(_) | Self::Transform(_) => None,
613            Self::Ohlc(s) | Self::HeikinAshi { raw: s, .. } => {
614                let mut cols = OhlcColumns {
615                    volume: s.has_volume().then(Vec::new),
616                    ..OhlcColumns::default()
617                };
618                for j in s.first()..s.end() {
619                    let (Some(t), Some(b)) = (index.time_at(j), s.bar_at(j)) else {
620                        continue;
621                    };
622                    cols.time.push(t);
623                    cols.open.push(b[0]);
624                    cols.high.push(b[1]);
625                    cols.low.push(b[2]);
626                    cols.close.push(b[3]);
627                    if let Some(v) = cols.volume.as_mut() {
628                        v.push(s.volume_at(j).unwrap_or(0.0));
629                    }
630                }
631                Some(SeriesData::Ohlc(cols))
632            }
633            Self::Value(s) => {
634                let mut cols = ValueColumns {
635                    color: s.colors().map(|_| Vec::new()),
636                    ..ValueColumns::default()
637                };
638                for j in s.first()..s.end() {
639                    let (Some(t), Some(v)) = (index.time_at(j), s.value_at(j)) else {
640                        continue;
641                    };
642                    if v.is_nan() {
643                        continue;
644                    }
645                    cols.time.push(t);
646                    cols.value.push(v);
647                    if let (Some(c), Some(src)) = (cols.color.as_mut(), s.colors()) {
648                        let p = usize::try_from(j - s.first()).unwrap_or(0);
649                        c.push(src.get(p).copied().unwrap_or(0));
650                    }
651                }
652                Some(SeriesData::Value(cols))
653            }
654        }
655    }
656}
657
658/// A data operation on one series. Every time it is given must already be
659/// a slot of `index` (the chart extends the index first).
660pub(crate) struct Op<'a> {
661    pub kind: SeriesKind,
662    pub index: &'a TimeIndex,
663    pub mode: ValidationMode,
664}
665
666impl Op<'_> {
667    fn ohlc(data: SeriesData) -> Result<OhlcColumns> {
668        match data {
669            SeriesData::Ohlc(c) => Ok(c),
670            SeriesData::Value(_) => Err(Error::InvalidArgument("this series needs OHLC data")),
671        }
672    }
673
674    fn value(data: SeriesData) -> Result<ValueColumns> {
675        match data {
676            SeriesData::Value(c) => Ok(c),
677            SeriesData::Ohlc(_) => Err(Error::InvalidArgument("this series needs value data")),
678        }
679    }
680
681    fn interpolate(&self) -> bool {
682        // Bars and dots stand alone: a gap has none.
683        !matches!(self.kind, SeriesKind::Histogram | SeriesKind::Points)
684    }
685
686    fn map(&self, times: &[Timestamp]) -> Result<SeriesMapping> {
687        self.index.map_series(times)?.ok_or(NOT_ON_AXIS)
688    }
689
690    fn check_times(cols: &OhlcColumns) -> Result<()> {
691        if cols.time.len() == cols.open.len() {
692            Ok(())
693        } else {
694            Err(Error::LengthMismatch { column: "open" })
695        }
696    }
697
698    /// `set_data`. Returns the number of repaired bars.
699    pub(crate) fn set(&self, store: &mut Store, data: SeriesData) -> Result<usize> {
700        match store {
701            // The chart runs transform series' operations itself.
702            Store::None | Store::Custom(_) | Store::Transform(_) => Err(NO_OWN_DATA),
703            Store::Ohlc(s) => self.set_ohlc(s, Self::ohlc(data)?),
704            Store::HeikinAshi { raw, ha } => {
705                let repaired = self.set_ohlc(raw, Self::ohlc(data)?)?;
706                rebuild_ha(raw, ha)?;
707                Ok(repaired)
708            }
709            Store::Value(s) => {
710                let cols = Self::value(data)?;
711                check_value_cols(&cols)?;
712                let (first, offsets) = split(self.map(&cols.time)?);
713                match offsets {
714                    None => s.replace(first, cols.value, cols.color)?,
715                    Some(o) => {
716                        let (v, c) =
717                            densify(&o, &cols.value, cols.color.as_deref(), self.interpolate())?;
718                        s.replace(first, v, c)?;
719                    }
720                }
721                Ok(0)
722            }
723        }
724    }
725
726    /// `set_data` of data whose point `p` is logical index `first + p` (the
727    /// time column is ignored). Returns the number of repaired bars.
728    pub(crate) fn set_aligned(
729        &self,
730        store: &mut Store,
731        first: i64,
732        data: SeriesData,
733    ) -> Result<usize> {
734        match store {
735            // The chart runs transform series' operations itself.
736            Store::None | Store::Custom(_) | Store::Transform(_) => Err(NO_OWN_DATA),
737            Store::Ohlc(s) => s.replace_at(first, Self::ohlc(data)?, self.mode),
738            Store::HeikinAshi { raw, ha } => {
739                let repaired = raw.replace_at(first, Self::ohlc(data)?, self.mode)?;
740                rebuild_ha(raw, ha)?;
741                Ok(repaired)
742            }
743            Store::Value(s) => {
744                let cols = Self::value(data)?;
745                s.replace(first, cols.value, cols.color)?;
746                Ok(0)
747            }
748        }
749    }
750
751    fn set_ohlc(&self, s: &mut OhlcStore, mut cols: OhlcColumns) -> Result<usize> {
752        Self::check_times(&cols)?;
753        match self.map(&cols.time)? {
754            SeriesMapping::Aligned { first } => s.replace_at(first, cols, self.mode),
755            SeriesMapping::Mapped { first, offsets } => {
756                let repaired = check_columns(&mut cols, self.mode)?;
757                s.replace_at(first, densify_ohlc(Some(&offsets), &cols, 0, 0)?, self.mode)?;
758                Ok(repaired)
759            }
760        }
761    }
762
763    /// `append`. Returns the number of repaired bars.
764    pub(crate) fn append(&self, store: &mut Store, data: SeriesData) -> Result<usize> {
765        if store.is_empty() {
766            return self.set(store, data);
767        }
768        match store {
769            // The chart runs transform series' operations itself.
770            Store::None | Store::Custom(_) | Store::Transform(_) => Err(NO_OWN_DATA),
771            Store::Ohlc(s) => self.append_ohlc(s, Self::ohlc(data)?),
772            Store::HeikinAshi { raw, ha } => {
773                let old_end = raw.end();
774                let repaired = self.append_ohlc(raw, Self::ohlc(data)?)?;
775                extend_ha(raw, ha, old_end)?;
776                Ok(repaired)
777            }
778            Store::Value(s) => {
779                let cols = Self::value(data)?;
780                check_value_cols(&cols)?;
781                let (first, offsets) = split(self.map(&cols.time)?);
782                if first < s.end() {
783                    return Err(Error::TimeNotIncreasing { index: 0 });
784                }
785                if offsets.is_none() && first == s.end() {
786                    s.append(&cols.value, cols.color.as_deref())?;
787                    return Ok(0);
788                }
789                // Anchor on the last stored point so the gap is filled.
790                let anchor = s.value_at(s.end() - 1).map(|v| (s.end() - 1 - first, v));
791                let (v, c) =
792                    dense_with_anchor(offsets.as_deref(), &cols, anchor, self.interpolate())?;
793                s.append(&v, c.as_deref())?;
794                Ok(0)
795            }
796        }
797    }
798
799    fn append_ohlc(&self, s: &mut OhlcStore, mut cols: OhlcColumns) -> Result<usize> {
800        Self::check_times(&cols)?;
801        if cols.open.is_empty() {
802            return Ok(0);
803        }
804        let (first, offsets) = split(self.map(&cols.time)?);
805        if first < s.end() {
806            return Err(Error::TimeNotIncreasing { index: 0 });
807        }
808        let lead = usize::try_from(first - s.end()).map_err(|_| NOT_ON_AXIS)?;
809        if offsets.is_none() && lead == 0 {
810            return s.append(None, cols, self.mode);
811        }
812        let repaired = check_columns(&mut cols, self.mode)?;
813        s.append(
814            None,
815            densify_ohlc(offsets.as_deref(), &cols, lead, 0)?,
816            self.mode,
817        )?;
818        Ok(repaired)
819    }
820
821    /// `prepend`. Returns the number of repaired bars.
822    pub(crate) fn prepend(&self, store: &mut Store, data: SeriesData) -> Result<usize> {
823        if store.is_empty() {
824            return self.set(store, data);
825        }
826        match store {
827            // The chart runs transform series' operations itself.
828            Store::None | Store::Custom(_) | Store::Transform(_) => Err(NO_OWN_DATA),
829            Store::Ohlc(s) => self.prepend_ohlc(s, Self::ohlc(data)?),
830            Store::HeikinAshi { raw, ha } => {
831                let repaired = self.prepend_ohlc(raw, Self::ohlc(data)?)?;
832                // Every later candle depends on the history: recompute (O(n)).
833                rebuild_ha(raw, ha)?;
834                Ok(repaired)
835            }
836            Store::Value(s) => {
837                let cols = Self::value(data)?;
838                check_value_cols(&cols)?;
839                if cols.value.is_empty() {
840                    return Ok(0);
841                }
842                let (first, offsets) = split(self.map(&cols.time)?);
843                let last_off = offsets
844                    .as_ref()
845                    .and_then(|o| o.last().map(|&x| i64::from(x)))
846                    .unwrap_or_else(|| i64::try_from(cols.value.len()).unwrap_or(0) - 1);
847                if first + last_off >= s.first() {
848                    return Err(Error::TimeNotIncreasing {
849                        index: cols.value.len().saturating_sub(1),
850                    });
851                }
852                if offsets.is_none() && first + last_off + 1 == s.first() {
853                    s.prepend(&cols.value, cols.color.as_deref())?;
854                    return Ok(0);
855                }
856                let anchor = s.value_at(s.first()).map(|v| (s.first() - first, v));
857                let (v, c) =
858                    dense_with_anchor(offsets.as_deref(), &cols, anchor, self.interpolate())?;
859                s.prepend(&v, c.as_deref())?;
860                Ok(0)
861            }
862        }
863    }
864
865    fn prepend_ohlc(&self, s: &mut OhlcStore, mut cols: OhlcColumns) -> Result<usize> {
866        Self::check_times(&cols)?;
867        let n = cols.open.len();
868        if n == 0 {
869            return Ok(0);
870        }
871        let (first, offsets) = split(self.map(&cols.time)?);
872        let span = offsets
873            .as_ref()
874            .and_then(|o| o.last())
875            .map_or(n, |&x| x as usize + 1);
876        let end = first.saturating_add(i64::try_from(span).unwrap_or(i64::MAX));
877        if end > s.first() {
878            return Err(Error::TimeNotIncreasing { index: n - 1 });
879        }
880        let trail = usize::try_from(s.first() - end).map_err(|_| NOT_ON_AXIS)?;
881        if offsets.is_none() && trail == 0 {
882            return s.prepend(None, cols, self.mode);
883        }
884        let repaired = check_columns(&mut cols, self.mode)?;
885        s.prepend(
886            None,
887            densify_ohlc(offsets.as_deref(), &cols, 0, trail)?,
888            self.mode,
889        )?;
890        Ok(repaired)
891    }
892
893    /// `update_last`: replaces the last point if `bar.time` is its time (no
894    /// allocation), appends otherwise (with gaps up to it if needed). Value
895    /// series use `bar.close`.
896    pub(crate) fn update_last(
897        &self,
898        store: &mut Store,
899        bar: BarUpdate,
900    ) -> Result<(DataChange, usize)> {
901        let j = self.index.index_of(bar.time).ok_or(NOT_ON_AXIS)?;
902        match store {
903            // The chart runs transform series' operations itself.
904            Store::None | Store::Custom(_) | Store::Transform(_) => Err(NO_OWN_DATA),
905            Store::Ohlc(s) => self.update_ohlc(s, j, bar),
906            Store::HeikinAshi { raw, ha } => {
907                let old_end = raw.end();
908                let (change, repaired) = self.update_ohlc(raw, j, bar)?;
909                let in_place = change == DataChange::UpdateLast
910                    && ha.len() > 0
911                    && ha.first() == raw.first()
912                    && ha.end() == raw.end();
913                if in_place {
914                    let h = match raw.bar_at(j) {
915                        Some(x) => ha_bar(last_bar_before(ha, j), x),
916                        None => [f64::NAN; 4],
917                    };
918                    ha.set_last(
919                        bar_update(bar.time, h, raw.volume_at(j)),
920                        ValidationMode::Repair,
921                    )?;
922                } else if change == DataChange::UpdateLast {
923                    rebuild_ha(raw, ha)?;
924                } else {
925                    extend_ha(raw, ha, old_end)?;
926                }
927                Ok((change, repaired))
928            }
929            Store::Value(s) => {
930                let v = bar.close;
931                check_values(&[v])?;
932                if s.len() > 0 {
933                    let last = s.end() - 1;
934                    if j == last {
935                        s.set_last(v, None)?;
936                        return Ok((DataChange::UpdateLast, 0));
937                    }
938                    if j < last {
939                        return Err(Error::TimeNotIncreasing { index: 0 });
940                    }
941                }
942                let old_end = s.end();
943                let fresh = s.len() == 0;
944                self.append(store, SeriesData::point(self.kind, bar))?;
945                let count = if fresh { 1 } else { appended(old_end, store) };
946                Ok((DataChange::Append { count }, 0))
947            }
948        }
949    }
950
951    fn update_ohlc(
952        &self,
953        s: &mut OhlcStore,
954        j: i64,
955        bar: BarUpdate,
956    ) -> Result<(DataChange, usize)> {
957        if s.len() > 0 {
958            if j == s.end() - 1 {
959                return Ok((DataChange::UpdateLast, s.set_last(bar, self.mode)?));
960            }
961            if j < s.end() - 1 {
962                return Err(Error::TimeNotIncreasing { index: 0 });
963            }
964            let old_end = s.end();
965            let repaired = self.append_ohlc(s, OhlcStore::bar_columns(bar, true))?;
966            let count = usize::try_from(s.end() - old_end).unwrap_or(1);
967            return Ok((DataChange::Append { count }, repaired));
968        }
969        let repaired = s.replace_at(j, OhlcStore::bar_columns(bar, false), self.mode)?;
970        Ok((DataChange::Append { count: 1 }, repaired))
971    }
972}
973
974/// Number of points added after `old_end`.
975fn appended(old_end: i64, store: &Store) -> usize {
976    store
977        .span()
978        .and_then(|(_, end)| usize::try_from(end - old_end).ok())
979        .unwrap_or(1)
980}
981
982#[cfg(test)]
983#[allow(clippy::float_cmp)] // exact values are the point of these tests
984mod tests {
985    use super::*;
986    use proptest::prelude::*;
987
988    fn bars(times: &[i64], closes: &[f64]) -> OhlcColumns {
989        OhlcColumns {
990            time: times.to_vec(),
991            open: closes.to_vec(),
992            high: closes.iter().map(|c| c + 1.0).collect(),
993            low: closes.iter().map(|c| c - 1.0).collect(),
994            close: closes.to_vec(),
995            volume: None,
996        }
997    }
998
999    fn op(kind: SeriesKind, index: &TimeIndex) -> Op<'_> {
1000        Op {
1001            kind,
1002            index,
1003            mode: ValidationMode::Reject,
1004        }
1005    }
1006
1007    fn axis(times: &[i64]) -> TimeIndex {
1008        TimeIndex::from_times(times.to_vec()).unwrap()
1009    }
1010
1011    fn v(time: &[i64], value: &[f64]) -> SeriesData {
1012        SeriesData::Value(ValueColumns {
1013            time: time.to_vec(),
1014            value: value.to_vec(),
1015            color: None,
1016        })
1017    }
1018
1019    #[test]
1020    fn sparse_line_is_densified_and_extended() {
1021        let index = axis(&[10, 20, 30, 40, 50]);
1022        let mut line = Store::for_kind(SeriesKind::Line);
1023        let o = op(SeriesKind::Line, &index);
1024        o.set(&mut line, v(&[10, 30], &[1.0, 3.0])).unwrap();
1025        assert_eq!(line.bar_at(1), Some([2.0; 4])); // interpolated
1026        o.append(&mut line, v(&[50], &[7.0])).unwrap();
1027        assert_eq!(line.bar_at(3), Some([5.0; 4]));
1028        assert_eq!(line.len(), 5);
1029        assert!(o.set(&mut line, v(&[15], &[1.0])).is_err()); // not on the axis
1030        // Histograms leave gaps instead.
1031        let mut hist = Store::for_kind(SeriesKind::Histogram);
1032        op(SeriesKind::Histogram, &index)
1033            .set(&mut hist, v(&[10, 30], &[1.0, 3.0]))
1034            .unwrap();
1035        assert_eq!(hist.bar_at(1), None);
1036        assert_eq!(hist.span(), Some((0, 3)));
1037    }
1038
1039    #[test]
1040    fn sparse_ohlc_gets_gap_bars() {
1041        let index = axis(&[1, 2, 3, 4, 5, 6]);
1042        let mut s = Store::for_kind(SeriesKind::OhlcBar);
1043        let o = op(SeriesKind::OhlcBar, &index);
1044        o.set(&mut s, SeriesData::Ohlc(bars(&[1, 3], &[1.0, 3.0])))
1045            .unwrap();
1046        assert_eq!(s.span(), Some((0, 3)));
1047        assert_eq!(s.bar_at(1), None);
1048        assert_eq!(s.bar_at(2), Some([3.0, 4.0, 2.0, 3.0]));
1049        let bar = BarUpdate {
1050            time: 5,
1051            open: 5.0,
1052            high: 6.0,
1053            low: 4.0,
1054            close: 5.5,
1055            volume: None,
1056        };
1057        // Two slots later: one gap bar, then the bar.
1058        assert_eq!(
1059            o.update_last(&mut s, bar).unwrap().0,
1060            DataChange::Append { count: 2 }
1061        );
1062        assert_eq!(
1063            o.update_last(&mut s, bar).unwrap().0,
1064            DataChange::UpdateLast
1065        );
1066        assert_eq!(s.bar_at(3), None);
1067        assert_eq!(s.bar_at(4), Some([5.0, 6.0, 4.0, 5.5]));
1068        o.prepend(&mut s, SeriesData::Ohlc(bars(&[1], &[0.5])))
1069            .unwrap_err(); // slot 1 is taken already
1070        // Snapshots leave the gaps out.
1071        let Some(SeriesData::Ohlc(snap)) = s.snapshot(&index) else {
1072            panic!("no snapshot");
1073        };
1074        assert_eq!(snap.time, [1, 3, 5]);
1075        // Partial NaN bars are invalid; all-NaN bars are gaps.
1076        let mut bad = bars(&[6], &[1.0]);
1077        bad.open[0] = f64::NAN;
1078        assert!(o.append(&mut s, SeriesData::Ohlc(bad)).is_err());
1079        assert!(
1080            o.append(&mut s, SeriesData::Ohlc(bars(&[6], &[f64::NAN])))
1081                .is_ok()
1082        );
1083        assert_eq!(s.bar_at(5), None);
1084    }
1085
1086    #[test]
1087    fn heikin_ashi_follows_the_formula() {
1088        let index = axis(&[1, 2, 3]);
1089        let mut s = Store::for_kind(SeriesKind::HeikinAshi);
1090        let raw = OhlcColumns {
1091            time: vec![1, 3],
1092            open: vec![10.0, 12.0],
1093            high: vec![14.0, 15.0],
1094            low: vec![9.0, 11.0],
1095            close: vec![12.0, 13.0],
1096            volume: None,
1097        };
1098        op(SeriesKind::HeikinAshi, &index)
1099            .set(&mut s, SeriesData::Ohlc(raw))
1100            .unwrap();
1101        // First: open = (10 + 12) / 2, close = (10 + 14 + 9 + 12) / 4.
1102        assert_eq!(s.bar_at(0), Some([11.0, 14.0, 9.0, 11.25]));
1103        // The gap is skipped: open = (11 + 11.25) / 2.
1104        assert_eq!(s.bar_at(1), None);
1105        assert_eq!(s.bar_at(2), Some([11.125, 15.0, 11.0, 12.75]));
1106    }
1107
1108    proptest! {
1109        /// Heikin-Ashi after incremental updates equals Heikin-Ashi of all bars.
1110        #[test]
1111        fn heikin_ashi_incremental_equals_full(
1112            closes in proptest::collection::vec(1.0f64..100.0, 2..60),
1113            ticks in proptest::collection::vec((0i64..3, 1.0f64..100.0), 1..30),
1114        ) {
1115            let times: Vec<i64> = (0..closes.len() as i64).collect();
1116            // Every time a tick can reach (steps of up to 2 leave gaps).
1117            let index = axis(&(0..=closes.len() as i64 + 2 * 30).collect::<Vec<_>>());
1118            let mut s = Store::for_kind(SeriesKind::HeikinAshi);
1119            let o = op(SeriesKind::HeikinAshi, &index);
1120            o.set(&mut s, SeriesData::Ohlc(bars(&times, &closes))).unwrap();
1121            let mut all = bars(&times, &closes);
1122            for (step, c) in ticks {
1123                let t = *all.time.last().unwrap() + step;
1124                let bar = BarUpdate { time: t, open: c, high: c + 1.0, low: c - 1.0, close: c, volume: None };
1125                o.update_last(&mut s, bar).unwrap();
1126                if step > 0 {
1127                    all.time.push(t); all.open.push(c); all.high.push(c + 1.0);
1128                    all.low.push(c - 1.0); all.close.push(c);
1129                } else {
1130                    let p = all.time.len() - 1;
1131                    all.open[p] = c; all.high[p] = c + 1.0; all.low[p] = c - 1.0; all.close[p] = c;
1132                }
1133            }
1134            let mut full = Store::for_kind(SeriesKind::HeikinAshi);
1135            o.set(&mut full, SeriesData::Ohlc(all.clone())).unwrap();
1136            prop_assert_eq!(s.span(), full.span());
1137            for j in 0..index.len() as i64 {
1138                prop_assert_eq!(s.bar_at(j), full.bar_at(j));
1139            }
1140        }
1141    }
1142}