Skip to main content

parquet_variant/
variant.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: See the NOTICE file distributed with this work for additional information regarding copyright ownership
3// SPDX-FileContributor: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements
4
5pub use self::decimal::{VariantDecimal4, VariantDecimal8, VariantDecimal16, VariantDecimalType};
6pub use self::list::VariantList;
7pub use self::metadata::{
8    EMPTY_VARIANT_METADATA, EMPTY_VARIANT_METADATA_BYTES, VARIANT_SPEC_VERSION, VariantMetadata,
9};
10pub use self::object::VariantObject;
11
12// Publicly export types used in the API
13pub use half::f16;
14pub use uuid::Uuid;
15
16use crate::decoder::{
17    self, VariantBasicType, VariantPrimitiveType, get_basic_type, get_primitive_type,
18};
19use crate::path::{VariantPath, VariantPathElement};
20use crate::utils::{first_byte_from_slice, slice_from_slice};
21use std::ops::Deref;
22
23use arrow_schema::ArrowError;
24use chrono::{DateTime, NaiveDate, NaiveDateTime, NaiveTime, Timelike, Utc};
25
26mod decimal;
27mod list;
28mod metadata;
29mod object;
30
31const MAX_SHORT_STRING_BYTES: usize = 0x3F;
32
33/// The maximum number of nested objects and arrays a [`Variant`] may contain.
34///
35/// Full [validation] recurses into nested values, so unbounded nesting would overflow the stack --
36/// an abort, not a catchable panic. Validation therefore rejects more deeply nested values, which
37/// also bounds the recursion of infallible accesses such as [`Debug`] and [`PartialEq`].
38///
39/// The variant [spec] does not specify a limit. This value matches the default `serde_json`
40/// recursion limit, so any variant parsed from JSON already satisfies it.
41///
42/// [validation]: Variant#Validation
43/// [spec]: https://github.com/apache/parquet-format/blob/master/VariantEncoding.md
44pub const MAX_NESTING_DEPTH: usize = 128;
45
46/// A Variant [`ShortString`]
47///
48/// This implementation is a zero cost wrapper over `&str` that ensures
49/// the length of the underlying string is a valid Variant short string (63 bytes or less)
50#[derive(Debug, Clone, Copy, PartialEq)]
51pub struct ShortString<'a>(pub(crate) &'a str);
52
53impl<'a> ShortString<'a> {
54    /// Attempts to interpret `value` as a variant short string value.
55    ///
56    /// # Errors
57    ///
58    /// Returns an error if  `value` is longer than the maximum allowed length
59    /// of a Variant short string (63 bytes).
60    pub fn try_new(value: &'a str) -> Result<Self, ArrowError> {
61        if value.len() > MAX_SHORT_STRING_BYTES {
62            return Err(ArrowError::InvalidArgumentError(format!(
63                "value is larger than {MAX_SHORT_STRING_BYTES} bytes"
64            )));
65        }
66
67        Ok(Self(value))
68    }
69
70    /// Returns the underlying Variant short string as a &str
71    pub fn as_str(&self) -> &'a str {
72        self.0
73    }
74}
75
76impl<'a> From<ShortString<'a>> for &'a str {
77    fn from(value: ShortString<'a>) -> Self {
78        value.0
79    }
80}
81
82impl<'a> TryFrom<&'a str> for ShortString<'a> {
83    type Error = ArrowError;
84
85    fn try_from(value: &'a str) -> Result<Self, Self::Error> {
86        Self::try_new(value)
87    }
88}
89
90impl AsRef<str> for ShortString<'_> {
91    fn as_ref(&self) -> &str {
92        self.0
93    }
94}
95
96impl Deref for ShortString<'_> {
97    type Target = str;
98
99    fn deref(&self) -> &Self::Target {
100        self.0
101    }
102}
103
104/// Represents a [Parquet Variant]
105///
106/// The lifetimes `'m` and `'v` are for metadata and value buffers, respectively.
107///
108/// # Background
109///
110/// The [specification] says:
111///
112/// The Variant Binary Encoding allows representation of semi-structured data
113/// (e.g. JSON) in a form that can be efficiently queried by path. The design is
114/// intended to allow efficient access to nested data even in the presence of
115/// very wide or deep structures.
116///
117/// Another motivation for the representation is that (aside from metadata) each
118/// nested Variant value is contiguous and self-contained. For example, in a
119/// Variant containing an Array of Variant values, the representation of an
120/// inner Variant value, when paired with the metadata of the full variant, is
121/// itself a valid Variant.
122///
123/// When stored in Parquet files, Variant fields can also be *shredded*. Shredding
124/// refers to extracting some elements of the variant into separate columns for
125/// more efficient extraction/filter pushdown. The [Variant Shredding
126/// specification] describes the details of shredding Variant values as typed
127/// Parquet columns.
128///
129/// A Variant represents a type that contains one of:
130///
131/// * Primitive: A type and corresponding value (e.g. INT, STRING)
132///
133/// * Array: An ordered list of Variant values
134///
135/// * Object: An unordered collection of string/Variant pairs (i.e. key/value
136///   pairs). An object may not contain duplicate keys.
137///
138/// # Encoding
139///
140/// A Variant is encoded with 2 binary values, the value and the metadata. The
141/// metadata stores a header and an optional dictionary of field names which are
142/// referred to by offset in the value. The value is a binary representation of
143/// the actual data, and varies depending on the type.
144///
145/// # Design Goals
146///
147/// The design goals of the Rust API are as follows:
148/// 1. Speed / Zero copy access (no `clone`ing is required)
149/// 2. Safety
150/// 3. Follow standard Rust conventions
151///
152/// [Parquet Variant]: https://github.com/apache/parquet-format/blob/master/VariantEncoding.md
153/// [specification]: https://github.com/apache/parquet-format/blob/master/VariantEncoding.md
154/// [Variant Shredding specification]: https://github.com/apache/parquet-format/blob/master/VariantShredding.md
155///
156/// # Examples:
157///
158/// ## Creating `Variant` from Rust Types
159/// ```
160/// use parquet_variant::Variant;
161/// // variants can be directly constructed
162/// let variant = Variant::Int32(123);
163/// // or constructed via `From` impls
164/// assert_eq!(variant, Variant::from(123i32));
165/// ```
166/// ## Creating `Variant` from metadata and value
167/// ```
168/// # use parquet_variant::{Variant, VariantMetadata};
169/// let metadata = [0x01, 0x00, 0x00];
170/// let value = [0x09, 0x48, 0x49];
171/// // parse the header metadata
172/// assert_eq!(
173///   Variant::from("HI"),
174///   Variant::new(&metadata, &value)
175/// );
176/// ```
177///
178/// ## Using `Variant` values
179/// ```
180/// # use parquet_variant::Variant;
181/// # let variant = Variant::Int32(123);
182/// // variants can be used in match statements like normal enums
183/// match variant {
184///   Variant::Int32(i) => println!("Integer: {}", i),
185///   Variant::String(s) => println!("String: {}", s),
186///   _ => println!("Other variant"),
187/// }
188/// ```
189///
190/// # Validation
191///
192/// Every instance of variant is either _valid_ or _invalid_. depending on whether the
193/// underlying bytes are a valid encoding of a variant value (see below).
194///
195/// Instances produced by [`Self::try_new`], [`Self::try_new_with_metadata`], or [`Self::with_full_validation`]
196/// are fully _validated_. They always contain _valid_ data, and infallible accesses such as
197/// iteration and indexing are panic-free. The validation cost is `O(m + v)` where `m` and
198/// `v` are the number of bytes in the metadata and value buffers, respectively.
199///
200/// Instances produced by [`Self::new`] and [`Self::new_with_metadata`] are _unvalidated_ and so
201/// they may contain either _valid_ or _invalid_ data. Infallible accesses to variant objects and
202/// arrays, such as iteration and indexing will panic if the underlying bytes are _invalid_, and
203/// fallible alternatives are provided as panic-free alternatives. [`Self::with_full_validation`] can also be
204/// used to _validate_ an _unvalidated_ instance, if desired.
205///
206/// _Unvalidated_ instances can be constructed in constant time. This can be useful if the caller
207/// knows the underlying bytes were already validated previously, or if the caller intends to
208/// perform a small number of (fallible) accesses to a large variant value.
209///
210/// A _validated_ variant value guarantees that the associated [metadata] and all nested [object]
211/// and [array] values are _valid_. Primitive variant subtypes are always _valid_ by construction.
212///
213/// # Safety
214///
215/// Even an _invalid_ variant value is still _safe_ to use in the Rust sense. Accessing it with
216/// infallible methods may cause panics but will never lead to undefined behavior.
217///
218/// [metadata]: VariantMetadata#Validation
219/// [object]: VariantObject#Validation
220/// [array]: VariantList#Validation
221#[derive(Clone, PartialEq)]
222pub enum Variant<'m, 'v> {
223    /// Primitive type: Null
224    Null,
225    /// Primitive (type_id=1): INT(8, SIGNED)
226    Int8(i8),
227    /// Primitive (type_id=1): INT(16, SIGNED)
228    Int16(i16),
229    /// Primitive (type_id=1): INT(32, SIGNED)
230    Int32(i32),
231    /// Primitive (type_id=1): INT(64, SIGNED)
232    Int64(i64),
233    /// Primitive (type_id=1): DATE
234    Date(NaiveDate),
235    /// Primitive (type_id=1): TIMESTAMP(isAdjustedToUTC=true, MICROS)
236    TimestampMicros(DateTime<Utc>),
237    /// Primitive (type_id=1): TIMESTAMP(isAdjustedToUTC=false, MICROS)
238    TimestampNtzMicros(NaiveDateTime),
239    /// Primitive (type_id=1): TIMESTAMP(isAdjustedToUTC=true, NANOS)
240    TimestampNanos(DateTime<Utc>),
241    /// Primitive (type_id=1): TIMESTAMP(isAdjustedToUTC=false, NANOS)
242    TimestampNtzNanos(NaiveDateTime),
243    /// Primitive (type_id=1): DECIMAL(precision, scale) 32-bits
244    Decimal4(VariantDecimal4),
245    /// Primitive (type_id=1): DECIMAL(precision, scale) 64-bits
246    Decimal8(VariantDecimal8),
247    /// Primitive (type_id=1): DECIMAL(precision, scale) 128-bits
248    Decimal16(VariantDecimal16),
249    /// Primitive (type_id=1): FLOAT
250    Float(f32),
251    /// Primitive (type_id=1): DOUBLE
252    Double(f64),
253    /// Primitive (type_id=1): BOOLEAN (true)
254    BooleanTrue,
255    /// Primitive (type_id=1): BOOLEAN (false)
256    BooleanFalse,
257    // Note: only need the *value* buffer for these types
258    /// Primitive (type_id=1): BINARY
259    Binary(&'v [u8]),
260    /// Primitive (type_id=1): STRING
261    String(&'v str),
262    /// Primitive (type_id=1): TIME(isAdjustedToUTC=false, MICROS)
263    Time(NaiveTime),
264    /// Primitive (type_id=1): UUID
265    Uuid(Uuid),
266    /// Short String (type_id=2): STRING
267    ShortString(ShortString<'v>),
268    // need both metadata & value
269    /// Object (type_id=3): N/A
270    Object(VariantObject<'m, 'v>),
271    /// Array (type_id=4): N/A
272    List(VariantList<'m, 'v>),
273}
274
275// We don't want this to grow because it could hurt performance of a frequently-created type.
276#[cfg(all(target_pointer_width = "64", target_arch = "s390x"))]
277const _: () = crate::utils::expect_size_of::<Variant>(72);
278#[cfg(all(target_pointer_width = "64", not(target_arch = "s390x")))]
279const _: () = crate::utils::expect_size_of::<Variant>(80);
280#[cfg(target_pointer_width = "32")]
281const _: () = crate::utils::expect_size_of::<Variant>(48);
282
283impl<'m, 'v> Variant<'m, 'v> {
284    /// Attempts to interpret a metadata and value buffer pair as a new `Variant`.
285    ///
286    /// The instance is fully [validated].
287    ///
288    /// # Example
289    /// ```
290    /// use parquet_variant::{Variant, VariantMetadata};
291    /// let metadata = [0x01, 0x00, 0x00];
292    /// let value = [0x09, 0x48, 0x49];
293    /// // parse the header metadata
294    /// assert_eq!(
295    ///   Variant::from("HI"),
296    ///   Variant::try_new(&metadata, &value).unwrap()
297    /// );
298    /// ```
299    ///
300    /// [validated]: Self#Validation
301    pub fn try_new(metadata: &'m [u8], value: &'v [u8]) -> Result<Self, ArrowError> {
302        let metadata = VariantMetadata::try_new(metadata)?;
303        Self::try_new_with_metadata(metadata, value)
304    }
305
306    /// Attempts to interpret a metadata and value buffer pair as a new `Variant`.
307    ///
308    /// The instance is [unvalidated].
309    ///
310    /// # Example
311    /// ```
312    /// use parquet_variant::{Variant, VariantMetadata};
313    /// let metadata = [0x01, 0x00, 0x00];
314    /// let value = [0x09, 0x48, 0x49];
315    /// // parse the header metadata
316    /// assert_eq!(
317    ///   Variant::from("HI"),
318    ///   Variant::new(&metadata, &value)
319    /// );
320    /// ```
321    ///
322    /// [unvalidated]: Self#Validation
323    ///
324    /// # Panics
325    ///
326    /// Panics if `metadata` or `value` fail basic validation. Use [`Self::try_new`]
327    /// for a fallible version.
328    pub fn new(metadata: &'m [u8], value: &'v [u8]) -> Self {
329        let metadata = VariantMetadata::try_new_with_shallow_validation(metadata)
330            .expect("Invalid variant metadata");
331        Self::try_new_with_metadata_and_shallow_validation(metadata, value)
332            .expect("Invalid variant data")
333    }
334
335    /// Create a new variant with existing metadata.
336    ///
337    /// The instance is fully [validated].
338    ///
339    /// # Example
340    /// ```
341    /// # use parquet_variant::{Variant, VariantMetadata};
342    /// let metadata = [0x01, 0x00, 0x00];
343    /// let value = [0x09, 0x48, 0x49];
344    /// // parse the header metadata first
345    /// let metadata = VariantMetadata::new(&metadata);
346    /// assert_eq!(
347    ///   Variant::from("HI"),
348    ///   Variant::try_new_with_metadata(metadata, &value).unwrap()
349    /// );
350    /// ```
351    ///
352    /// [validated]: Self#Validation
353    pub fn try_new_with_metadata(
354        metadata: VariantMetadata<'m>,
355        value: &'v [u8],
356    ) -> Result<Self, ArrowError> {
357        Self::try_new_with_metadata_at_depth(metadata, value, 0)
358    }
359
360    // Same as [`Self::try_new_with_metadata`], tracking how deeply validation has recursed.
361    pub(crate) fn try_new_with_metadata_at_depth(
362        metadata: VariantMetadata<'m>,
363        value: &'v [u8],
364        depth: usize,
365    ) -> Result<Self, ArrowError> {
366        Self::try_new_with_metadata_and_shallow_validation(metadata, value)?
367            .with_full_validation_at_depth(depth)
368    }
369
370    /// Similar to [`Self::try_new_with_metadata`], but [unvalidated].
371    ///
372    /// [unvalidated]: Self#Validation
373    ///
374    /// # Panics
375    ///
376    /// Panics if `value` fails basic validation. Use [`Self::try_new_with_metadata`]
377    /// for a fallible version.
378    pub fn new_with_metadata(metadata: VariantMetadata<'m>, value: &'v [u8]) -> Self {
379        Self::try_new_with_metadata_and_shallow_validation(metadata, value)
380            .expect("Invalid variant")
381    }
382
383    // The actual constructor, which only performs shallow (constant-time) validation.
384    fn try_new_with_metadata_and_shallow_validation(
385        metadata: VariantMetadata<'m>,
386        value: &'v [u8],
387    ) -> Result<Self, ArrowError> {
388        let value_metadata = first_byte_from_slice(value)?;
389        let value_data = slice_from_slice(value, 1..)?;
390        let new_self = match get_basic_type(value_metadata) {
391            VariantBasicType::Primitive => match get_primitive_type(value_metadata)? {
392                VariantPrimitiveType::Null => Variant::Null,
393                VariantPrimitiveType::Int8 => Variant::Int8(decoder::decode_int8(value_data)?),
394                VariantPrimitiveType::Int16 => Variant::Int16(decoder::decode_int16(value_data)?),
395                VariantPrimitiveType::Int32 => Variant::Int32(decoder::decode_int32(value_data)?),
396                VariantPrimitiveType::Int64 => Variant::Int64(decoder::decode_int64(value_data)?),
397                VariantPrimitiveType::Decimal4 => {
398                    let (integer, scale) = decoder::decode_decimal4(value_data)?;
399                    Variant::Decimal4(VariantDecimal4::try_new(integer, scale)?)
400                }
401                VariantPrimitiveType::Decimal8 => {
402                    let (integer, scale) = decoder::decode_decimal8(value_data)?;
403                    Variant::Decimal8(VariantDecimal8::try_new(integer, scale)?)
404                }
405                VariantPrimitiveType::Decimal16 => {
406                    let (integer, scale) = decoder::decode_decimal16(value_data)?;
407                    Variant::Decimal16(VariantDecimal16::try_new(integer, scale)?)
408                }
409                VariantPrimitiveType::Float => Variant::Float(decoder::decode_float(value_data)?),
410                VariantPrimitiveType::Double => {
411                    Variant::Double(decoder::decode_double(value_data)?)
412                }
413                VariantPrimitiveType::BooleanTrue => Variant::BooleanTrue,
414                VariantPrimitiveType::BooleanFalse => Variant::BooleanFalse,
415                VariantPrimitiveType::Date => Variant::Date(decoder::decode_date(value_data)?),
416                VariantPrimitiveType::TimestampMicros => {
417                    Variant::TimestampMicros(decoder::decode_timestamp_micros(value_data)?)
418                }
419                VariantPrimitiveType::TimestampNtzMicros => {
420                    Variant::TimestampNtzMicros(decoder::decode_timestampntz_micros(value_data)?)
421                }
422                VariantPrimitiveType::TimestampNanos => {
423                    Variant::TimestampNanos(decoder::decode_timestamp_nanos(value_data)?)
424                }
425                VariantPrimitiveType::TimestampNtzNanos => {
426                    Variant::TimestampNtzNanos(decoder::decode_timestampntz_nanos(value_data)?)
427                }
428                VariantPrimitiveType::Uuid => Variant::Uuid(decoder::decode_uuid(value_data)?),
429                VariantPrimitiveType::Binary => {
430                    Variant::Binary(decoder::decode_binary(value_data)?)
431                }
432                VariantPrimitiveType::String => {
433                    Variant::String(decoder::decode_long_string(value_data)?)
434                }
435                VariantPrimitiveType::Time => Variant::Time(decoder::decode_time_ntz(value_data)?),
436            },
437            VariantBasicType::ShortString => {
438                Variant::ShortString(decoder::decode_short_string(value_metadata, value_data)?)
439            }
440            VariantBasicType::Object => Variant::Object(
441                VariantObject::try_new_with_shallow_validation(metadata, value)?,
442            ),
443            VariantBasicType::Array => Variant::List(VariantList::try_new_with_shallow_validation(
444                metadata, value,
445            )?),
446        };
447        Ok(new_self)
448    }
449
450    /// True if this variant instance has already been [validated].
451    ///
452    /// [validated]: Self#Validation
453    pub fn is_fully_validated(&self) -> bool {
454        match self {
455            Variant::List(list) => list.is_fully_validated(),
456            Variant::Object(obj) => obj.is_fully_validated(),
457            _ => true,
458        }
459    }
460
461    /// Recursively validates this variant value, ensuring that infallible access will not panic due
462    /// to invalid bytes.
463    ///
464    /// Variant leaf values are always valid by construction, but [objects] and [arrays] can be
465    /// constructed in unvalidated (and potentially invalid) state.
466    ///
467    /// If [`Self::is_fully_validated`] is true, validation is a no-op. Otherwise, the cost is `O(m + v)`
468    /// where `m` and `v` are the sizes of metadata and value buffers, respectively.
469    ///
470    /// Values nested more than [`MAX_NESTING_DEPTH`] deep are rejected.
471    ///
472    /// [objects]: VariantObject#Validation
473    /// [arrays]: VariantList#Validation
474    pub fn with_full_validation(self) -> Result<Self, ArrowError> {
475        self.with_full_validation_at_depth(0)
476    }
477
478    // Same as [`Self::with_full_validation`], tracking how deeply validation has recursed.
479    pub(crate) fn with_full_validation_at_depth(self, depth: usize) -> Result<Self, ArrowError> {
480        use Variant::*;
481        match self {
482            List(list) => list.with_full_validation_at_depth(depth).map(List),
483            Object(obj) => obj.with_full_validation_at_depth(depth).map(Object),
484            _ => Ok(self),
485        }
486    }
487
488    /// Converts this variant to `()` if it is null.
489    ///
490    /// Returns `Some(())` for null variants,
491    /// `None` for non-null variants.
492    ///
493    /// # Examples
494    ///
495    /// ```
496    /// use parquet_variant::Variant;
497    ///
498    /// // you can extract `()` from a null variant
499    /// let v1 = Variant::from(());
500    /// assert_eq!(v1.as_null(), Some(()));
501    ///
502    /// // but not from other variants
503    /// let v2 = Variant::from("hello!");
504    /// assert_eq!(v2.as_null(), None);
505    /// ```
506    pub fn as_null(&self) -> Option<()> {
507        matches!(self, Variant::Null).then_some(())
508    }
509
510    /// Converts this variant to a `bool` if possible.
511    ///
512    /// Returns `Some(bool)` for boolean variants,
513    /// `None` for non-boolean variants.
514    ///
515    /// # Examples
516    ///
517    /// ```
518    /// use parquet_variant::Variant;
519    ///
520    /// // you can extract a bool from the true variant
521    /// let v1 = Variant::from(true);
522    /// assert_eq!(v1.as_boolean(), Some(true));
523    ///
524    /// // and the false variant
525    /// let v2 = Variant::from(false);
526    /// assert_eq!(v2.as_boolean(), Some(false));
527    ///
528    /// // but not from other variants
529    /// let v3 = Variant::from("hello!");
530    /// assert_eq!(v3.as_boolean(), None);
531    /// ```
532    pub fn as_boolean(&self) -> Option<bool> {
533        match self {
534            Variant::BooleanTrue => Some(true),
535            Variant::BooleanFalse => Some(false),
536            _ => None,
537        }
538    }
539
540    /// Converts this variant to a `NaiveDate` if possible.
541    ///
542    /// Returns `Some(NaiveDate)` for date variants,
543    /// `None` for non-date variants.
544    ///
545    /// # Examples
546    ///
547    /// ```
548    /// use parquet_variant::Variant;
549    /// use chrono::NaiveDate;
550    ///
551    /// // you can extract a NaiveDate from a date variant
552    /// let date = NaiveDate::from_ymd_opt(2025, 4, 12).unwrap();
553    /// let v1 = Variant::from(date);
554    /// assert_eq!(v1.as_naive_date(), Some(date));
555    ///
556    /// // but not from other variants
557    /// let v2 = Variant::from("hello!");
558    /// assert_eq!(v2.as_naive_date(), None);
559    /// ```
560    pub fn as_naive_date(&self) -> Option<NaiveDate> {
561        if let Variant::Date(d) = self {
562            Some(*d)
563        } else {
564            None
565        }
566    }
567
568    /// Converts this variant to a `DateTime<Utc>` if possible.
569    ///
570    /// Returns `Some(DateTime<Utc>)` for timestamp(micro&nano) variants if fits in the range,
571    /// `None` for other variants or the value can't fit in the micro second range.
572    ///
573    /// # Examples
574    ///
575    /// ```
576    /// use parquet_variant::Variant;
577    /// use chrono::NaiveDate;
578    ///
579    /// // you can extract a DateTime<Utc> from a UTC-adjusted variant
580    /// let datetime = NaiveDate::from_ymd_opt(2025, 4, 16)
581    ///     .unwrap()
582    ///     .and_hms_milli_opt(12, 34, 56, 780)
583    ///     .unwrap()
584    ///     .and_utc();
585    /// let v1 = Variant::from(datetime);
586    /// assert_eq!(v1.as_timestamp_micros(), Some(datetime));
587    ///
588    /// // or from a timestamp nano variant that can fit into micro second range.
589    /// let datetime_nanos = NaiveDate::from_ymd_opt(2026, 7, 15)
590    /// .unwrap()
591    /// .and_hms_nano_opt(12, 34, 56, 123456000)
592    /// .unwrap()
593    /// .and_utc();
594    /// // construct the variant directly, because variant::from will treat this into a timestamp micro variant
595    /// let v2 = Variant::TimestampNanos(datetime_nanos);
596    /// assert_eq!(v2.as_timestamp_micros(), Some(datetime_nanos));
597    ///
598    /// // but not for a non-microsecond-aligned nanosecond variant
599    /// let datetime_nanos = NaiveDate::from_ymd_opt(2025, 8, 14)
600    ///     .unwrap()
601    ///     .and_hms_nano_opt(12, 33, 54, 123456789)
602    ///     .unwrap()
603    ///     .and_utc();
604    /// let v3 = Variant::from(datetime_nanos);
605    /// assert_eq!(v3.as_timestamp_micros(), None);
606    ///
607    /// // or from other variant
608    /// let v4 = Variant::from("hello");
609    /// assert_eq!(v4.as_timestamp_micros(), None);
610    /// ```
611    pub fn as_timestamp_micros(&self) -> Option<DateTime<Utc>> {
612        match *self {
613            Variant::TimestampMicros(d) => Some(d),
614            Variant::TimestampNanos(d) if d.nanosecond() % 1_000 == 0 => Some(d),
615            _ => None,
616        }
617    }
618
619    /// Converts this variant to a `NaiveDateTime` if possible.
620    ///
621    /// Returns `Some(NaiveDateTime)` for [`Variant::TimestampNtzMicros`] variants,
622    /// `None` for other variants.
623    ///
624    /// # Examples
625    ///
626    /// ```
627    /// use parquet_variant::Variant;
628    /// use chrono::NaiveDate;
629    ///
630    /// // you can extract a NaiveDateTime from a non-UTC-adjusted variant
631    /// let datetime = NaiveDate::from_ymd_opt(2025, 4, 16)
632    ///     .unwrap()
633    ///     .and_hms_milli_opt(12, 34, 56, 780)
634    ///     .unwrap();
635    /// let v1 = Variant::from(datetime);
636    /// assert_eq!(v1.as_timestamp_ntz_micros(), Some(datetime));
637    ///
638    /// // or from a non-UTC-adjusted timestamp nano variant that can fit into microsecond range
639    /// let datetime_nanos = NaiveDate::from_ymd_opt(2026, 7, 15)
640    /// .unwrap()
641    /// .and_hms_nano_opt(12, 34, 56, 123456000)
642    /// .unwrap();
643    /// // construct the variant directly, because variant::from will treat this into a timestamp variant
644    /// let v2 = Variant::TimestampNtzNanos(datetime_nanos);
645    /// assert_eq!(v2.as_timestamp_ntz_micros(), Some(datetime_nanos));
646    ///
647    /// // but not for a non-microsecond-aligned nanosecond variant.
648    /// let datetime_nanos = NaiveDate::from_ymd_opt(2025, 8, 14)
649    ///     .unwrap()
650    ///     .and_hms_nano_opt(12, 33, 54, 123456789)
651    ///     .unwrap();
652    /// let v3 = Variant::from(datetime_nanos);
653    /// assert_eq!(v3.as_timestamp_ntz_micros(), None);
654    ///
655    /// // or other variant
656    /// let v4 = Variant::from("hello");
657    /// assert_eq!(v4.as_timestamp_ntz_micros(), None);
658    /// ```
659    pub fn as_timestamp_ntz_micros(&self) -> Option<NaiveDateTime> {
660        match *self {
661            Variant::TimestampNtzMicros(d) => Some(d),
662            Variant::TimestampNtzNanos(d) if d.nanosecond() % 1000 == 0 => Some(d),
663            _ => None,
664        }
665    }
666
667    /// Converts this variant to a `DateTime<Utc>` if possible.
668    ///
669    /// Returns `Some(DateTime<Utc>)` for timestamp variants,
670    /// `None` for other variants.
671    ///
672    /// # Examples
673    ///
674    /// ```
675    /// use parquet_variant::Variant;
676    /// use chrono::NaiveDate;
677    ///
678    /// // you can extract a DateTime<Utc> from a UTC-adjusted nanosecond-precision variant
679    /// let datetime = NaiveDate::from_ymd_opt(2025, 4, 16)
680    ///     .unwrap()
681    ///     .and_hms_nano_opt(12, 34, 56, 789123456)
682    ///     .unwrap()
683    ///     .and_utc();
684    /// let v1 = Variant::from(datetime);
685    /// assert_eq!(v1.as_timestamp_nanos(), Some(datetime));
686    ///
687    /// // or from UTC-adjusted microsecond-precision variant
688    /// let datetime_micros = NaiveDate::from_ymd_opt(2025, 8, 14)
689    ///     .unwrap()
690    ///     .and_hms_milli_opt(12, 33, 54, 123)
691    ///     .unwrap()
692    ///     .and_utc();
693    /// // this will convert to `Variant::TimestampMicros`.
694    /// let v2 = Variant::from(datetime_micros);
695    /// assert_eq!(v2.as_timestamp_nanos(), Some(datetime_micros));
696    ///
697    /// // but not for other variants.
698    /// let v3 = Variant::from("hello!");
699    /// assert_eq!(v3.as_timestamp_nanos(), None);
700    /// ```
701    pub fn as_timestamp_nanos(&self) -> Option<DateTime<Utc>> {
702        match *self {
703            Variant::TimestampNanos(d) | Variant::TimestampMicros(d) => Some(d),
704            _ => None,
705        }
706    }
707
708    /// Converts this variant to a `NaiveDateTime` if possible.
709    ///
710    /// Returns `Some(NaiveDateTime)` for timestamp variants,
711    /// `None` for other variants.
712    ///
713    /// # Examples
714    ///
715    /// ```
716    /// use parquet_variant::Variant;
717    /// use chrono::NaiveDate;
718    ///
719    /// // you can extract a NaiveDateTime from a non-UTC-adjusted variant
720    /// let datetime = NaiveDate::from_ymd_opt(2025, 4, 16)
721    ///     .unwrap()
722    ///     .and_hms_nano_opt(12, 34, 56, 789123456)
723    ///     .unwrap();
724    /// let v1 = Variant::from(datetime);
725    /// assert_eq!(v1.as_timestamp_ntz_nanos(), Some(datetime));
726    ///
727    /// // or from a microsecond-precision non-UTC-adjusted variant
728    /// let datetime_micros = NaiveDate::from_ymd_opt(2025, 8, 14)
729    ///     .unwrap()
730    ///     .and_hms_milli_opt(12, 33, 54, 123)
731    ///     .unwrap();
732    /// // this will convert to `Variant::TimestampMicros`.
733    /// let v2 = Variant::from(datetime_micros);
734    /// assert_eq!(v2.as_timestamp_ntz_nanos(), Some(datetime_micros));
735    ///
736    /// // but not for other variants.
737    /// let v3 = Variant::from("hello!");
738    /// assert_eq!(v3.as_timestamp_ntz_nanos(), None);
739    /// ```
740    pub fn as_timestamp_ntz_nanos(&self) -> Option<NaiveDateTime> {
741        match *self {
742            Variant::TimestampNtzNanos(d) | Variant::TimestampNtzMicros(d) => Some(d),
743            _ => None,
744        }
745    }
746
747    /// Converts this variant to a `&[u8]` if possible.
748    ///
749    /// Returns `Some(&[u8])` for binary variants,
750    /// `None` for non-binary variants.
751    ///
752    /// # Examples
753    ///
754    /// ```
755    /// use parquet_variant::Variant;
756    ///
757    /// // you can extract a byte slice from a binary variant
758    /// let data = b"hello!";
759    /// let v1 = Variant::Binary(data);
760    /// assert_eq!(v1.as_u8_slice(), Some(data.as_slice()));
761    ///
762    /// // but not from other variant types
763    /// let v2 = Variant::from(123i64);
764    /// assert_eq!(v2.as_u8_slice(), None);
765    /// ```
766    pub fn as_u8_slice(&'v self) -> Option<&'v [u8]> {
767        if let Variant::Binary(d) = self {
768            Some(d)
769        } else {
770            None
771        }
772    }
773
774    /// Converts this variant to a `&str` if possible.
775    ///
776    /// Returns `Some(&str)` for string variants (both regular and short strings),
777    /// `None` for non-string variants.
778    ///
779    /// # Examples
780    ///
781    /// ```
782    /// use parquet_variant::Variant;
783    ///
784    /// // you can extract a string from string variants
785    /// let s = "hello!";
786    /// let v1 = Variant::from(s);
787    /// assert_eq!(v1.as_string(), Some(s));
788    ///
789    /// // but not from other variants
790    /// let v2 = Variant::from(123i64);
791    /// assert_eq!(v2.as_string(), None);
792    /// ```
793    pub fn as_string(&'v self) -> Option<&'v str> {
794        match self {
795            Variant::String(s) | Variant::ShortString(ShortString(s)) => Some(s),
796            _ => None,
797        }
798    }
799
800    /// Converts this variant to a `uuid hyphenated string` if possible.
801    ///
802    /// Returns `Some(String)` for UUID variants, `None` for non-UUID variants.
803    ///
804    /// # Examples
805    ///
806    /// ```
807    /// use parquet_variant::Variant;
808    ///
809    /// // You can extract a UUID from a UUID variant
810    /// let s = uuid::Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap();
811    /// let v1 = Variant::Uuid(s);
812    /// assert_eq!(s, v1.as_uuid().unwrap());
813    /// assert_eq!("67e55044-10b1-426f-9247-bb680e5fe0c8", v1.as_uuid().unwrap().to_string());
814    ///
815    /// //but not from other variants
816    /// let v2 = Variant::from(1234);
817    /// assert_eq!(None, v2.as_uuid())
818    /// ```
819    pub fn as_uuid(&self) -> Option<Uuid> {
820        match self {
821            Variant::Uuid(u) => Some(*u),
822            _ => None,
823        }
824    }
825
826    /// Converts this variant to an `i8` if possible.
827    ///
828    /// Returns `Some(i8)` for int variants, decimal variants has no fractional part
829    /// (scale = 0, or unscaled integer is divisible by 10^scale) that fits in `i8` range.
830    /// `None` for other variants or values that would overflow.
831    /// # Examples
832    ///
833    /// ```
834    /// use parquet_variant::{Variant, VariantDecimal4};
835    ///
836    /// // you can read an int64 variant into an i8 if it fits
837    /// let v1 = Variant::from(123i64);
838    /// assert_eq!(v1.as_int8(), Some(123i8));
839    ///
840    /// // or from a decimal variant with scale = 0 that fits in i8 range
841    /// let d = VariantDecimal4::try_new(123, 0).unwrap();
842    /// let v2 = Variant::from(d);
843    /// assert_eq!(v2.as_int8(), Some(123i8));
844    ///
845    /// // or from a decimal variant that unscaled value is divisible by 10^scale
846    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
847    /// let v3 = Variant::from(d);
848    /// assert_eq!(v3.as_int8(), Some(1i8));
849    ///
850    /// // but not if it would overflow
851    /// let d = VariantDecimal4::try_new(1234i32, 0).unwrap();
852    /// let v4 = Variant::from(d);
853    /// assert_eq!(v4.as_int8(), None);
854    ///
855    /// // or if the variant cannot be cast into an integer
856    /// let v5 = Variant::from("hello");
857    /// assert_eq!(v5.as_int8(), None);
858    /// ```
859    pub fn as_int8(&self) -> Option<i8> {
860        match *self {
861            Variant::Int8(i) => Some(i),
862            Variant::Int16(i) => i.try_into().ok(),
863            Variant::Int32(i) => i.try_into().ok(),
864            Variant::Int64(i) => i.try_into().ok(),
865            Variant::Decimal4(d) => d.as_integer()?.try_into().ok(),
866            Variant::Decimal8(d) => d.as_integer()?.try_into().ok(),
867            Variant::Decimal16(d) => d.as_integer()?.try_into().ok(),
868            _ => None,
869        }
870    }
871
872    /// Converts this variant to an `i16` if possible.
873    ///
874    /// Returns `Some(i16)` for int variant, decimal variant has no fractional part
875    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `i16` range.
876    /// `None` for other variants or values that would overflow.
877    ///
878    /// # Examples
879    ///
880    /// ```
881    /// use parquet_variant::{Variant, VariantDecimal4};
882    ///
883    /// // you can read an int64 variant into an i16 if it fits
884    /// let v1 = Variant::from(123i64);
885    /// assert_eq!(v1.as_int16(), Some(123i16));
886    ///
887    /// // or from a decimal variant that scale = 0
888    /// let d = VariantDecimal4::try_new(123, 0).unwrap();
889    /// let v2 = Variant::from(d);
890    /// assert_eq!(v2.as_int16(), Some(123i16));
891    ///
892    /// // or from a decimal variant that unscaled value is divisible by 10^scale
893    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
894    /// let v3 = Variant::from(d);
895    /// assert_eq!(v3.as_int16(), Some(1i16));
896    ///
897    /// // but not if it would overflow
898    /// let d = VariantDecimal4::try_new(123456i32, 0).unwrap();
899    /// let v4 = Variant::from(d);
900    /// assert_eq!(v4.as_int16(), None);
901    ///
902    /// // or if the variant cannot be cast into an integer
903    /// let v5 = Variant::from("hello");
904    /// assert_eq!(v5.as_int16(), None);
905    /// ```
906    pub fn as_int16(&self) -> Option<i16> {
907        match *self {
908            Variant::Int8(i) => Some(i as i16),
909            Variant::Int16(i) => Some(i),
910            Variant::Int32(i) => i.try_into().ok(),
911            Variant::Int64(i) => i.try_into().ok(),
912            Variant::Decimal4(d) => d.as_integer()?.try_into().ok(),
913            Variant::Decimal8(d) => d.as_integer()?.try_into().ok(),
914            Variant::Decimal16(d) => d.as_integer()?.try_into().ok(),
915            _ => None,
916        }
917    }
918
919    /// Converts this variant to an `i32` if possible.
920    ///
921    /// Returns `Some(i32)` for int variant, decimal variant has no fractional part
922    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `i32` range.
923    /// `None` for other variants or values that would overflow.
924    /// # Examples
925    ///
926    /// ```
927    /// use parquet_variant::{Variant, VariantDecimal4, VariantDecimal8};
928    ///
929    /// // you can read an int32 variant into an i32
930    /// let v1 = Variant::from(123i32);
931    /// assert_eq!(v1.as_int32(), Some(123i32));
932    ///
933    /// // or from an int64 if it fits
934    /// let v2 = Variant::from(1231i64);
935    /// assert_eq!(v2.as_int32(), Some(1231i32));
936    ///
937    /// // or from decimal variant that scale=0
938    /// let d = VariantDecimal4::try_new(123, 0).unwrap();
939    /// let v4 = Variant::from(d);
940    /// assert_eq!(v4.as_int32(), Some(123i32));
941    ///
942    /// // or from a decimal variant that unscaled value is divisible by 10^scale
943    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
944    /// let v3 = Variant::from(d);
945    /// assert_eq!(v3.as_int32(), Some(1i32));
946    ///
947    /// // but not if it would overflow
948    /// let d = VariantDecimal8::try_new(1234567890123, 0).unwrap();
949    /// let v5 = Variant::from(d);
950    /// assert_eq!(v5.as_int32(), None);
951    ///
952    /// // or if the variant cannot be cast into an integer
953    /// let v6 = Variant::from("hello");
954    /// assert_eq!(v6.as_int32(), None)
955    /// ```
956    pub fn as_int32(&self) -> Option<i32> {
957        match *self {
958            Variant::Int8(i) => Some(i as i32),
959            Variant::Int16(i) => Some(i as i32),
960            Variant::Int32(i) => Some(i),
961            Variant::Int64(i) => i.try_into().ok(),
962            Variant::Decimal4(d) => d.as_integer(),
963            Variant::Decimal8(d) => d.as_integer()?.try_into().ok(),
964            Variant::Decimal16(d) => d.as_integer()?.try_into().ok(),
965            _ => None,
966        }
967    }
968
969    /// Converts this variant to an `i64` if possible.
970    ///
971    /// Returns `Some(i64)` for int variant, decimal variant has no fractional part
972    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `i64` range.
973    /// `None` for other variants or values that would overflow.
974    ///
975    /// # Examples
976    ///
977    /// ```
978    /// use parquet_variant::{Variant, VariantDecimal16, VariantDecimal4};
979    ///
980    /// // you can read an int64 variant into an i64
981    /// let v1 = Variant::from(123i64);
982    /// assert_eq!(v1.as_int64(), Some(123i64));
983    ///
984    /// // or from a decimal variant that scale = 0
985    /// let d = VariantDecimal4::try_new(123, 0).unwrap();
986    /// let v2 = Variant::from(d);
987    /// assert_eq!(v2.as_int64(), Some(123i64));
988    ///
989    /// // or from a decimal variant that unscaled value is divisible by 10^scale
990    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
991    /// let v3 = Variant::from(d);
992    /// assert_eq!(v3.as_int64(), Some(1i64));
993    ///
994    /// // but not if it would overflow
995    /// let d = VariantDecimal16::try_new(i128::from(i64::MAX) + 1, 0).unwrap();
996    /// let v4 = Variant::from(d);
997    /// assert_eq!(v4.as_int64(), None);
998    ///
999    /// // or if the variant cannot be cast into an integer
1000    /// let v5 = Variant::from("hello!");
1001    /// assert_eq!(v5.as_int64(), None);
1002    /// ```
1003    pub fn as_int64(&self) -> Option<i64> {
1004        match *self {
1005            Variant::Int8(i) => Some(i as i64),
1006            Variant::Int16(i) => Some(i as i64),
1007            Variant::Int32(i) => Some(i as i64),
1008            Variant::Int64(i) => Some(i),
1009            Variant::Decimal4(d) => d.as_integer().map(|i| i as i64),
1010            Variant::Decimal8(d) => d.as_integer(),
1011            Variant::Decimal16(d) => d.as_integer()?.try_into().ok(),
1012            _ => None,
1013        }
1014    }
1015
1016    fn convert_to_unsigned_num<O>(variant: &Variant) -> Option<O>
1017    where
1018        O: TryFrom<i8> + TryFrom<i16> + TryFrom<i32> + TryFrom<i64> + TryFrom<i128>,
1019    {
1020        match *variant {
1021            Variant::Int8(i) => i.try_into().ok(),
1022            Variant::Int16(i) => i.try_into().ok(),
1023            Variant::Int32(i) => i.try_into().ok(),
1024            Variant::Int64(i) => i.try_into().ok(),
1025            Variant::Decimal4(d) => d.as_integer()?.try_into().ok(),
1026            Variant::Decimal8(d) => d.as_integer()?.try_into().ok(),
1027            Variant::Decimal16(d) => d.as_integer()?.try_into().ok(),
1028            _ => None,
1029        }
1030    }
1031
1032    /// Converts this variant to a `u8` if possible.
1033    ///
1034    /// Returns `Some(u8)` for int variant, decimal variant has no fractional part
1035    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `u8` range.
1036    /// `None` for other variants or values that would overflow.
1037    ///
1038    /// # Examples
1039    ///
1040    /// ```
1041    ///  use parquet_variant::{Variant, VariantDecimal4};
1042    ///
1043    ///  // you can read an int64 variant into an u8
1044    ///  let v1 = Variant::from(123i64);
1045    ///  assert_eq!(v1.as_u8(), Some(123u8));
1046    ///
1047    /// // or from decimal variant that scale = 0
1048    /// let d = VariantDecimal4::try_new(123, 0).unwrap();
1049    /// let v2 = Variant::from(d);
1050    /// assert_eq!(v2.as_u8(), Some(123u8));
1051    ///
1052    /// // or from a decimal variant that unscaled integer is divisible by 10^scale
1053    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
1054    /// let v3 = Variant::from(d);
1055    /// assert_eq!(v3.as_u8(), Some(1u8));
1056    ///
1057    ///  // but not a variant that can't fit into the range
1058    /// let d = VariantDecimal4::try_new(-1, 0).unwrap();
1059    ///  let v4 = Variant::from(d);
1060    ///  assert_eq!(v4.as_u8(), None);
1061    ///
1062    ///  // or not a variant that cannot be cast into an integer
1063    ///  let v5 = Variant::from("hello");
1064    ///  assert_eq!(v5.as_u8(), None);
1065    /// ```
1066    pub fn as_u8(&self) -> Option<u8> {
1067        Self::convert_to_unsigned_num(self)
1068    }
1069
1070    /// Converts this variant to an `u16` if possible.
1071    ///
1072    /// Returns `Some(u16)` for int variant, decimal variant has no fractional part
1073    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `u16` range.
1074    /// `None` for other variants or values that would overflow.
1075    ///
1076    /// # Examples
1077    ///
1078    /// ```
1079    ///  use parquet_variant::{Variant, VariantDecimal4};
1080    ///
1081    ///  // you can read an int64 variant into an u16
1082    ///  let v1 = Variant::from(123i64);
1083    ///  assert_eq!(v1.as_u16(), Some(123u16));
1084    ///
1085    /// // or from decimal variant that scale = 0
1086    /// let d = VariantDecimal4::try_new(123, 0).unwrap();
1087    /// let v2 = Variant::from(d);
1088    /// assert_eq!(v2.as_u16(), Some(123u16));
1089    ///
1090    /// // or from a decimal variant that unscaled value is divisible by 10^scale
1091    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
1092    /// let v3 = Variant::from(d);
1093    /// assert_eq!(v3.as_u16(), Some(1u16));
1094    ///
1095    ///  // but not a variant that can't fit into the range
1096    /// let d = VariantDecimal4::try_new(-1, 0).unwrap();
1097    ///  let v4 = Variant::from(d);
1098    ///  assert_eq!(v4.as_u16(), None);
1099    ///
1100    ///  // or not a variant that cannot be cast into an integer
1101    ///  let v5 = Variant::from("hello");
1102    ///  assert_eq!(v5.as_u16(), None);
1103    /// ```
1104    pub fn as_u16(&self) -> Option<u16> {
1105        Self::convert_to_unsigned_num(self)
1106    }
1107
1108    /// Converts this variant to an `u32` if possible.
1109    ///
1110    /// Returns `Some(u32)` for int variant, decimal variant has no fractional part
1111    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `u32` range.
1112    /// `None` for other variants or values that would overflow.
1113    ///
1114    /// # Examples
1115    ///
1116    /// ```
1117    ///  use parquet_variant::{Variant, VariantDecimal4, VariantDecimal8};
1118    ///
1119    ///  // you can read an int64 variant into an u32
1120    ///  let v1 = Variant::from(123i64);
1121    ///  assert_eq!(v1.as_u32(), Some(123u32));
1122    ///
1123    ///  // or from decimal variant that scale = 0
1124    ///  let d = VariantDecimal4::try_new(123, 0).unwrap();
1125    ///  let v2 = Variant::from(d);
1126    ///  assert_eq!(v2.as_u32(), Some(123u32));
1127    ///
1128    /// // or from a decimal variant that unscaled value is divisible by 10^scale
1129    /// let d = VariantDecimal4::try_new(100, 2).unwrap();
1130    /// let v3 = Variant::from(d);
1131    /// assert_eq!(v3.as_u32(), Some(1u32));
1132    ///
1133    ///  // but not a variant that can't fit into the range
1134    /// let d = VariantDecimal4::try_new(-1, 0).unwrap();
1135    ///  let v4 = Variant::from(d);
1136    ///  assert_eq!(v4.as_u32(), None);
1137    ///
1138    ///  // or not a variant that cannot be cast into an integer
1139    ///  let v5 = Variant::from("hello");
1140    ///  assert_eq!(v5.as_u32(), None);
1141    /// ```
1142    pub fn as_u32(&self) -> Option<u32> {
1143        Self::convert_to_unsigned_num(self)
1144    }
1145
1146    /// Converts this variant to an `u64` if possible.
1147    ///
1148    /// Returns `Some(u64)` for integer variant, decimal variant has no fractional part
1149    /// (scale=0 or unscaled integer is divisible by 10^scale) that fits in `u64` range.
1150    /// `None` for other variants or values that would overflow.
1151    ///
1152    /// # Examples
1153    ///
1154    /// ```
1155    ///  use parquet_variant::{Variant, VariantDecimal16, VariantDecimal4};
1156    ///
1157    ///  // you can read an int64 variant into an u64
1158    ///  let v1 = Variant::from(123i64);
1159    ///  assert_eq!(v1.as_u64(), Some(123u64));
1160    ///
1161    ///  // or from a variant decimal with scale = 0
1162    /// let d = VariantDecimal16::try_new(1, 0).unwrap();
1163    ///  let v2 = Variant::from(d);
1164    ///  assert_eq!(v2.as_u64(), Some(1u64));
1165    ///
1166    /// // or from a decimal variant that unscaled value is divisible by 10^scale
1167    /// let d = VariantDecimal16::try_new(100, 2).unwrap();
1168    /// let v3 = Variant::from(d);
1169    /// assert_eq!(v3.as_u64(), Some(1u64));
1170    ///
1171    ///  // but not a variant that can't fit into the range
1172    /// let d = VariantDecimal4::try_new(-1, 0).unwrap();
1173    ///  let v4 = Variant::from(d);
1174    ///  assert_eq!(v4.as_u64(), None);
1175    ///
1176    ///  // or not a variant that cannot be cast into an integer
1177    ///  let v5 = Variant::from("hello!");
1178    ///  assert_eq!(v5.as_u64(), None);
1179    /// ```
1180    pub fn as_u64(&self) -> Option<u64> {
1181        Self::convert_to_unsigned_num(self)
1182    }
1183
1184    /// Converts this variant to tuple with a 4-byte unscaled value if possible.
1185    ///
1186    /// Returns `Some((i32, u8))` for decimal variants, int variants where the unscaled value fits in
1187    /// `i32` range, `None` for other variants or the value would overflow.
1188    ///
1189    /// # Examples
1190    ///
1191    /// ```
1192    /// use parquet_variant::{Variant, VariantDecimal4, VariantDecimal8};
1193    ///
1194    /// // you can extract decimal parts from smaller or equally-sized decimal variants
1195    /// let v1 = Variant::from(VariantDecimal4::try_new(1234_i32, 2).unwrap());
1196    /// assert_eq!(v1.as_decimal4(), VariantDecimal4::try_new(1234_i32, 2).ok());
1197    ///
1198    /// // and from larger decimal variants if they fit
1199    /// let v2 = Variant::from(VariantDecimal8::try_new(1234_i64, 2).unwrap());
1200    /// assert_eq!(v2.as_decimal4(), VariantDecimal4::try_new(1234_i32, 2).ok());
1201    ///
1202    /// // and from integer if they fit
1203    /// let v3 = Variant::from(123);
1204    /// assert_eq!(v3.as_decimal4(), VariantDecimal4::try_new(123_i32, 0).ok());
1205    ///
1206    /// // but not if the value would overflow i32
1207    /// let v4 = Variant::from(VariantDecimal8::try_new(12345678901i64, 2).unwrap());
1208    /// assert_eq!(v4.as_decimal4(), None);
1209    ///
1210    /// // or if the variant is not a decimal
1211    /// let v5 = Variant::from("hello");
1212    /// assert_eq!(v5.as_decimal4(), None);
1213    /// ```
1214    pub fn as_decimal4(&self) -> Option<VariantDecimal4> {
1215        match *self {
1216            Variant::Int8(i) => VariantDecimal4::try_new(i as i32, 0).ok(),
1217            Variant::Int16(i) => VariantDecimal4::try_new(i as i32, 0).ok(),
1218            Variant::Int32(i) => VariantDecimal4::try_new(i, 0).ok(),
1219            Variant::Int64(i) => {
1220                let i = i32::try_from(i).ok()?;
1221                VariantDecimal4::try_new(i, 0).ok()
1222            }
1223            Variant::Decimal4(decimal4) => Some(decimal4),
1224            Variant::Decimal8(decimal8) => decimal8.try_into().ok(),
1225            Variant::Decimal16(decimal16) => decimal16.try_into().ok(),
1226            _ => None,
1227        }
1228    }
1229
1230    /// Converts this variant to tuple with an 8-byte unscaled value if possible.
1231    ///
1232    /// Returns `Some((i64, u8))` for decimal variants, int variants where the unscaled value
1233    /// fits in `i64` range, `None` for other variants or decimal values that would overflow.
1234    ///
1235    /// # Examples
1236    ///
1237    /// ```
1238    /// use parquet_variant::{Variant, VariantDecimal16, VariantDecimal4, VariantDecimal8};
1239    ///
1240    /// // you can extract decimal parts from smaller or equally-sized decimal variants
1241    /// let v1 = Variant::from(VariantDecimal4::try_new(1234_i32, 2).unwrap());
1242    /// assert_eq!(v1.as_decimal8(), VariantDecimal8::try_new(1234_i64, 2).ok());
1243    ///
1244    /// // and from larger decimal variants if they fit
1245    /// let v2 = Variant::from(VariantDecimal16::try_new(1234_i128, 2).unwrap());
1246    /// assert_eq!(v2.as_decimal8(), VariantDecimal8::try_new(1234_i64, 2).ok());
1247    ///
1248    /// // or from int variants if they fit
1249    /// let v3 = Variant::from(123);
1250    /// assert_eq!(v3.as_decimal8(), VariantDecimal8::try_new(123_i64, 0).ok());
1251    ///
1252    /// // but not if the value would overflow i64
1253    /// let v4 = Variant::from(VariantDecimal16::try_new(2e19 as i128, 2).unwrap());
1254    /// assert_eq!(v4.as_decimal8(), None);
1255    ///
1256    /// // or if the variant is not a decimal
1257    /// let v5 = Variant::from("hello");
1258    /// assert_eq!(v5.as_decimal8(), None);
1259    /// ```
1260    pub fn as_decimal8(&self) -> Option<VariantDecimal8> {
1261        match *self {
1262            Variant::Int8(i) => VariantDecimal8::try_new(i as i64, 0).ok(),
1263            Variant::Int16(i) => VariantDecimal8::try_new(i as i64, 0).ok(),
1264            Variant::Int32(i) => VariantDecimal8::try_new(i as i64, 0).ok(),
1265            Variant::Int64(i) => VariantDecimal8::try_new(i, 0).ok(),
1266            Variant::Decimal4(decimal4) => Some(decimal4.into()),
1267            Variant::Decimal8(decimal8) => Some(decimal8),
1268            Variant::Decimal16(decimal16) => decimal16.try_into().ok(),
1269            _ => None,
1270        }
1271    }
1272
1273    /// Converts this variant to tuple with a 16-byte unscaled value if possible.
1274    ///
1275    /// Returns `Some((i128, u8))` for decimal variants, int variants where the unscaled value
1276    /// fits in `i128` range, `None` for other variants or values that would overflow.
1277    ///
1278    /// # Examples
1279    ///
1280    /// ```
1281    /// use parquet_variant::{Variant, VariantDecimal16, VariantDecimal4};
1282    ///
1283    /// // you can extract decimal parts from smaller or equally-sized decimal variants
1284    /// let d = VariantDecimal16::try_new(2e19 as i128, 2).unwrap();
1285    /// let v1 = Variant::from(d);
1286    /// assert_eq!(v1.as_decimal16(), VariantDecimal16::try_new(2e19 as i128, 2).ok());
1287    ///
1288    /// // or from int variants
1289    /// let v2 = Variant::from(123);
1290    /// assert_eq!(v2.as_decimal16(), VariantDecimal16::try_new(123_i128, 0).ok());
1291    ///
1292    /// // but not if the variant is not a decimal
1293    /// let v3 = Variant::from("hello");
1294    /// assert_eq!(v3.as_decimal16(), None);
1295    /// ```
1296    pub fn as_decimal16(&self) -> Option<VariantDecimal16> {
1297        match *self {
1298            Variant::Int8(i) => VariantDecimal16::try_new(i as i128, 0).ok(),
1299            Variant::Int16(i) => VariantDecimal16::try_new(i as i128, 0).ok(),
1300            Variant::Int32(i) => VariantDecimal16::try_new(i as i128, 0).ok(),
1301            Variant::Int64(i) => VariantDecimal16::try_new(i as i128, 0).ok(),
1302            Variant::Decimal4(decimal4) => Some(decimal4.into()),
1303            Variant::Decimal8(decimal8) => Some(decimal8.into()),
1304            Variant::Decimal16(decimal16) => Some(decimal16),
1305            _ => None,
1306        }
1307    }
1308
1309    /// Converts this variant to an `f32` if possible.
1310    ///
1311    /// Returns `Some(f32)` for float variants, `None` for other variants.
1312    ///
1313    /// # Examples
1314    ///
1315    /// ```
1316    /// use parquet_variant::Variant;
1317    ///
1318    /// // you can extract an f32 from a float variant
1319    /// let v1 = Variant::from(std::f32::consts::PI);
1320    /// assert_eq!(v1.as_f32(), Some(std::f32::consts::PI));
1321    ///
1322    /// // but not from double variant
1323    /// let v3 = Variant::from(3f64);
1324    /// assert_eq!(v3.as_f32(), None);
1325    ///
1326    /// // or other variants
1327    /// let v4 = Variant::from("hello");
1328    /// assert_eq!(v4.as_f32(), None);
1329    /// ```
1330    pub fn as_f32(&self) -> Option<f32> {
1331        match *self {
1332            Variant::Float(i) => Some(i),
1333            _ => None,
1334        }
1335    }
1336
1337    /// Converts this variant to an `f64`.
1338    ///
1339    /// Returns `Some(f64)` for double variants, `None` otherwise.
1340    ///
1341    /// # Examples
1342    ///
1343    /// ```
1344    /// use parquet_variant::Variant;
1345    ///
1346    /// // you can extract an f64 from a double variant
1347    /// let v1 = Variant::from(std::f64::consts::PI);
1348    /// assert_eq!(v1.as_f64(), Some(std::f64::consts::PI));
1349    ///
1350    /// // but not from a float variant
1351    /// let v2 = Variant::from(std::f32::consts::PI);
1352    /// assert_eq!(v2.as_f64(), None);
1353    ///
1354    /// // or from other variants
1355    /// let v3 = Variant::from("hello");
1356    /// assert_eq!(v3.as_f64(), None);
1357    /// ```
1358    pub fn as_f64(&self) -> Option<f64> {
1359        match *self {
1360            Variant::Double(i) => Some(i),
1361            _ => None,
1362        }
1363    }
1364
1365    /// Converts this variant to an `Object` if it is an [`VariantObject`].
1366    ///
1367    /// Returns `Some(&VariantObject)` for object variants,
1368    /// `None` for non-object variants.
1369    ///
1370    /// See [`Self::get_path`] to dynamically traverse objects
1371    ///
1372    /// # Examples
1373    /// ```
1374    /// # use parquet_variant::{Variant, VariantBuilder, VariantObject};
1375    /// # let (metadata, value) = {
1376    /// # let mut builder = VariantBuilder::new();
1377    /// #   let mut obj = builder.new_object();
1378    /// #   obj.insert("name", "John");
1379    /// #   obj.finish();
1380    /// #   builder.finish()
1381    /// # };
1382    /// // object that is {"name": "John"}
1383    ///  let variant = Variant::new(&metadata, &value);
1384    /// // use the `as_object` method to access the object
1385    /// let obj = variant.as_object().expect("variant should be an object");
1386    /// assert_eq!(obj.get("name"), Some(Variant::from("John")));
1387    /// ```
1388    pub fn as_object(&'m self) -> Option<&'m VariantObject<'m, 'v>> {
1389        if let Variant::Object(obj) = self {
1390            Some(obj)
1391        } else {
1392            None
1393        }
1394    }
1395
1396    /// If this is an object and the requested field name exists, retrieves the corresponding field
1397    /// value. Otherwise, returns None.
1398    ///
1399    /// This is shorthand for [`Self::as_object`] followed by [`VariantObject::get`].
1400    ///
1401    /// # Examples
1402    /// ```
1403    /// # use parquet_variant::{Variant, VariantBuilder, VariantObject};
1404    /// # let mut builder = VariantBuilder::new();
1405    /// # let mut obj = builder.new_object();
1406    /// # obj.insert("name", "John");
1407    /// # obj.finish();
1408    /// # let (metadata, value) = builder.finish();
1409    /// // object that is {"name": "John"}
1410    ///  let variant = Variant::new(&metadata, &value);
1411    /// // use the `get_object_field` method to access the object
1412    /// let obj = variant.get_object_field("name");
1413    /// assert_eq!(obj, Some(Variant::from("John")));
1414    /// let obj = variant.get_object_field("foo");
1415    /// assert!(obj.is_none());
1416    /// ```
1417    pub fn get_object_field(&self, field_name: &str) -> Option<Self> {
1418        match self {
1419            Variant::Object(object) => object.get(field_name),
1420            _ => None,
1421        }
1422    }
1423
1424    /// Converts this variant to a `List` if it is a [`VariantList`].
1425    ///
1426    /// Returns `Some(&VariantList)` for list variants,
1427    /// `None` for non-list variants.
1428    ///
1429    /// See [`Self::get_path`] to dynamically traverse lists
1430    ///
1431    /// # Examples
1432    /// ```
1433    /// # use parquet_variant::{Variant, VariantBuilder, VariantList};
1434    /// # let (metadata, value) = {
1435    /// # let mut builder = VariantBuilder::new();
1436    /// #   let mut list = builder.new_list();
1437    /// #   list.append_value("John");
1438    /// #   list.append_value("Doe");
1439    /// #   list.finish();
1440    /// #   builder.finish()
1441    /// # };
1442    /// // list that is ["John", "Doe"]
1443    /// let variant = Variant::new(&metadata, &value);
1444    /// // use the `as_list` method to access the list
1445    /// let list = variant.as_list().expect("variant should be a list");
1446    /// assert_eq!(list.len(), 2);
1447    /// assert_eq!(list.get(0).unwrap(), Variant::from("John"));
1448    /// assert_eq!(list.get(1).unwrap(), Variant::from("Doe"));
1449    /// ```
1450    pub fn as_list(&'m self) -> Option<&'m VariantList<'m, 'v>> {
1451        if let Variant::List(list) = self {
1452            Some(list)
1453        } else {
1454            None
1455        }
1456    }
1457
1458    /// Converts this variant to a `NaiveTime` if possible.
1459    ///
1460    /// Returns `Some(NaiveTime)` for `Variant::Time`,
1461    /// `None` for non-Time variants.
1462    ///
1463    /// # Example
1464    ///
1465    /// ```
1466    /// use chrono::NaiveTime;
1467    /// use parquet_variant::Variant;
1468    ///
1469    /// // you can extract a `NaiveTime` from a `Variant::Time`
1470    /// let time = NaiveTime::from_hms_micro_opt(1, 2, 3, 4).unwrap();
1471    /// let v1 = Variant::from(time);
1472    /// assert_eq!(Some(time), v1.as_time_utc());
1473    ///
1474    /// // but not from other variants.
1475    /// let v2 = Variant::from("Hello");
1476    /// assert_eq!(None, v2.as_time_utc());
1477    /// ```
1478    pub fn as_time_utc(&'m self) -> Option<NaiveTime> {
1479        if let Variant::Time(time) = self {
1480            Some(*time)
1481        } else {
1482            None
1483        }
1484    }
1485
1486    /// If this is a list and the requested index is in bounds, retrieves the corresponding
1487    /// element. Otherwise, returns None.
1488    ///
1489    /// This is shorthand for [`Self::as_list`] followed by [`VariantList::get`].
1490    ///
1491    /// # Examples
1492    /// ```
1493    /// # use parquet_variant::{Variant, VariantBuilder, VariantList};
1494    /// # let mut builder = VariantBuilder::new();
1495    /// # let mut list = builder.new_list();
1496    /// # list.append_value("John");
1497    /// # list.append_value("Doe");
1498    /// # list.finish();
1499    /// # let (metadata, value) = builder.finish();
1500    /// // list that is ["John", "Doe"]
1501    /// let variant = Variant::new(&metadata, &value);
1502    /// // use the `get_list_element` method to access the list
1503    /// assert_eq!(variant.get_list_element(0), Some(Variant::from("John")));
1504    /// assert_eq!(variant.get_list_element(1), Some(Variant::from("Doe")));
1505    /// assert!(variant.get_list_element(2).is_none());
1506    /// ```
1507    pub fn get_list_element(&self, index: usize) -> Option<Self> {
1508        match self {
1509            Variant::List(list) => list.get(index),
1510            _ => None,
1511        }
1512    }
1513
1514    /// Return the metadata dictionary associated with this variant value.
1515    pub fn metadata(&self) -> &VariantMetadata<'m> {
1516        match self {
1517            Variant::Object(VariantObject { metadata, .. })
1518            | Variant::List(VariantList { metadata, .. }) => metadata,
1519            _ => &EMPTY_VARIANT_METADATA,
1520        }
1521    }
1522
1523    /// Return a new Variant with the path followed.
1524    ///
1525    /// If the path is not found, `None` is returned.
1526    ///
1527    /// # Example
1528    /// ```
1529    /// # use parquet_variant::{Variant, VariantBuilder, VariantObject, VariantPath};
1530    /// # let mut builder = VariantBuilder::new();
1531    /// # let mut obj = builder.new_object();
1532    /// # let mut list = obj.new_list("foo");
1533    /// # list.append_value("bar");
1534    /// # list.append_value("baz");
1535    /// # list.finish();
1536    /// # obj.finish();
1537    /// # let (metadata, value) = builder.finish();
1538    /// // given a variant like `{"foo": ["bar", "baz"]}`
1539    /// let variant = Variant::new(&metadata, &value);
1540    /// // Accessing a non existent path returns None
1541    /// assert_eq!(variant.get_path(&VariantPath::try_from("non_existent").unwrap()), None);
1542    /// // Access obj["foo"]
1543    /// let path = VariantPath::try_from("foo").unwrap();
1544    /// let foo = variant.get_path(&path).expect("field `foo` should exist");
1545    /// assert!(foo.as_list().is_some(), "field `foo` should be a list");
1546    /// // Access foo[0]
1547    /// let path = VariantPath::from(0);
1548    /// let bar = foo.get_path(&path).expect("element 0 should exist");
1549    /// // bar is a string
1550    /// assert_eq!(bar.as_string(), Some("bar"));
1551    /// // You can also access nested paths
1552    /// let path = VariantPath::try_from("foo").unwrap().join(0);
1553    /// assert_eq!(variant.get_path(&path).unwrap(), bar);
1554    /// ```
1555    pub fn get_path(&self, path: &VariantPath) -> Option<Variant<'_, '_>> {
1556        path.iter()
1557            .try_fold(self.clone(), |output, element| match element {
1558                VariantPathElement::Field { name } => output.get_object_field(name),
1559                VariantPathElement::Index { index } => output.get_list_element(*index),
1560                VariantPathElement::ListElement => None,
1561            })
1562    }
1563}
1564
1565impl From<()> for Variant<'_, '_> {
1566    fn from((): ()) -> Self {
1567        Variant::Null
1568    }
1569}
1570
1571impl From<bool> for Variant<'_, '_> {
1572    fn from(value: bool) -> Self {
1573        match value {
1574            true => Variant::BooleanTrue,
1575            false => Variant::BooleanFalse,
1576        }
1577    }
1578}
1579
1580impl From<i8> for Variant<'_, '_> {
1581    fn from(value: i8) -> Self {
1582        Variant::Int8(value)
1583    }
1584}
1585
1586impl From<i16> for Variant<'_, '_> {
1587    fn from(value: i16) -> Self {
1588        Variant::Int16(value)
1589    }
1590}
1591
1592impl From<i32> for Variant<'_, '_> {
1593    fn from(value: i32) -> Self {
1594        Variant::Int32(value)
1595    }
1596}
1597
1598impl From<i64> for Variant<'_, '_> {
1599    fn from(value: i64) -> Self {
1600        Variant::Int64(value)
1601    }
1602}
1603
1604impl From<u8> for Variant<'_, '_> {
1605    fn from(value: u8) -> Self {
1606        // if it fits in i8, use that, otherwise use i16
1607        if let Ok(value) = i8::try_from(value) {
1608            Variant::Int8(value)
1609        } else {
1610            Variant::Int16(i16::from(value))
1611        }
1612    }
1613}
1614
1615impl From<u16> for Variant<'_, '_> {
1616    fn from(value: u16) -> Self {
1617        // if it fits in i16, use that, otherwise use i32
1618        if let Ok(value) = i16::try_from(value) {
1619            Variant::Int16(value)
1620        } else {
1621            Variant::Int32(i32::from(value))
1622        }
1623    }
1624}
1625impl From<u32> for Variant<'_, '_> {
1626    fn from(value: u32) -> Self {
1627        // if it fits in i32, use that, otherwise use i64
1628        if let Ok(value) = i32::try_from(value) {
1629            Variant::Int32(value)
1630        } else {
1631            Variant::Int64(i64::from(value))
1632        }
1633    }
1634}
1635
1636impl From<u64> for Variant<'_, '_> {
1637    fn from(value: u64) -> Self {
1638        // if it fits in i64, use that, otherwise use Decimal16
1639        if let Ok(value) = i64::try_from(value) {
1640            Variant::Int64(value)
1641        } else {
1642            // u64 max is 18446744073709551615, which fits in i128
1643            Variant::Decimal16(VariantDecimal16::try_new(i128::from(value), 0).unwrap())
1644        }
1645    }
1646}
1647
1648impl From<VariantDecimal4> for Variant<'_, '_> {
1649    fn from(value: VariantDecimal4) -> Self {
1650        Variant::Decimal4(value)
1651    }
1652}
1653
1654impl From<VariantDecimal8> for Variant<'_, '_> {
1655    fn from(value: VariantDecimal8) -> Self {
1656        Variant::Decimal8(value)
1657    }
1658}
1659
1660impl From<VariantDecimal16> for Variant<'_, '_> {
1661    fn from(value: VariantDecimal16) -> Self {
1662        Variant::Decimal16(value)
1663    }
1664}
1665
1666impl From<half::f16> for Variant<'_, '_> {
1667    fn from(value: half::f16) -> Self {
1668        Variant::Float(value.into())
1669    }
1670}
1671
1672impl From<f32> for Variant<'_, '_> {
1673    fn from(value: f32) -> Self {
1674        Variant::Float(value)
1675    }
1676}
1677
1678impl From<f64> for Variant<'_, '_> {
1679    fn from(value: f64) -> Self {
1680        Variant::Double(value)
1681    }
1682}
1683
1684impl From<NaiveDate> for Variant<'_, '_> {
1685    fn from(value: NaiveDate) -> Self {
1686        Variant::Date(value)
1687    }
1688}
1689
1690impl From<DateTime<Utc>> for Variant<'_, '_> {
1691    fn from(value: DateTime<Utc>) -> Self {
1692        if !value.nanosecond().is_multiple_of(1000) {
1693            Variant::TimestampNanos(value)
1694        } else {
1695            Variant::TimestampMicros(value)
1696        }
1697    }
1698}
1699
1700impl From<NaiveDateTime> for Variant<'_, '_> {
1701    fn from(value: NaiveDateTime) -> Self {
1702        if !value.nanosecond().is_multiple_of(1000) {
1703            Variant::TimestampNtzNanos(value)
1704        } else {
1705            Variant::TimestampNtzMicros(value)
1706        }
1707    }
1708}
1709
1710impl<'v> From<&'v [u8]> for Variant<'_, 'v> {
1711    fn from(value: &'v [u8]) -> Self {
1712        Variant::Binary(value)
1713    }
1714}
1715
1716impl From<NaiveTime> for Variant<'_, '_> {
1717    fn from(value: NaiveTime) -> Self {
1718        Variant::Time(value)
1719    }
1720}
1721
1722impl From<Uuid> for Variant<'_, '_> {
1723    fn from(value: Uuid) -> Self {
1724        Variant::Uuid(value)
1725    }
1726}
1727
1728impl<'v> From<&'v str> for Variant<'_, 'v> {
1729    fn from(value: &'v str) -> Self {
1730        if value.len() > MAX_SHORT_STRING_BYTES {
1731            Variant::String(value)
1732        } else {
1733            Variant::ShortString(ShortString(value))
1734        }
1735    }
1736}
1737
1738impl TryFrom<(i32, u8)> for Variant<'_, '_> {
1739    type Error = ArrowError;
1740
1741    fn try_from(value: (i32, u8)) -> Result<Self, Self::Error> {
1742        Ok(Variant::Decimal4(VariantDecimal4::try_new(
1743            value.0, value.1,
1744        )?))
1745    }
1746}
1747
1748impl TryFrom<(i64, u8)> for Variant<'_, '_> {
1749    type Error = ArrowError;
1750
1751    fn try_from(value: (i64, u8)) -> Result<Self, Self::Error> {
1752        Ok(Variant::Decimal8(VariantDecimal8::try_new(
1753            value.0, value.1,
1754        )?))
1755    }
1756}
1757
1758impl TryFrom<(i128, u8)> for Variant<'_, '_> {
1759    type Error = ArrowError;
1760
1761    fn try_from(value: (i128, u8)) -> Result<Self, Self::Error> {
1762        Ok(Variant::Decimal16(VariantDecimal16::try_new(
1763            value.0, value.1,
1764        )?))
1765    }
1766}
1767
1768// helper to print <invalid> instead of "<invalid>" in debug mode when a VariantObject or VariantList contains invalid values.
1769struct InvalidVariant;
1770
1771impl std::fmt::Debug for InvalidVariant {
1772    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1773        write!(f, "<invalid>")
1774    }
1775}
1776
1777// helper to print binary data in hex format in debug mode, as space-separated hex byte values.
1778struct HexString<'a>(&'a [u8]);
1779
1780impl std::fmt::Debug for HexString<'_> {
1781    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1782        if let Some((first, rest)) = self.0.split_first() {
1783            write!(f, "{first:02x}")?;
1784            for b in rest {
1785                write!(f, " {b:02x}")?;
1786            }
1787        }
1788        Ok(())
1789    }
1790}
1791
1792impl std::fmt::Debug for Variant<'_, '_> {
1793    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1794        match self {
1795            Variant::Null => write!(f, "Null"),
1796            Variant::BooleanTrue => write!(f, "BooleanTrue"),
1797            Variant::BooleanFalse => write!(f, "BooleanFalse"),
1798            Variant::Int8(v) => f.debug_tuple("Int8").field(v).finish(),
1799            Variant::Int16(v) => f.debug_tuple("Int16").field(v).finish(),
1800            Variant::Int32(v) => f.debug_tuple("Int32").field(v).finish(),
1801            Variant::Int64(v) => f.debug_tuple("Int64").field(v).finish(),
1802            Variant::Float(v) => f.debug_tuple("Float").field(v).finish(),
1803            Variant::Double(v) => f.debug_tuple("Double").field(v).finish(),
1804            Variant::Decimal4(d) => f.debug_tuple("Decimal4").field(d).finish(),
1805            Variant::Decimal8(d) => f.debug_tuple("Decimal8").field(d).finish(),
1806            Variant::Decimal16(d) => f.debug_tuple("Decimal16").field(d).finish(),
1807            Variant::Date(d) => f.debug_tuple("Date").field(d).finish(),
1808            Variant::TimestampMicros(ts) => f.debug_tuple("TimestampMicros").field(ts).finish(),
1809            Variant::TimestampNtzMicros(ts) => {
1810                f.debug_tuple("TimestampNtzMicros").field(ts).finish()
1811            }
1812            Variant::TimestampNanos(ts) => f.debug_tuple("TimestampNanos").field(ts).finish(),
1813            Variant::TimestampNtzNanos(ts) => f.debug_tuple("TimestampNtzNanos").field(ts).finish(),
1814            Variant::Binary(bytes) => write!(f, "Binary({:?})", HexString(bytes)),
1815            Variant::String(s) => f.debug_tuple("String").field(s).finish(),
1816            Variant::Time(s) => f.debug_tuple("Time").field(s).finish(),
1817            Variant::ShortString(s) => f.debug_tuple("ShortString").field(s).finish(),
1818            Variant::Uuid(uuid) => f.debug_tuple("Uuid").field(&uuid).finish(),
1819            Variant::Object(obj) => {
1820                let mut map = f.debug_map();
1821                for res in obj.iter_try() {
1822                    match res {
1823                        Ok((k, v)) => map.entry(&k, &v),
1824                        Err(_) => map.entry(&InvalidVariant, &InvalidVariant),
1825                    };
1826                }
1827                map.finish()
1828            }
1829            Variant::List(arr) => {
1830                let mut list = f.debug_list();
1831                for res in arr.iter_try() {
1832                    match res {
1833                        Ok(v) => list.entry(&v),
1834                        Err(_) => list.entry(&InvalidVariant),
1835                    };
1836                }
1837                list.finish()
1838            }
1839        }
1840    }
1841}
1842
1843#[cfg(test)]
1844mod tests {
1845
1846    use super::*;
1847
1848    #[test]
1849    fn test_empty_variant_will_fail() {
1850        let metadata = VariantMetadata::try_new(&[1, 0, 0]).unwrap();
1851
1852        let err = Variant::try_new_with_metadata(metadata, &[]).unwrap_err();
1853
1854        assert!(matches!(
1855            err,
1856            ArrowError::InvalidArgumentError(ref msg) if msg == "Received empty bytes"));
1857    }
1858
1859    #[test]
1860    fn test_construct_short_string() {
1861        let short_string = ShortString::try_new("norm").expect("should fit in short string");
1862        assert_eq!(short_string.as_str(), "norm");
1863
1864        let long_string = "a".repeat(MAX_SHORT_STRING_BYTES + 1);
1865        let res = ShortString::try_new(&long_string);
1866        assert!(res.is_err());
1867    }
1868
1869    #[test]
1870    fn test_variant_all_subtypes_debug() {
1871        use crate::VariantBuilder;
1872
1873        let mut builder = VariantBuilder::new();
1874
1875        // Create a root object that contains one of every variant subtype
1876        let mut root_obj = builder.new_object();
1877
1878        // Add primitive types
1879        root_obj.insert("null", ());
1880        root_obj.insert("boolean_true", true);
1881        root_obj.insert("boolean_false", false);
1882        root_obj.insert("int8", 42i8);
1883        root_obj.insert("int16", 1234i16);
1884        root_obj.insert("int32", 123456i32);
1885        root_obj.insert("int64", 1234567890123456789i64);
1886        root_obj.insert("float", 1.234f32);
1887        root_obj.insert("double", 1.23456789f64);
1888
1889        // Add date and timestamp types
1890        let date = chrono::NaiveDate::from_ymd_opt(2024, 12, 25).unwrap();
1891        root_obj.insert("date", date);
1892
1893        let timestamp_utc = chrono::NaiveDate::from_ymd_opt(2024, 12, 25)
1894            .unwrap()
1895            .and_hms_milli_opt(15, 30, 45, 123)
1896            .unwrap()
1897            .and_utc();
1898        root_obj.insert("timestamp_micros", Variant::TimestampMicros(timestamp_utc));
1899
1900        let timestamp_ntz = chrono::NaiveDate::from_ymd_opt(2024, 12, 25)
1901            .unwrap()
1902            .and_hms_milli_opt(15, 30, 45, 123)
1903            .unwrap();
1904        root_obj.insert(
1905            "timestamp_ntz_micros",
1906            Variant::TimestampNtzMicros(timestamp_ntz),
1907        );
1908
1909        let timestamp_nanos_utc = chrono::NaiveDate::from_ymd_opt(2025, 8, 15)
1910            .unwrap()
1911            .and_hms_nano_opt(12, 3, 4, 123456789)
1912            .unwrap()
1913            .and_utc();
1914        root_obj.insert(
1915            "timestamp_nanos",
1916            Variant::TimestampNanos(timestamp_nanos_utc),
1917        );
1918
1919        let timestamp_ntz_nanos = chrono::NaiveDate::from_ymd_opt(2025, 8, 15)
1920            .unwrap()
1921            .and_hms_nano_opt(12, 3, 4, 123456789)
1922            .unwrap();
1923        root_obj.insert(
1924            "timestamp_ntz_nanos",
1925            Variant::TimestampNtzNanos(timestamp_ntz_nanos),
1926        );
1927
1928        // Add decimal types
1929        let decimal4 = VariantDecimal4::try_new(1234i32, 2).unwrap();
1930        root_obj.insert("decimal4", decimal4);
1931
1932        let decimal8 = VariantDecimal8::try_new(123456789i64, 3).unwrap();
1933        root_obj.insert("decimal8", decimal8);
1934
1935        let decimal16 = VariantDecimal16::try_new(123456789012345678901234567890i128, 4).unwrap();
1936        root_obj.insert("decimal16", decimal16);
1937
1938        // Add binary and string types
1939        let binary_data = b"\x01\x02\x03\x04\xde\xad\xbe\xef";
1940        root_obj.insert("binary", binary_data.as_slice());
1941
1942        let long_string =
1943            "This is a long string that exceeds the short string limit and contains emoji 🦀";
1944        root_obj.insert("string", long_string);
1945        root_obj.insert("short_string", "Short string with emoji 🎉");
1946        let time = NaiveTime::from_hms_micro_opt(1, 2, 3, 4).unwrap();
1947        root_obj.insert("time", time);
1948
1949        // Add uuid
1950        let uuid = Uuid::parse_str("67e55044-10b1-426f-9247-bb680e5fe0c8").unwrap();
1951        root_obj.insert("uuid", Variant::Uuid(uuid));
1952
1953        // Add nested object
1954        let mut nested_obj = root_obj.new_object("nested_object");
1955        nested_obj.insert("inner_key1", "inner_value1");
1956        nested_obj.insert("inner_key2", 999i32);
1957        nested_obj.finish();
1958
1959        // Add list with mixed types
1960        let mut mixed_list = root_obj.new_list("mixed_list");
1961        mixed_list.append_value(1i32);
1962        mixed_list.append_value("two");
1963        mixed_list.append_value(true);
1964        mixed_list.append_value(4.0f32);
1965        mixed_list.append_value(());
1966
1967        // Add nested list inside the mixed list
1968        let mut nested_list = mixed_list.new_list();
1969        nested_list.append_value("nested");
1970        nested_list.append_value(10i8);
1971        nested_list.finish();
1972
1973        mixed_list.finish();
1974
1975        root_obj.finish();
1976
1977        let (metadata, value) = builder.finish();
1978        let variant = Variant::try_new(&metadata, &value).unwrap();
1979
1980        // Test Debug formatter (?)
1981        let debug_output = format!("{variant:?}");
1982
1983        // Verify that the debug output contains all the expected types
1984        assert!(debug_output.contains("\"null\": Null"));
1985        assert!(debug_output.contains("\"boolean_true\": BooleanTrue"));
1986        assert!(debug_output.contains("\"boolean_false\": BooleanFalse"));
1987        assert!(debug_output.contains("\"int8\": Int8(42)"));
1988        assert!(debug_output.contains("\"int16\": Int16(1234)"));
1989        assert!(debug_output.contains("\"int32\": Int32(123456)"));
1990        assert!(debug_output.contains("\"int64\": Int64(1234567890123456789)"));
1991        assert!(debug_output.contains("\"float\": Float(1.234)"));
1992        assert!(debug_output.contains("\"double\": Double(1.23456789"));
1993        assert!(debug_output.contains("\"date\": Date(2024-12-25)"));
1994        assert!(debug_output.contains("\"timestamp_micros\": TimestampMicros("));
1995        assert!(debug_output.contains("\"timestamp_ntz_micros\": TimestampNtzMicros("));
1996        assert!(debug_output.contains("\"timestamp_nanos\": TimestampNanos("));
1997        assert!(debug_output.contains("\"timestamp_ntz_nanos\": TimestampNtzNanos("));
1998        assert!(debug_output.contains("\"decimal4\": Decimal4("));
1999        assert!(debug_output.contains("\"decimal8\": Decimal8("));
2000        assert!(debug_output.contains("\"decimal16\": Decimal16("));
2001        assert!(debug_output.contains("\"binary\": Binary(01 02 03 04 de ad be ef)"));
2002        assert!(debug_output.contains("\"string\": String("));
2003        assert!(debug_output.contains("\"short_string\": ShortString("));
2004        assert!(debug_output.contains("\"uuid\": Uuid(67e55044-10b1-426f-9247-bb680e5fe0c8)"));
2005        assert!(debug_output.contains("\"time\": Time(01:02:03.000004)"));
2006        assert!(debug_output.contains("\"nested_object\":"));
2007        assert!(debug_output.contains("\"mixed_list\":"));
2008
2009        let expected = r#"{"binary": Binary(01 02 03 04 de ad be ef), "boolean_false": BooleanFalse, "boolean_true": BooleanTrue, "date": Date(2024-12-25), "decimal16": Decimal16(VariantDecimal16 { integer: 123456789012345678901234567890, scale: 4 }), "decimal4": Decimal4(VariantDecimal4 { integer: 1234, scale: 2 }), "decimal8": Decimal8(VariantDecimal8 { integer: 123456789, scale: 3 }), "double": Double(1.23456789), "float": Float(1.234), "int16": Int16(1234), "int32": Int32(123456), "int64": Int64(1234567890123456789), "int8": Int8(42), "mixed_list": [Int32(1), ShortString(ShortString("two")), BooleanTrue, Float(4.0), Null, [ShortString(ShortString("nested")), Int8(10)]], "nested_object": {"inner_key1": ShortString(ShortString("inner_value1")), "inner_key2": Int32(999)}, "null": Null, "short_string": ShortString(ShortString("Short string with emoji 🎉")), "string": String("This is a long string that exceeds the short string limit and contains emoji 🦀"), "time": Time(01:02:03.000004), "timestamp_micros": TimestampMicros(2024-12-25T15:30:45.123Z), "timestamp_nanos": TimestampNanos(2025-08-15T12:03:04.123456789Z), "timestamp_ntz_micros": TimestampNtzMicros(2024-12-25T15:30:45.123), "timestamp_ntz_nanos": TimestampNtzNanos(2025-08-15T12:03:04.123456789), "uuid": Uuid(67e55044-10b1-426f-9247-bb680e5fe0c8)}"#;
2010        assert_eq!(debug_output, expected);
2011
2012        // Test alternate Debug formatter (#?)
2013        let alt_debug_output = format!("{variant:#?}");
2014        let expected = r#"{
2015    "binary": Binary(01 02 03 04 de ad be ef),
2016    "boolean_false": BooleanFalse,
2017    "boolean_true": BooleanTrue,
2018    "date": Date(
2019        2024-12-25,
2020    ),
2021    "decimal16": Decimal16(
2022        VariantDecimal16 {
2023            integer: 123456789012345678901234567890,
2024            scale: 4,
2025        },
2026    ),
2027    "decimal4": Decimal4(
2028        VariantDecimal4 {
2029            integer: 1234,
2030            scale: 2,
2031        },
2032    ),
2033    "decimal8": Decimal8(
2034        VariantDecimal8 {
2035            integer: 123456789,
2036            scale: 3,
2037        },
2038    ),
2039    "double": Double(
2040        1.23456789,
2041    ),
2042    "float": Float(
2043        1.234,
2044    ),
2045    "int16": Int16(
2046        1234,
2047    ),
2048    "int32": Int32(
2049        123456,
2050    ),
2051    "int64": Int64(
2052        1234567890123456789,
2053    ),
2054    "int8": Int8(
2055        42,
2056    ),
2057    "mixed_list": [
2058        Int32(
2059            1,
2060        ),
2061        ShortString(
2062            ShortString(
2063                "two",
2064            ),
2065        ),
2066        BooleanTrue,
2067        Float(
2068            4.0,
2069        ),
2070        Null,
2071        [
2072            ShortString(
2073                ShortString(
2074                    "nested",
2075                ),
2076            ),
2077            Int8(
2078                10,
2079            ),
2080        ],
2081    ],
2082    "nested_object": {
2083        "inner_key1": ShortString(
2084            ShortString(
2085                "inner_value1",
2086            ),
2087        ),
2088        "inner_key2": Int32(
2089            999,
2090        ),
2091    },
2092    "null": Null,
2093    "short_string": ShortString(
2094        ShortString(
2095            "Short string with emoji 🎉",
2096        ),
2097    ),
2098    "string": String(
2099        "This is a long string that exceeds the short string limit and contains emoji 🦀",
2100    ),
2101    "time": Time(
2102        01:02:03.000004,
2103    ),
2104    "timestamp_micros": TimestampMicros(
2105        2024-12-25T15:30:45.123Z,
2106    ),
2107    "timestamp_nanos": TimestampNanos(
2108        2025-08-15T12:03:04.123456789Z,
2109    ),
2110    "timestamp_ntz_micros": TimestampNtzMicros(
2111        2024-12-25T15:30:45.123,
2112    ),
2113    "timestamp_ntz_nanos": TimestampNtzNanos(
2114        2025-08-15T12:03:04.123456789,
2115    ),
2116    "uuid": Uuid(
2117        67e55044-10b1-426f-9247-bb680e5fe0c8,
2118    ),
2119}"#;
2120        assert_eq!(alt_debug_output, expected);
2121    }
2122}