readstat/
rs_var.rs

1//! Variable types and format classification for SAS data.
2//!
3//! [`ReadStatVarFormatClass`] classifies SAS format strings into semantic categories
4//! (Date, `DateTime`, Time, and their sub-second precision variants), which determines
5//! the Arrow data type used during conversion.
6//!
7//! [`ReadStatVarType`] and [`ReadStatVarTypeClass`] map `ReadStat` C type codes to Rust
8//! enums, used during schema construction and builder allocation.
9
10use num_derive::FromPrimitive;
11use serde::Serialize;
12
13/// Semantic classification of a SAS format string.
14///
15/// Determines the Arrow data type used for date/time/datetime variables:
16///
17/// | Variant | Arrow Type |
18/// |---------|------------|
19/// | `Date` | `Date32` |
20/// | `DateTime` | `Timestamp(Second)` |
21/// | `DateTimeWithMilliseconds` | `Timestamp(Millisecond)` |
22/// | `DateTimeWithMicroseconds` | `Timestamp(Microsecond)` |
23/// | `DateTimeWithNanoseconds` | `Timestamp(Nanosecond)` |
24/// | `Time` | `Time32(Second)` |
25/// | `TimeWithMilliseconds` | `Time32(Millisecond)` |
26/// | `TimeWithMicroseconds` | `Time64(Microsecond)` |
27/// | `TimeWithNanoseconds` | `Time64(Nanosecond)` |
28///
29/// This enum is `#[non_exhaustive]`: new precision levels or format classes
30/// may be added in minor releases.
31///
32/// # Time range note
33///
34/// SAS `TIME` values are stored as seconds since midnight, but SAS treats them
35/// as durations and permits values that are negative or exceed 86 399 s (one
36/// day). Such values are written into the Arrow `Time32`/`Time64` columns as-is,
37/// without clamping — so a column may legally hold a time-of-day outside the
38/// `[0, 86400)` range that consumers of Arrow time types might assume.
39#[non_exhaustive]
40#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
41pub enum ReadStatVarFormatClass {
42    /// Date format (e.g. `DATE9`, `MMDDYY10`). Maps to Arrow `Date32`.
43    Date,
44    /// `DateTime` format with second precision (e.g. `DATETIME22`).
45    DateTime,
46    /// `DateTime` format with millisecond precision (e.g. `DATETIME22.3`).
47    DateTimeWithMilliseconds,
48    /// `DateTime` format with microsecond precision (e.g. `DATETIME22.6`).
49    DateTimeWithMicroseconds,
50    /// `DateTime` format with nanosecond precision (e.g. `DATETIME22.9`).
51    DateTimeWithNanoseconds,
52    /// Time format with second precision (e.g. `TIME8`).
53    Time,
54    /// Time format with millisecond precision (e.g. `TIME15.3`).
55    TimeWithMilliseconds,
56    /// Time format with microsecond precision (e.g. `TIME15.6`).
57    TimeWithMicroseconds,
58    /// Time format with nanosecond precision (e.g. `TIME15.9`).
59    TimeWithNanoseconds,
60}
61
62/// The storage type of a SAS variable, as reported by the `ReadStat` C library.
63///
64/// This enum is `#[non_exhaustive]`: it mirrors a C library enum that may gain
65/// variants. Match with a wildcard arm to remain forward-compatible.
66#[non_exhaustive]
67#[derive(Clone, Copy, Debug, FromPrimitive, Serialize)]
68#[allow(clippy::cast_possible_wrap)]
69pub enum ReadStatVarType {
70    /// Variable-length string.
71    String = readstat_sys::readstat_type_e_READSTAT_TYPE_STRING as isize,
72    /// 8-bit signed integer.
73    Int8 = readstat_sys::readstat_type_e_READSTAT_TYPE_INT8 as isize,
74    /// 16-bit signed integer.
75    Int16 = readstat_sys::readstat_type_e_READSTAT_TYPE_INT16 as isize,
76    /// 32-bit signed integer.
77    Int32 = readstat_sys::readstat_type_e_READSTAT_TYPE_INT32 as isize,
78    /// 32-bit floating point.
79    Float = readstat_sys::readstat_type_e_READSTAT_TYPE_FLOAT as isize,
80    /// 64-bit floating point (also used for dates/times via format class).
81    Double = readstat_sys::readstat_type_e_READSTAT_TYPE_DOUBLE as isize,
82    /// String reference (interned string).
83    StringRef = readstat_sys::readstat_type_e_READSTAT_TYPE_STRING_REF as isize,
84    /// Unknown or unrecognized type.
85    Unknown,
86}
87
88/// High-level type class of a SAS variable: string or numeric.
89///
90/// This enum is `#[non_exhaustive]`: it mirrors a C library enum that may gain
91/// variants. Match with a wildcard arm to remain forward-compatible.
92#[non_exhaustive]
93#[derive(Clone, Copy, Debug, FromPrimitive, Serialize)]
94#[allow(clippy::cast_possible_wrap)]
95pub enum ReadStatVarTypeClass {
96    /// Character/string data.
97    String = readstat_sys::readstat_type_class_e_READSTAT_TYPE_CLASS_STRING as isize,
98    /// Numeric data (integers, floats, dates, times).
99    Numeric = readstat_sys::readstat_type_class_e_READSTAT_TYPE_CLASS_NUMERIC as isize,
100}
readstat/rs_var.rs

readstat/
rs_var.rs
