Skip to main content

astrs_node_api/message/
scalar.rs

1//! `std/core/v1` and `std/time/v1` — the scalar channels (§24.3).
2//!
3//! The simplest useful message there is: a single value, or a run of them, in
4//! one unnested column. A [`Scalar<f64>`](Scalar) message is a one-row
5//! `Float64` column; a [`ScalarRun<f64>`](ScalarRun) is an *n*-row one. Both
6//! declare the same URN, because the URN names the element type and the row
7//! count is data — which is what lets a node batch a hundred readings into one
8//! message without changing its port's declared type.
9//!
10//! | Rust | URN | Layout |
11//! |---|---|---|
12//! | [`Scalar<T>`] / [`ScalarRun<T>`] | `std/core/v1/{Int,UInt,Float}N` | the matching primitive |
13//! | [`Flag`] / [`FlagRun`] | `std/core/v1/Bool` | `Bool` |
14//! | [`Text`] / [`TextRun`] | `std/core/v1/String` | `Utf8` |
15//! | [`Bytes`] / [`BytesRun`] | `std/core/v1/Bytes` | `Binary` |
16//! | [`Empty`] | `std/core/v1/Empty` | `Null` |
17//! | [`Timestamp`] / [`TimestampRun`] | `std/time/v1/Timestamp` | `Timestamp(ns)` |
18//! | [`Duration`] | `std/time/v1/Duration` | `Duration(ns)` |
19//!
20//! # Why newtypes rather than `impl AstrsMessage for f64`
21//!
22//! [`AstrsMessage`] is declared in `astrs-data` (it has to be — see that
23//! crate's `message` module), and `f64` is declared in `core`. Rust's orphan
24//! rule forbids this crate from pairing two foreign items, so the primitives
25//! reach the trait through a local wrapper. The wrapper is not friction in
26//! practice: every one of these types is `From` its inner value, and the typed
27//! output handle takes `impl Into<T>`, so a node writes `speed.send(2.5, …)`
28//! and never names [`Scalar`] at all.
29//!
30//! # Examples
31//!
32//! ```
33//! use astrs_node_api::message::{AstrsMessage, Bytes, Scalar, ScalarRun, Timestamp};
34//!
35//! let batch = Scalar::from(2.5_f64).to_record_batch()?;
36//! assert_eq!(Scalar::<f64>::from_record_batch(&batch)?.into_inner(), 2.5);
37//!
38//! let many = ScalarRun::from(vec![1.0_f64, 2.0, 3.0]).to_record_batch()?;
39//! assert_eq!(many.num_rows(), 3);
40//!
41//! assert_eq!(Bytes::URN, "std/core/v1/Bytes");
42//! assert_eq!(Timestamp::from_nanos(7).nanos(), 7);
43//! # Ok::<(), astrs_data::DataError>(())
44//! ```
45
46use astrs_data::array::{
47    Array, ArrayExt, ArrayRef, BinaryArray, BooleanArray, DurationArray, IntoArrayRef, NullArray,
48    StringArray, TimestampArray,
49};
50use astrs_data::{ArrowNativeType, AstrsMessage, DataError, DataType, RecordBatch, Result};
51
52use super::{build, payload_column, read, single_row_column};
53
54/// A primitive with a `std/core/v1` URN.
55///
56/// The bridge between `astrs-data`'s sealed [`ArrowNativeType`] and the §24.3
57/// registry: each primitive knows which scalar channel it *is*.
58///
59/// # Examples
60///
61/// ```
62/// use astrs_node_api::message::scalar::ScalarType;
63///
64/// assert_eq!(<f32 as ScalarType>::SCALAR_URN, "std/core/v1/Float32");
65/// assert_eq!(<u16 as ScalarType>::SCALAR_URN, "std/core/v1/UInt16");
66/// ```
67pub trait ScalarType: ArrowNativeType {
68    /// The `std/core/v1` URN of this element type.
69    const SCALAR_URN: &'static str;
70}
71
72/// Declares a primitive's scalar channel.
73macro_rules! scalar_type {
74    ($ty:ty, $urn:literal) => {
75        impl ScalarType for $ty {
76            const SCALAR_URN: &'static str = $urn;
77        }
78    };
79}
80
81scalar_type!(i8, "std/core/v1/Int8");
82scalar_type!(i16, "std/core/v1/Int16");
83scalar_type!(i32, "std/core/v1/Int32");
84scalar_type!(i64, "std/core/v1/Int64");
85scalar_type!(u8, "std/core/v1/UInt8");
86scalar_type!(u16, "std/core/v1/UInt16");
87scalar_type!(u32, "std/core/v1/UInt32");
88scalar_type!(u64, "std/core/v1/UInt64");
89scalar_type!(f32, "std/core/v1/Float32");
90scalar_type!(f64, "std/core/v1/Float64");
91scalar_type!(astrs_data::F16, "std/core/v1/Float16");
92
93/// One primitive reading — a one-row `std/core/v1` channel message.
94#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
95pub struct Scalar<T: ScalarType>(pub T);
96
97impl<T: ScalarType> Scalar<T> {
98    /// Wraps a value.
99    #[must_use]
100    pub const fn new(value: T) -> Self {
101        Self(value)
102    }
103
104    /// Unwraps the value.
105    #[must_use]
106    pub fn into_inner(self) -> T {
107        self.0
108    }
109
110    /// The value.
111    #[must_use]
112    pub const fn get(&self) -> &T {
113        &self.0
114    }
115}
116
117impl<T: ScalarType> From<T> for Scalar<T> {
118    fn from(value: T) -> Self {
119        Self(value)
120    }
121}
122
123impl<T: ScalarType> AstrsMessage for Scalar<T> {
124    const URN: &'static str = T::SCALAR_URN;
125
126    fn data_type() -> DataType {
127        T::DATA_TYPE
128    }
129
130    fn to_record_batch(&self) -> Result<RecordBatch> {
131        Ok(RecordBatch::from_payload(build::primitive::<T>(
132            core::slice::from_ref(&self.0),
133        )))
134    }
135
136    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
137        Ok(Self(read::primitive_at::<T>(single_row_column(batch)?, 0)?))
138    }
139}
140
141impl<T: ScalarType> super::FromPayload for Scalar<T> {
142    fn from_batch(batch: &RecordBatch) -> Result<Self> {
143        Self::from_record_batch(batch)
144    }
145}
146
147/// A run of primitive readings — an *n*-row `std/core/v1` channel message.
148#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
149pub struct ScalarRun<T: ScalarType>(pub Vec<T>);
150
151impl<T: ScalarType> ScalarRun<T> {
152    /// Wraps a vector of values.
153    #[must_use]
154    pub const fn new(values: Vec<T>) -> Self {
155        Self(values)
156    }
157
158    /// The values.
159    #[must_use]
160    pub fn as_slice(&self) -> &[T] {
161        &self.0
162    }
163
164    /// Unwraps the vector.
165    #[must_use]
166    pub fn into_vec(self) -> Vec<T> {
167        self.0
168    }
169
170    /// How many readings the run holds.
171    #[must_use]
172    pub fn len(&self) -> usize {
173        self.0.len()
174    }
175
176    /// Whether the run is empty.
177    #[must_use]
178    pub fn is_empty(&self) -> bool {
179        self.0.is_empty()
180    }
181}
182
183impl<T: ScalarType> From<Vec<T>> for ScalarRun<T> {
184    fn from(values: Vec<T>) -> Self {
185        Self(values)
186    }
187}
188
189impl<T: ScalarType> AstrsMessage for ScalarRun<T> {
190    const URN: &'static str = T::SCALAR_URN;
191
192    fn data_type() -> DataType {
193        T::DATA_TYPE
194    }
195
196    fn to_record_batch(&self) -> Result<RecordBatch> {
197        Ok(RecordBatch::from_payload(build::primitive::<T>(&self.0)))
198    }
199
200    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
201        let column = payload_column(batch)?;
202        (0..column.len())
203            .map(|row| read::primitive_at::<T>(column, row))
204            .collect::<Result<Vec<T>>>()
205            .map(Self)
206    }
207}
208
209impl<T: ScalarType> super::FromPayload for ScalarRun<T> {
210    fn from_batch(batch: &RecordBatch) -> Result<Self> {
211        Self::from_record_batch(batch)
212    }
213}
214
215/// One boolean reading — `std/core/v1/Bool`.
216#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
217pub struct Flag(pub bool);
218
219impl Flag {
220    /// The value.
221    #[must_use]
222    pub const fn get(self) -> bool {
223        self.0
224    }
225}
226
227impl From<bool> for Flag {
228    fn from(value: bool) -> Self {
229        Self(value)
230    }
231}
232
233impl AstrsMessage for Flag {
234    const URN: &'static str = "std/core/v1/Bool";
235
236    fn data_type() -> DataType {
237        DataType::Bool
238    }
239
240    fn to_record_batch(&self) -> Result<RecordBatch> {
241        Ok(RecordBatch::from_payload(build::boolean(&[self.0])))
242    }
243
244    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
245        Ok(Self(read::bool_at(single_row_column(batch)?, 0)?))
246    }
247}
248
249super::impl_from_payload!(Flag);
250
251/// A run of boolean readings — `std/core/v1/Bool`.
252#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
253pub struct FlagRun(pub Vec<bool>);
254
255impl From<Vec<bool>> for FlagRun {
256    fn from(values: Vec<bool>) -> Self {
257        Self(values)
258    }
259}
260
261impl AstrsMessage for FlagRun {
262    const URN: &'static str = "std/core/v1/Bool";
263
264    fn data_type() -> DataType {
265        DataType::Bool
266    }
267
268    fn to_record_batch(&self) -> Result<RecordBatch> {
269        Ok(RecordBatch::from_payload(build::boolean(&self.0)))
270    }
271
272    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
273        Ok(Self(booleans_of(batch)?))
274    }
275}
276
277super::impl_from_payload!(FlagRun);
278
279/// One UTF-8 string — `std/core/v1/String`.
280#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
281pub struct Text(pub String);
282
283impl Text {
284    /// The string.
285    #[must_use]
286    pub fn as_str(&self) -> &str {
287        &self.0
288    }
289
290    /// Unwraps the string.
291    #[must_use]
292    pub fn into_string(self) -> String {
293        self.0
294    }
295}
296
297impl From<String> for Text {
298    fn from(value: String) -> Self {
299        Self(value)
300    }
301}
302
303impl From<&str> for Text {
304    fn from(value: &str) -> Self {
305        Self(value.to_owned())
306    }
307}
308
309impl AstrsMessage for Text {
310    const URN: &'static str = "std/core/v1/String";
311
312    fn data_type() -> DataType {
313        DataType::Utf8
314    }
315
316    fn to_record_batch(&self) -> Result<RecordBatch> {
317        Ok(RecordBatch::from_payload(build::strings(&[&self.0])))
318    }
319
320    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
321        Ok(Self(read::str_at(single_row_column(batch)?, 0)?.to_owned()))
322    }
323}
324
325super::impl_from_payload!(Text);
326
327/// A run of UTF-8 strings — `std/core/v1/String`.
328#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
329pub struct TextRun(pub Vec<String>);
330
331impl From<Vec<String>> for TextRun {
332    fn from(values: Vec<String>) -> Self {
333        Self(values)
334    }
335}
336
337impl AstrsMessage for TextRun {
338    const URN: &'static str = "std/core/v1/String";
339
340    fn data_type() -> DataType {
341        DataType::Utf8
342    }
343
344    fn to_record_batch(&self) -> Result<RecordBatch> {
345        Ok(RecordBatch::from_payload(build::strings(&self.0)))
346    }
347
348    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
349        Ok(Self(strings_of(batch)?))
350    }
351}
352
353super::impl_from_payload!(TextRun);
354
355/// Opaque bytes — `std/core/v1/Bytes`.
356///
357/// One blob is **one row**, in contrast to `ScalarRun<u8>`, where one sample
358/// is one row. Saying which of the two a port carries is the whole point of
359/// having both.
360#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
361pub struct Bytes(pub Vec<u8>);
362
363impl Bytes {
364    /// Wraps a byte vector.
365    #[must_use]
366    pub const fn new(bytes: Vec<u8>) -> Self {
367        Self(bytes)
368    }
369
370    /// The bytes.
371    #[must_use]
372    pub fn as_slice(&self) -> &[u8] {
373        &self.0
374    }
375
376    /// Unwraps the byte vector.
377    #[must_use]
378    pub fn into_vec(self) -> Vec<u8> {
379        self.0
380    }
381}
382
383impl From<Vec<u8>> for Bytes {
384    fn from(bytes: Vec<u8>) -> Self {
385        Self(bytes)
386    }
387}
388
389impl AsRef<[u8]> for Bytes {
390    fn as_ref(&self) -> &[u8] {
391        &self.0
392    }
393}
394
395impl AstrsMessage for Bytes {
396    const URN: &'static str = "std/core/v1/Bytes";
397
398    fn data_type() -> DataType {
399        DataType::Binary
400    }
401
402    fn to_record_batch(&self) -> Result<RecordBatch> {
403        Ok(RecordBatch::from_payload(build::binaries(&[&self.0])))
404    }
405
406    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
407        Ok(Self(read::bytes_at(single_row_column(batch)?, 0)?.to_vec()))
408    }
409}
410
411super::impl_from_payload!(Bytes);
412
413/// A run of opaque blobs — `std/core/v1/Bytes`, one blob per row.
414#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
415pub struct BytesRun(pub Vec<Vec<u8>>);
416
417impl From<Vec<Vec<u8>>> for BytesRun {
418    fn from(values: Vec<Vec<u8>>) -> Self {
419        Self(values)
420    }
421}
422
423impl AstrsMessage for BytesRun {
424    const URN: &'static str = "std/core/v1/Bytes";
425
426    fn data_type() -> DataType {
427        DataType::Binary
428    }
429
430    fn to_record_batch(&self) -> Result<RecordBatch> {
431        Ok(RecordBatch::from_payload(build::binaries(&self.0)))
432    }
433
434    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
435        Ok(Self(blobs_of(batch)?))
436    }
437}
438
439super::impl_from_payload!(BytesRun);
440
441/// A signal with no payload — `std/core/v1/Empty`.
442///
443/// The columnar layout is `Null`, whose row carries no bytes at all; a
444/// heartbeat or a trigger edge is exactly this.
445#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
446pub struct Empty;
447
448impl AstrsMessage for Empty {
449    const URN: &'static str = "std/core/v1/Empty";
450
451    fn data_type() -> DataType {
452        DataType::Null
453    }
454
455    fn to_record_batch(&self) -> Result<RecordBatch> {
456        Ok(RecordBatch::from_payload(
457            NullArray::new(1).into_array_ref(),
458        ))
459    }
460
461    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
462        let column = single_row_column(batch)?;
463        if column.data_type() == &DataType::Null {
464            Ok(Self)
465        } else {
466            Err(DataError::type_mismatch(
467                DataType::Null,
468                column.data_type().clone(),
469            ))
470        }
471    }
472}
473
474super::impl_from_payload!(Empty);
475
476/// A point in time — `std/time/v1/Timestamp`, nanoseconds since the Unix
477/// epoch, timezone-less.
478#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
479pub struct Timestamp {
480    /// Nanoseconds since the Unix epoch.
481    pub nanos: i64,
482}
483
484impl Timestamp {
485    /// A timestamp at `nanos` since the epoch.
486    #[must_use]
487    pub const fn from_nanos(nanos: i64) -> Self {
488        Self { nanos }
489    }
490
491    /// The value in nanoseconds.
492    #[must_use]
493    pub const fn nanos(self) -> i64 {
494        self.nanos
495    }
496
497    /// The whole seconds since the epoch, rounding towards negative infinity
498    /// so a pre-epoch stamp's sub-second part stays non-negative.
499    #[must_use]
500    pub const fn seconds(self) -> i64 {
501        self.nanos.div_euclid(1_000_000_000)
502    }
503
504    /// The nanoseconds past [`Timestamp::seconds`], always in `0..1e9`.
505    #[must_use]
506    pub fn subsec_nanos(self) -> u32 {
507        // `rem_euclid` with a positive divisor lands in `0..1e9`, which always
508        // fits a `u32`; the fallback keeps the conversion total.
509        u32::try_from(self.nanos.rem_euclid(1_000_000_000)).unwrap_or(0)
510    }
511
512    /// The matching [`astrs_time::HlcTimestamp`] reading, with `counter` as
513    /// its logical component.
514    #[must_use]
515    pub fn to_hlc(self, counter: u32) -> astrs_time::HlcTimestamp {
516        astrs_time::HlcTimestamp::new(self.nanos.max(0).unsigned_abs(), counter)
517    }
518
519    /// The timestamp an [`astrs_time::HlcTimestamp`] names.
520    #[must_use]
521    pub fn from_hlc(hlc: astrs_time::HlcTimestamp) -> Self {
522        Self::from_nanos(i64::try_from(hlc.physical_ns()).unwrap_or(i64::MAX))
523    }
524}
525
526impl From<i64> for Timestamp {
527    fn from(nanos: i64) -> Self {
528        Self::from_nanos(nanos)
529    }
530}
531
532impl AstrsMessage for Timestamp {
533    const URN: &'static str = "std/time/v1/Timestamp";
534
535    fn data_type() -> DataType {
536        DataType::Timestamp
537    }
538
539    fn to_record_batch(&self) -> Result<RecordBatch> {
540        Ok(RecordBatch::from_payload(build::timestamps(&[self.nanos])))
541    }
542
543    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
544        Ok(Self::from_nanos(read::timestamp_at(
545            single_row_column(batch)?,
546            0,
547        )?))
548    }
549}
550
551super::impl_from_payload!(Timestamp);
552
553/// A run of timestamps — `std/time/v1/Timestamp`.
554#[derive(Debug, Clone, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
555pub struct TimestampRun(pub Vec<Timestamp>);
556
557impl From<Vec<Timestamp>> for TimestampRun {
558    fn from(values: Vec<Timestamp>) -> Self {
559        Self(values)
560    }
561}
562
563impl AstrsMessage for TimestampRun {
564    const URN: &'static str = "std/time/v1/Timestamp";
565
566    fn data_type() -> DataType {
567        DataType::Timestamp
568    }
569
570    fn to_record_batch(&self) -> Result<RecordBatch> {
571        let nanos: Vec<i64> = self.0.iter().map(|stamp| stamp.nanos).collect();
572        Ok(RecordBatch::from_payload(build::timestamps(&nanos)))
573    }
574
575    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
576        Ok(Self(
577            timestamps_of(batch)?
578                .into_iter()
579                .map(Timestamp::from_nanos)
580                .collect(),
581        ))
582    }
583}
584
585super::impl_from_payload!(TimestampRun);
586
587/// A time interval — `std/time/v1/Duration`, in nanoseconds.
588///
589/// Signed, because "how far behind schedule" is as useful a reading as "how
590/// far ahead".
591#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
592pub struct Duration {
593    /// The interval in nanoseconds.
594    pub nanos: i64,
595}
596
597impl Duration {
598    /// An interval of `nanos` nanoseconds.
599    #[must_use]
600    pub const fn from_nanos(nanos: i64) -> Self {
601        Self { nanos }
602    }
603
604    /// An interval of `millis` milliseconds.
605    #[must_use]
606    pub const fn from_millis(millis: i64) -> Self {
607        Self {
608            nanos: millis.saturating_mul(1_000_000),
609        }
610    }
611
612    /// The interval in nanoseconds.
613    #[must_use]
614    pub const fn nanos(self) -> i64 {
615        self.nanos
616    }
617
618    /// Whether the interval runs backwards.
619    #[must_use]
620    pub const fn is_negative(self) -> bool {
621        self.nanos < 0
622    }
623
624    /// The interval as a [`core::time::Duration`], clamped at zero.
625    #[must_use]
626    pub const fn to_std(self) -> core::time::Duration {
627        if self.nanos <= 0 {
628            core::time::Duration::ZERO
629        } else {
630            core::time::Duration::from_nanos(self.nanos.unsigned_abs())
631        }
632    }
633}
634
635impl AstrsMessage for Duration {
636    const URN: &'static str = "std/time/v1/Duration";
637
638    fn data_type() -> DataType {
639        DataType::Duration
640    }
641
642    fn to_record_batch(&self) -> Result<RecordBatch> {
643        Ok(RecordBatch::from_payload(
644            DurationArray::from_nanos([self.nanos]).into_array_ref(),
645        ))
646    }
647
648    fn from_record_batch(batch: &RecordBatch) -> Result<Self> {
649        let column = single_row_column(batch)?;
650        let array = column.downcast::<DurationArray>().ok_or_else(|| {
651            DataError::type_mismatch(DataType::Duration, column.data_type().clone())
652        })?;
653        let nanos = array
654            .value(0)
655            .ok_or(DataError::IndexOutOfBounds { index: 0, len: 0 })?;
656        Ok(Self::from_nanos(nanos))
657    }
658}
659
660super::impl_from_payload!(Duration);
661
662/// The `"data"` column of `batch` as owned strings, whatever its row count.
663///
664/// # Errors
665///
666/// [`DataError`] when the column is not `Utf8`.
667pub fn strings_of(batch: &RecordBatch) -> Result<Vec<String>> {
668    let column = payload_column(batch)?;
669    let array = column
670        .downcast::<StringArray>()
671        .ok_or_else(|| DataError::type_mismatch(DataType::Utf8, column.data_type().clone()))?;
672    (0..array.len())
673        .map(|row| {
674            array
675                .value(row)
676                .map(str::to_owned)
677                .ok_or(DataError::IndexOutOfBounds {
678                    index: row,
679                    len: array.len(),
680                })
681        })
682        .collect()
683}
684
685/// The `"data"` column of `batch` as a boolean run.
686///
687/// # Errors
688///
689/// [`DataError`] when the column is not `Bool`.
690pub fn booleans_of(batch: &RecordBatch) -> Result<Vec<bool>> {
691    let column = payload_column(batch)?;
692    let array = column
693        .downcast::<BooleanArray>()
694        .ok_or_else(|| DataError::type_mismatch(DataType::Bool, column.data_type().clone()))?;
695    (0..array.len())
696        .map(|row| {
697            array.value(row).ok_or(DataError::IndexOutOfBounds {
698                index: row,
699                len: array.len(),
700            })
701        })
702        .collect()
703}
704
705/// The `"data"` column of `batch` as a binary run.
706///
707/// # Errors
708///
709/// [`DataError`] when the column is not `Binary`.
710pub fn blobs_of(batch: &RecordBatch) -> Result<Vec<Vec<u8>>> {
711    let column = payload_column(batch)?;
712    let array = column
713        .downcast::<BinaryArray>()
714        .ok_or_else(|| DataError::type_mismatch(DataType::Binary, column.data_type().clone()))?;
715    (0..array.len())
716        .map(|row| {
717            array
718                .value(row)
719                .map(<[u8]>::to_vec)
720                .ok_or(DataError::IndexOutOfBounds {
721                    index: row,
722                    len: array.len(),
723                })
724        })
725        .collect()
726}
727
728/// The `"data"` column of `batch` as nanosecond timestamps.
729///
730/// # Errors
731///
732/// [`DataError`] when the column is not `Timestamp`.
733pub fn timestamps_of(batch: &RecordBatch) -> Result<Vec<i64>> {
734    let column = payload_column(batch)?;
735    let array = column
736        .downcast::<TimestampArray>()
737        .ok_or_else(|| DataError::type_mismatch(DataType::Timestamp, column.data_type().clone()))?;
738    (0..array.len())
739        .map(|row| {
740            array.value(row).ok_or(DataError::IndexOutOfBounds {
741                index: row,
742                len: array.len(),
743            })
744        })
745        .collect()
746}
747
748/// The `"data"` column, whatever it is — the untyped escape hatch for a
749/// `type: any` port (§3.7).
750///
751/// # Errors
752///
753/// [`DataError::ColumnCountMismatch`] when the batch carries no column.
754pub fn any_column(batch: &RecordBatch) -> Result<ArrayRef> {
755    Ok(std::sync::Arc::clone(payload_column(batch)?))
756}
757
758#[cfg(test)]
759mod tests {
760    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
761
762    use super::*;
763    use crate::message::assert_registry_layout;
764
765    #[test]
766    fn every_numeric_scalar_round_trips_and_conforms() {
767        macro_rules! check {
768            ($ty:ty, $value:expr) => {{
769                assert_registry_layout::<Scalar<$ty>>().unwrap();
770                assert_registry_layout::<ScalarRun<$ty>>().unwrap();
771                let value = Scalar::from($value);
772                let batch = value.to_record_batch().unwrap();
773                assert_eq!(batch.num_rows(), 1);
774                assert_eq!(Scalar::<$ty>::from_record_batch(&batch).unwrap(), value);
775                assert_eq!(*value.get(), $value);
776                assert_eq!(value.into_inner(), $value);
777            }};
778        }
779        check!(i8, -8);
780        check!(i16, -16);
781        check!(i32, -32);
782        check!(i64, -64);
783        check!(u8, 8);
784        check!(u16, 16);
785        check!(u32, 32);
786        check!(u64, 64);
787        check!(f32, 1.5);
788        check!(f64, -2.5);
789    }
790
791    #[test]
792    fn float16_has_a_channel_too() {
793        assert_registry_layout::<Scalar<astrs_data::F16>>().unwrap();
794        assert_eq!(
795            <astrs_data::F16 as ScalarType>::SCALAR_URN,
796            "std/core/v1/Float16"
797        );
798    }
799
800    #[test]
801    fn runs_round_trip_with_the_same_urn() {
802        assert_eq!(
803            <ScalarRun<f64> as AstrsMessage>::URN,
804            <Scalar<f64> as AstrsMessage>::URN
805        );
806        let values = ScalarRun::from(vec![1.0_f64, 2.0, 3.0]);
807        let batch = values.to_record_batch().unwrap();
808        assert_eq!(batch.num_rows(), 3);
809        assert_eq!(ScalarRun::<f64>::from_record_batch(&batch).unwrap(), values);
810        assert_eq!(values.len(), 3);
811        assert!(!values.is_empty());
812        assert_eq!(values.as_slice()[1], 2.0);
813        assert_eq!(values.clone().into_vec().len(), 3);
814        assert!(
815            Scalar::<f64>::from_record_batch(&batch).is_err(),
816            "a scalar decode of a three-row batch is a mistake, not a truncation"
817        );
818    }
819
820    #[test]
821    fn flags_round_trip() {
822        assert_registry_layout::<Flag>().unwrap();
823        assert_registry_layout::<FlagRun>().unwrap();
824        let batch = Flag::from(true).to_record_batch().unwrap();
825        assert!(Flag::from_record_batch(&batch).unwrap().get());
826        let run = FlagRun::from(vec![true, false, true])
827            .to_record_batch()
828            .unwrap();
829        assert_eq!(
830            FlagRun::from_record_batch(&run).unwrap().0,
831            vec![true, false, true]
832        );
833        assert_eq!(booleans_of(&run).unwrap(), vec![true, false, true]);
834    }
835
836    #[test]
837    fn text_round_trips() {
838        assert_registry_layout::<Text>().unwrap();
839        assert_registry_layout::<TextRun>().unwrap();
840        let batch = Text::from("hello").to_record_batch().unwrap();
841        assert_eq!(Text::from_record_batch(&batch).unwrap().as_str(), "hello");
842        assert_eq!(Text::from("x".to_owned()).into_string(), "x");
843        let run = TextRun::from(vec!["a".to_owned(), "bb".to_owned()])
844            .to_record_batch()
845            .unwrap();
846        assert_eq!(TextRun::from_record_batch(&run).unwrap().0.len(), 2);
847        assert_eq!(strings_of(&run).unwrap(), vec!["a", "bb"]);
848    }
849
850    #[test]
851    fn bytes_are_one_row_and_u8_runs_are_many() {
852        assert_registry_layout::<Bytes>().unwrap();
853        assert_registry_layout::<BytesRun>().unwrap();
854        let blob = Bytes::new(vec![1, 2, 3]);
855        let batch = blob.to_record_batch().unwrap();
856        assert_eq!(batch.num_rows(), 1, "one blob is one row");
857        assert_eq!(Bytes::from_record_batch(&batch).unwrap(), blob);
858        assert_eq!(blobs_of(&batch).unwrap(), vec![vec![1, 2, 3]]);
859
860        let samples = ScalarRun::from(vec![1u8, 2, 3]).to_record_batch().unwrap();
861        assert_eq!(samples.num_rows(), 3, "three samples are three rows");
862        assert_ne!(
863            <Bytes as AstrsMessage>::URN,
864            <ScalarRun<u8> as AstrsMessage>::URN
865        );
866
867        assert_eq!(Bytes::from(vec![7u8]).as_slice(), &[7]);
868        assert_eq!(Bytes::new(vec![7]).into_vec(), vec![7]);
869        assert_eq!(Bytes::default().as_ref(), &[] as &[u8]);
870
871        let run = BytesRun::from(vec![vec![1u8], vec![2, 3]])
872            .to_record_batch()
873            .unwrap();
874        assert_eq!(BytesRun::from_record_batch(&run).unwrap().0.len(), 2);
875    }
876
877    #[test]
878    fn empty_carries_nothing() {
879        assert_registry_layout::<Empty>().unwrap();
880        let batch = Empty.to_record_batch().unwrap();
881        assert_eq!(batch.num_rows(), 1);
882        assert_eq!(Empty::from_record_batch(&batch).unwrap(), Empty);
883        let wrong = Scalar::from(1.0_f64).to_record_batch().unwrap();
884        assert!(Empty::from_record_batch(&wrong).is_err());
885    }
886
887    #[test]
888    fn timestamps_round_trip_and_split_correctly() {
889        assert_registry_layout::<Timestamp>().unwrap();
890        assert_registry_layout::<TimestampRun>().unwrap();
891        let stamp = Timestamp::from_nanos(1_700_000_000_123_456_789);
892        let batch = stamp.to_record_batch().unwrap();
893        assert_eq!(Timestamp::from_record_batch(&batch).unwrap(), stamp);
894        assert_eq!(stamp.seconds(), 1_700_000_000);
895        assert_eq!(stamp.subsec_nanos(), 123_456_789);
896        assert_eq!(stamp.nanos(), 1_700_000_000_123_456_789);
897        assert_eq!(Timestamp::from(5_i64).nanos, 5);
898
899        // Pre-epoch stamps keep a non-negative sub-second part.
900        let before = Timestamp::from_nanos(-1);
901        assert_eq!(before.seconds(), -1);
902        assert_eq!(before.subsec_nanos(), 999_999_999);
903
904        let run = TimestampRun::from(vec![stamp, before])
905            .to_record_batch()
906            .unwrap();
907        assert_eq!(TimestampRun::from_record_batch(&run).unwrap().0.len(), 2);
908        assert_eq!(timestamps_of(&run).unwrap().len(), 2);
909
910        let hlc = stamp.to_hlc(3);
911        assert_eq!(hlc.logical(), 3);
912        assert_eq!(Timestamp::from_hlc(hlc), stamp);
913    }
914
915    #[test]
916    fn durations_round_trip() {
917        assert_registry_layout::<Duration>().unwrap();
918        let value = Duration::from_millis(-250);
919        assert_eq!(value.nanos(), -250_000_000);
920        assert!(value.is_negative());
921        assert_eq!(value.to_std(), core::time::Duration::ZERO);
922        let batch = value.to_record_batch().unwrap();
923        assert_eq!(Duration::from_record_batch(&batch).unwrap(), value);
924        assert_eq!(
925            Duration::from_nanos(1_500_000_000).to_std(),
926            core::time::Duration::from_millis(1_500)
927        );
928    }
929
930    #[test]
931    fn a_wrong_column_type_is_reported_rather_than_reinterpreted() {
932        let batch = Scalar::from(1.0_f64).to_record_batch().unwrap();
933        assert!(Scalar::<i32>::from_record_batch(&batch).is_err());
934        assert!(Text::from_record_batch(&batch).is_err());
935        assert!(Bytes::from_record_batch(&batch).is_err());
936        assert!(Timestamp::from_record_batch(&batch).is_err());
937        assert!(Duration::from_record_batch(&batch).is_err());
938        assert!(Flag::from_record_batch(&batch).is_err());
939        assert!(strings_of(&batch).is_err());
940        assert!(booleans_of(&batch).is_err());
941        assert!(blobs_of(&batch).is_err());
942        assert!(timestamps_of(&batch).is_err());
943    }
944
945    #[test]
946    fn the_untyped_escape_hatch_returns_the_column() {
947        let batch = ScalarRun::from(vec![1.0_f64, 2.0])
948            .to_record_batch()
949            .unwrap();
950        let column = any_column(&batch).unwrap();
951        assert_eq!(column.len(), 2);
952        assert_eq!(column.data_type(), &DataType::Float64);
953    }
954
955    #[test]
956    fn empty_runs_are_legal() {
957        let batch = ScalarRun::<f64>::default().to_record_batch().unwrap();
958        assert_eq!(batch.num_rows(), 0);
959        assert!(
960            ScalarRun::<f64>::from_record_batch(&batch)
961                .unwrap()
962                .is_empty()
963        );
964    }
965}