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}