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}