1use std::cmp::Ordering;
2use std::collections::HashSet;
3
4use polars::prelude::{Column, DataFrame, IntoColumn, NamedFrom, Series, TimeUnit, TimeZone};
5use serde::{Deserialize, Serialize};
6
7use crate::{FerricAlphaError, Result};
8
9const NEW_OPERATION: &str = "ReportTable::new";
10
11#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
12pub struct ReportTable {
13 id: String,
14 title: String,
15 row_count: usize,
16 sort_by: Vec<String>,
17 columns: Vec<ReportColumn>,
18}
19
20#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
21pub struct ReportColumn {
22 name: String,
23 label: String,
24 role: ColumnRole,
25 display: Option<DisplayFormat>,
26 data: ReportColumnData,
27}
28
29#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
30#[serde(rename_all = "snake_case")]
31pub enum ReportColumnData {
32 Boolean(Vec<Option<bool>>),
33 Int32(Vec<Option<i32>>),
34 Int64(Vec<Option<i64>>),
35 UInt32(Vec<Option<u32>>),
36 UInt64(Vec<Option<u64>>),
37 Float64(Vec<Option<f64>>),
38 String(Vec<Option<String>>),
39 Datetime {
40 values: Vec<Option<i64>>,
41 time_unit: ReportTimeUnit,
42 timezone: Option<String>,
43 },
44}
45
46#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
47#[serde(rename_all = "snake_case")]
48pub enum ColumnRole {
49 Dimension,
50 Measure,
51 Statistic,
52}
53
54#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
55#[serde(rename_all = "snake_case")]
56pub enum ReportTimeUnit {
57 Nanoseconds,
58 Microseconds,
59 Milliseconds,
60}
61
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
63pub struct DisplayFormat {
64 unit: DisplayUnit,
65 decimals: u8,
66}
67
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
69#[serde(rename_all = "snake_case")]
70pub enum DisplayUnit {
71 Raw,
72 DecimalReturn,
73 BasisPoints,
74 Percent,
75 Ratio,
76 Count,
77}
78
79#[derive(Debug, Clone, Copy, PartialEq)]
80enum SortValue<'a> {
81 Boolean(bool),
82 Int32(i32),
83 Int64(i64),
84 UInt32(u32),
85 UInt64(u64),
86 Float64(f64),
87 String(&'a str),
88 Datetime(i64),
89}
90
91impl ReportTable {
92 pub fn new(
93 id: impl Into<String>,
94 title: impl Into<String>,
95 sort_by: Vec<String>,
96 columns: Vec<ReportColumn>,
97 ) -> Result<Self> {
98 let id = id.into();
99 if !valid_table_id(&id) {
100 return invalid("invalid table id");
101 }
102
103 let mut names = HashSet::with_capacity(columns.len());
104 for column in &columns {
105 if !names.insert(column.name.as_str()) {
106 return invalid("duplicate column name");
107 }
108 if matches!(&column.data, ReportColumnData::Float64(values) if values
109 .iter()
110 .flatten()
111 .any(|value| !value.is_finite()))
112 {
113 return invalid("float value is not finite");
114 }
115 }
116
117 let row_count = match columns.first() {
118 Some(column) => column.data.len(),
119 None => 0,
120 };
121 if columns.iter().any(|column| column.data.len() != row_count) {
122 return invalid("column lengths differ");
123 }
124
125 let sort_columns = sort_by
126 .iter()
127 .map(|name| {
128 columns.iter().find(|column| column.name == *name).ok_or(
129 FerricAlphaError::InvalidReport {
130 operation: NEW_OPERATION,
131 reason: "sort key missing",
132 },
133 )
134 })
135 .collect::<Result<Vec<_>>>()?;
136
137 for row in 0..row_count {
138 if sort_columns
139 .iter()
140 .any(|column| column.data.sort_value(row).is_none())
141 {
142 return invalid("sort key contains null");
143 }
144 }
145
146 for row in 1..row_count {
147 let ordering = compare_rows(&sort_columns, row - 1, row);
148 if ordering == Some(Ordering::Greater) {
149 return invalid("rows are not sorted by sort_by");
150 }
151 }
152
153 Ok(Self {
154 id,
155 title: title.into(),
156 row_count,
157 sort_by,
158 columns,
159 })
160 }
161
162 pub fn id(&self) -> &str {
163 &self.id
164 }
165
166 pub fn title(&self) -> &str {
167 &self.title
168 }
169
170 pub fn row_count(&self) -> usize {
171 self.row_count
172 }
173
174 pub fn sort_by(&self) -> &[String] {
175 &self.sort_by
176 }
177
178 pub fn columns(&self) -> &[ReportColumn] {
179 &self.columns
180 }
181
182 pub fn column_names(&self) -> Vec<&str> {
183 self.columns
184 .iter()
185 .map(|column| column.name.as_str())
186 .collect()
187 }
188
189 pub fn to_polars(&self) -> Result<DataFrame> {
190 let columns = self
191 .columns
192 .iter()
193 .map(ReportColumn::to_polars)
194 .collect::<Result<Vec<_>>>()?;
195 Ok(DataFrame::new(self.row_count, columns)?)
196 }
197}
198
199impl ReportColumn {
200 pub fn new(
201 name: impl Into<String>,
202 label: impl Into<String>,
203 role: ColumnRole,
204 display: Option<DisplayFormat>,
205 data: ReportColumnData,
206 ) -> Self {
207 Self {
208 name: name.into(),
209 label: label.into(),
210 role,
211 display,
212 data,
213 }
214 }
215
216 pub fn name(&self) -> &str {
217 &self.name
218 }
219
220 pub fn label(&self) -> &str {
221 &self.label
222 }
223
224 pub fn role(&self) -> ColumnRole {
225 self.role
226 }
227
228 pub fn display(&self) -> Option<&DisplayFormat> {
229 self.display.as_ref()
230 }
231
232 pub fn data(&self) -> &ReportColumnData {
233 &self.data
234 }
235
236 fn to_polars(&self) -> Result<Column> {
237 let column = match &self.data {
238 ReportColumnData::Boolean(values) => {
239 Series::new(self.name.as_str().into(), values).into_column()
240 }
241 ReportColumnData::Int32(values) => {
242 Series::new(self.name.as_str().into(), values).into_column()
243 }
244 ReportColumnData::Int64(values) => {
245 Series::new(self.name.as_str().into(), values).into_column()
246 }
247 ReportColumnData::UInt32(values) => {
248 Series::new(self.name.as_str().into(), values).into_column()
249 }
250 ReportColumnData::UInt64(values) => {
251 Series::new(self.name.as_str().into(), values).into_column()
252 }
253 ReportColumnData::Float64(values) => {
254 Series::new(self.name.as_str().into(), values).into_column()
255 }
256 ReportColumnData::String(values) => {
257 Series::new(self.name.as_str().into(), values).into_column()
258 }
259 ReportColumnData::Datetime {
260 values,
261 time_unit,
262 timezone,
263 } => Series::new(self.name.as_str().into(), values)
264 .into_datetime(
265 (*time_unit).into(),
266 TimeZone::opt_try_new(timezone.as_deref())?,
267 )
268 .into_column(),
269 };
270 Ok(column)
271 }
272}
273
274impl ReportColumnData {
275 pub fn len(&self) -> usize {
276 match self {
277 Self::Boolean(values) => values.len(),
278 Self::Int32(values) => values.len(),
279 Self::Int64(values) => values.len(),
280 Self::UInt32(values) => values.len(),
281 Self::UInt64(values) => values.len(),
282 Self::Float64(values) => values.len(),
283 Self::String(values) => values.len(),
284 Self::Datetime { values, .. } => values.len(),
285 }
286 }
287
288 pub fn is_empty(&self) -> bool {
289 self.len() == 0
290 }
291
292 fn sort_value(&self, row: usize) -> Option<SortValue<'_>> {
293 match self {
294 Self::Boolean(values) => values.get(row).copied().flatten().map(SortValue::Boolean),
295 Self::Int32(values) => values.get(row).copied().flatten().map(SortValue::Int32),
296 Self::Int64(values) => values.get(row).copied().flatten().map(SortValue::Int64),
297 Self::UInt32(values) => values.get(row).copied().flatten().map(SortValue::UInt32),
298 Self::UInt64(values) => values.get(row).copied().flatten().map(SortValue::UInt64),
299 Self::Float64(values) => values.get(row).copied().flatten().map(SortValue::Float64),
300 Self::String(values) => values
301 .get(row)
302 .and_then(Option::as_deref)
303 .map(SortValue::String),
304 Self::Datetime { values, .. } => {
305 values.get(row).copied().flatten().map(SortValue::Datetime)
306 }
307 }
308 }
309}
310
311impl DisplayFormat {
312 pub fn new(unit: DisplayUnit, decimals: u8) -> Self {
313 Self { unit, decimals }
314 }
315
316 pub fn unit(&self) -> DisplayUnit {
317 self.unit
318 }
319
320 pub fn decimals(&self) -> u8 {
321 self.decimals
322 }
323}
324
325impl From<ReportTimeUnit> for TimeUnit {
326 fn from(value: ReportTimeUnit) -> Self {
327 match value {
328 ReportTimeUnit::Nanoseconds => Self::Nanoseconds,
329 ReportTimeUnit::Microseconds => Self::Microseconds,
330 ReportTimeUnit::Milliseconds => Self::Milliseconds,
331 }
332 }
333}
334
335fn invalid<T>(reason: &'static str) -> Result<T> {
336 Err(FerricAlphaError::InvalidReport {
337 operation: NEW_OPERATION,
338 reason,
339 })
340}
341
342fn compare_rows(columns: &[&ReportColumn], left: usize, right: usize) -> Option<Ordering> {
343 for column in columns {
344 let left = column.data.sort_value(left)?;
345 let right = column.data.sort_value(right)?;
346 let ordering = left.partial_cmp(&right)?;
347 if ordering != Ordering::Equal {
348 return Some(ordering);
349 }
350 }
351 Some(Ordering::Equal)
352}
353
354fn valid_table_id(id: &str) -> bool {
355 !id.is_empty() && id.split('.').all(valid_table_id_segment)
356}
357
358fn valid_table_id_segment(segment: &str) -> bool {
359 if segment.is_empty()
360 || segment.starts_with('_')
361 || segment.ends_with('_')
362 || segment.contains("__")
363 {
364 return false;
365 }
366
367 segment.chars().enumerate().all(|(index, character)| {
368 character.is_ascii_lowercase()
369 || (index > 0 && (character.is_ascii_digit() || character == '_'))
370 })
371}
372
373impl PartialOrd for SortValue<'_> {
374 fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
375 match (self, other) {
376 (Self::Boolean(left), Self::Boolean(right)) => left.partial_cmp(right),
377 (Self::Int32(left), Self::Int32(right)) => left.partial_cmp(right),
378 (Self::Int64(left), Self::Int64(right)) => left.partial_cmp(right),
379 (Self::UInt32(left), Self::UInt32(right)) => left.partial_cmp(right),
380 (Self::UInt64(left), Self::UInt64(right)) => left.partial_cmp(right),
381 (Self::Float64(left), Self::Float64(right)) => left.partial_cmp(right),
382 (Self::String(left), Self::String(right)) => left.partial_cmp(right),
383 (Self::Datetime(left), Self::Datetime(right)) => left.partial_cmp(right),
384 _ => None,
385 }
386 }
387}