Skip to main content

ferrochart_core/data/
mod.rs

1//! Core data model: basic types, columnar (`SoA`) input formats and column storage.
2//!
3
4mod change_log;
5mod deq_column;
6pub(crate) mod lod;
7pub(crate) mod ohlc;
8mod time_index;
9pub(crate) mod value;
10
11pub use change_log::{ChangeLog, DataDelta};
12pub use deq_column::DeqColumn;
13pub use lod::{ANCHOR, MIN_LOD_LEVEL};
14pub use ohlc::{BarUpdate, Column, DataChange, OhlcLevelView, ValidationMode};
15pub use time_index::{SeriesMapping, TimeIndex};
16
17/// UTC timestamp in milliseconds. The engine does not handle time zones internally;
18/// time zones only affect label formatting.
19pub type Timestamp = i64;
20
21/// Logical index: position on the global time index. May be negative or beyond the
22/// data (empty space). Fractional values address positions between bars.
23pub type LogicalIndex = f64;
24
25/// Identifier of a series in a chart.
26#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
27pub struct SeriesId(pub u32);
28
29/// Identifier of an indicator in a chart.
30#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
31pub struct IndicatorId(pub u32);
32
33/// Identifier of a price line in a chart.
34#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
35pub struct PriceLineId(pub u32);
36
37/// Identifier of a band (fill between two series) in a chart.
38#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
39pub struct BandId(pub u32);
40
41/// Identifier of a layer plugin in a chart.
42#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
43pub struct LayerPluginId(pub u32);
44
45/// Identifier of a pane in a chart.
46#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
47pub struct PaneId(pub u32);
48
49/// Identifier of a drawing.
50#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)]
51pub struct DrawingId(pub u64);
52
53/// Single-value series in columnar layout (line, area, histogram).
54#[derive(Clone, Debug, Default, PartialEq)]
55pub struct ValueColumns {
56    /// Point times (UTC milliseconds), strictly increasing.
57    pub time: Vec<Timestamp>,
58    /// Values; NaN means a gap (no line is drawn through it).
59    pub value: Vec<f64>,
60    /// Optional per-point color as `0xRRGGBBAA`; `0` (transparent) uses the
61    /// series color. Only histogram series draw these, and only at full
62    /// detail (LOD level 0); other kinds keep them but use the series color.
63    pub color: Option<Vec<u32>>,
64}
65
66/// Half-open span of logical indices, `start..end`.
67///
68/// Used instead of `Range<i64>` because `Range` is not `Copy`, and everything that
69/// ends up in a `Frame` must be.
70///
71/// # Examples
72///
73/// ```
74/// use ferrochart_core::data::IdxSpan;
75///
76/// let span = IdxSpan { start: -2, end: 3 };
77/// assert_eq!(span.len(), 5);
78/// assert!(!span.is_empty());
79/// assert!(IdxSpan { start: 4, end: 4 }.is_empty());
80/// ```
81#[derive(Clone, Copy, PartialEq, Eq, Debug, Default, Hash)]
82pub struct IdxSpan {
83    /// First logical index in the span.
84    pub start: i64,
85    /// One past the last logical index in the span.
86    pub end: i64,
87}
88
89impl IdxSpan {
90    /// Whether the span contains no index (`end <= start`).
91    pub fn is_empty(self) -> bool {
92        self.end <= self.start
93    }
94
95    /// Number of indices in the span; 0 if empty.
96    pub fn len(self) -> u64 {
97        self.end.abs_diff(self.start) * u64::from(self.end > self.start)
98    }
99
100    /// Whether `self` and `other` overlap or are directly adjacent.
101    pub(crate) fn touches(self, other: Self) -> bool {
102        other.start <= self.end && self.start <= other.end
103    }
104
105    /// Smallest span containing both.
106    pub(crate) fn hull(self, other: Self) -> Self {
107        Self {
108            start: self.start.min(other.start),
109            end: self.end.max(other.end),
110        }
111    }
112}
113
114/// OHLC(V) series in columnar layout — the input format of `set_data` and friends.
115///
116/// Constraints (validated at the API boundary): `time` is strictly increasing,
117/// all columns have the same length, and `low <= min(open, close)`,
118/// `high >= max(open, close)` for every bar.
119#[derive(Clone, Debug, Default, PartialEq)]
120pub struct OhlcColumns {
121    /// Bar open times (UTC milliseconds), strictly increasing.
122    pub time: Vec<Timestamp>,
123    /// Open prices.
124    pub open: Vec<f64>,
125    /// High prices.
126    pub high: Vec<f64>,
127    /// Low prices.
128    pub low: Vec<f64>,
129    /// Close prices.
130    pub close: Vec<f64>,
131    /// Optional volumes.
132    pub volume: Option<Vec<f64>>,
133}
134
135impl OhlcColumns {
136    /// Number of bars (length of the `time` column).
137    pub fn len(&self) -> usize {
138        self.time.len()
139    }
140
141    /// Whether there are no bars.
142    pub fn is_empty(&self) -> bool {
143        self.time.is_empty()
144    }
145}