wickra_core/cross_section.rs
1//! Cross-section value type: a market-breadth snapshot across a whole universe.
2//!
3//! A [`CrossSection`] is a single tick that carries the per-symbol state of
4//! *every* symbol in a universe at one point in time. It is the non-OHLCV input
5//! consumed by the market-breadth indicator family (advance/decline, `McClellan`,
6//! the TRIN / Arms index, the high-low index, ...), each of which aggregates the
7//! whole cross-section into a single breadth reading. This is the same
8//! one-rich-type-per-family pattern as [`DerivativesTick`] and [`OrderBook`].
9//!
10//! Each [`Member`] precomputes the per-symbol signals the breadth indicators
11//! need — a signed price `change` (whose sign classifies the symbol as
12//! advancing, declining or unchanged), the period `volume`, and the
13//! `new_high` / `new_low` extreme flags — so the indicators stay stateless per
14//! tick and never have to track per-symbol history.
15//!
16//! [`DerivativesTick`]: crate::DerivativesTick
17//! [`OrderBook`]: crate::OrderBook
18
19use crate::error::{Error, Result};
20
21/// One symbol's contribution to a [`CrossSection`] tick.
22///
23/// Field invariants enforced by [`CrossSection::new`] when the member is placed
24/// into a tick:
25///
26/// - `change` is finite (its sign classifies the symbol — positive is
27/// advancing, negative is declining, zero is unchanged).
28/// - `volume` is finite and non-negative.
29///
30/// `new_high` / `new_low` are caller-supplied flags marking whether the symbol
31/// printed a new period extreme; they carry no numeric invariant.
32#[non_exhaustive]
33#[derive(Debug, Clone, Copy, PartialEq)]
34pub struct Member {
35 /// Price change versus the previous close. Sign classifies the symbol:
36 /// positive is advancing, negative is declining, zero is unchanged.
37 pub change: f64,
38 /// Period volume for the symbol (finite, non-negative).
39 pub volume: f64,
40 /// Whether the symbol printed a new period high.
41 pub new_high: bool,
42 /// Whether the symbol printed a new period low.
43 pub new_low: bool,
44}
45
46impl Member {
47 /// Assemble a cross-section member.
48 ///
49 /// The field invariants documented on [`Member`] are validated centrally by
50 /// [`CrossSection::new`] when the member is placed into a tick; this
51 /// constructor only assembles the value so the `#[non_exhaustive]` struct can
52 /// be built from outside the crate.
53 #[must_use]
54 pub const fn new(change: f64, volume: f64, new_high: bool, new_low: bool) -> Self {
55 Self {
56 change,
57 volume,
58 new_high,
59 new_low,
60 }
61 }
62}
63
64/// A market-breadth cross-section: the per-symbol state of an entire universe at
65/// a single point in time.
66///
67/// Invariants enforced by [`new`](CrossSection::new):
68///
69/// - `members` is non-empty (a breadth reading needs at least one symbol).
70/// - every member's `change` is finite, and `volume` is finite and non-negative.
71///
72/// `timestamp` is a caller-defined epoch / resolution and is not validated.
73#[non_exhaustive]
74#[derive(Debug, Clone, PartialEq)]
75pub struct CrossSection {
76 /// Per-symbol members of the universe for this tick.
77 pub members: Vec<Member>,
78 /// Tick timestamp (caller-defined epoch / resolution).
79 pub timestamp: i64,
80}
81
82impl CrossSection {
83 /// Construct a cross-section, validating every member invariant.
84 ///
85 /// # Errors
86 ///
87 /// Returns [`Error::InvalidCrossSection`] if `members` is empty, if any
88 /// member has a non-finite `change`, or if any member has a `volume` that is
89 /// not a finite non-negative number.
90 pub fn new(members: Vec<Member>, timestamp: i64) -> Result<Self> {
91 if members.is_empty() {
92 return Err(Error::InvalidCrossSection {
93 message: "cross-section must contain at least one member",
94 });
95 }
96 for member in &members {
97 if !member.change.is_finite() {
98 return Err(Error::InvalidCrossSection {
99 message: "member change must be finite",
100 });
101 }
102 if !member.volume.is_finite() || member.volume < 0.0 {
103 return Err(Error::InvalidCrossSection {
104 message: "member volume must be finite and non-negative",
105 });
106 }
107 }
108 Ok(Self { members, timestamp })
109 }
110
111 /// Construct a cross-section without validation. The caller asserts that
112 /// every invariant documented on [`CrossSection`] holds.
113 #[must_use]
114 pub const fn new_unchecked(members: Vec<Member>, timestamp: i64) -> Self {
115 Self { members, timestamp }
116 }
117
118 /// Number of advancing symbols (those with a strictly positive `change`).
119 #[must_use]
120 pub fn advancers(&self) -> usize {
121 self.members.iter().filter(|m| m.change > 0.0).count()
122 }
123
124 /// Number of declining symbols (those with a strictly negative `change`).
125 #[must_use]
126 pub fn decliners(&self) -> usize {
127 self.members.iter().filter(|m| m.change < 0.0).count()
128 }
129}
130
131#[cfg(test)]
132mod tests {
133 use super::*;
134
135 fn members() -> Vec<Member> {
136 vec![
137 Member::new(1.5, 100.0, true, false),
138 Member::new(-0.5, 50.0, false, true),
139 Member::new(0.0, 0.0, false, false),
140 ]
141 }
142
143 #[test]
144 fn new_accepts_valid() {
145 let cs = CrossSection::new(members(), 42).unwrap();
146 assert_eq!(cs.members.len(), 3);
147 assert_eq!(cs.timestamp, 42);
148 assert_eq!(cs.members[0].change, 1.5);
149 assert_eq!(cs.members[0].volume, 100.0);
150 assert!(cs.members[0].new_high);
151 assert!(cs.members[1].new_low);
152 }
153
154 #[test]
155 fn member_new_assembles_fields() {
156 let m = Member::new(2.0, 10.0, true, false);
157 assert_eq!(m.change, 2.0);
158 assert_eq!(m.volume, 10.0);
159 assert!(m.new_high);
160 assert!(!m.new_low);
161 }
162
163 #[test]
164 fn new_rejects_empty() {
165 assert!(matches!(
166 CrossSection::new(Vec::new(), 0),
167 Err(Error::InvalidCrossSection { .. })
168 ));
169 }
170
171 #[test]
172 fn new_rejects_non_finite_change() {
173 assert!(matches!(
174 CrossSection::new(vec![Member::new(f64::NAN, 10.0, false, false)], 0),
175 Err(Error::InvalidCrossSection { .. })
176 ));
177 assert!(matches!(
178 CrossSection::new(vec![Member::new(f64::INFINITY, 10.0, false, false)], 0),
179 Err(Error::InvalidCrossSection { .. })
180 ));
181 }
182
183 #[test]
184 fn new_rejects_negative_volume() {
185 assert!(matches!(
186 CrossSection::new(vec![Member::new(1.0, -1.0, false, false)], 0),
187 Err(Error::InvalidCrossSection { .. })
188 ));
189 }
190
191 #[test]
192 fn new_rejects_non_finite_volume() {
193 assert!(matches!(
194 CrossSection::new(vec![Member::new(1.0, f64::NAN, false, false)], 0),
195 Err(Error::InvalidCrossSection { .. })
196 ));
197 }
198
199 #[test]
200 fn new_unchecked_skips_validation() {
201 let cs = CrossSection::new_unchecked(vec![Member::new(f64::NAN, -1.0, false, false)], 7);
202 assert_eq!(cs.members.len(), 1);
203 assert_eq!(cs.timestamp, 7);
204 }
205
206 #[test]
207 fn advancers_and_decliners_count_by_sign() {
208 let cs = CrossSection::new(members(), 0).unwrap();
209 assert_eq!(cs.advancers(), 1);
210 assert_eq!(cs.decliners(), 1);
211 }
212
213 #[test]
214 fn unchanged_members_count_as_neither() {
215 let cs = CrossSection::new(
216 vec![
217 Member::new(0.0, 1.0, false, false),
218 Member::new(0.0, 1.0, false, false),
219 ],
220 0,
221 )
222 .unwrap();
223 assert_eq!(cs.advancers(), 0);
224 assert_eq!(cs.decliners(), 0);
225 }
226}