arrow_cast/
display.rs

1// Licensed to the Apache Software Foundation (ASF) under one
2// or more contributor license agreements.  See the NOTICE file
3// distributed with this work for additional information
4// regarding copyright ownership.  The ASF licenses this file
5// to you under the Apache License, Version 2.0 (the
6// "License"); you may not use this file except in compliance
7// with the License.  You may obtain a copy of the License at
8//
9//   http://www.apache.org/licenses/LICENSE-2.0
10//
11// Unless required by applicable law or agreed to in writing,
12// software distributed under the License is distributed on an
13// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14// KIND, either express or implied.  See the License for the
15// specific language governing permissions and limitations
16// under the License.
17
18//! Functions for printing array values as human-readable strings.
19//!
20//! This is often used for debugging or logging purposes.
21//!
22//! See the [`pretty`] crate for additional functions for
23//! record batch pretty printing.
24//!
25//! [`pretty`]: crate::pretty
26use std::fmt::{Debug, Display, Formatter, Write};
27use std::hash::{Hash, Hasher};
28use std::ops::Range;
29
30use arrow_array::cast::*;
31use arrow_array::temporal_conversions::*;
32use arrow_array::timezone::Tz;
33use arrow_array::types::*;
34use arrow_array::*;
35use arrow_buffer::ArrowNativeType;
36use arrow_schema::*;
37use chrono::{NaiveDate, NaiveDateTime, SecondsFormat, TimeZone, Utc};
38use lexical_core::FormattedSize;
39
40type TimeFormat<'a> = Option<&'a str>;
41
42/// Format for displaying durations
43#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
44#[non_exhaustive]
45pub enum DurationFormat {
46    /// ISO 8601 - `P198DT72932.972880S`
47    ISO8601,
48    /// A human readable representation - `198 days 16 hours 34 mins 15.407810000 secs`
49    Pretty,
50}
51
52/// Options for formatting arrays
53///
54/// By default nulls are formatted as `""` and temporal types formatted
55/// according to RFC3339
56///
57/// # Equality
58///
59/// Most fields in [`FormatOptions`] are compared by value, except `formatter_factory`. As the trait
60/// does not require an [`Eq`] and [`Hash`] implementation, this struct only compares the pointer of
61/// the factories.
62#[derive(Debug, Clone)]
63pub struct FormatOptions<'a> {
64    /// If set to `true` any formatting errors will be written to the output
65    /// instead of being converted into a [`std::fmt::Error`]
66    safe: bool,
67    /// Format string for nulls
68    null: &'a str,
69    /// Date format for date arrays
70    date_format: TimeFormat<'a>,
71    /// Format for DateTime arrays
72    datetime_format: TimeFormat<'a>,
73    /// Timestamp format for timestamp arrays
74    timestamp_format: TimeFormat<'a>,
75    /// Timestamp format for timestamp with timezone arrays
76    timestamp_tz_format: TimeFormat<'a>,
77    /// Time format for time arrays
78    time_format: TimeFormat<'a>,
79    /// Duration format
80    duration_format: DurationFormat,
81    /// Show types in visual representation batches
82    types_info: bool,
83    /// Formatter factory used to instantiate custom [`ArrayFormatter`]s. This allows users to
84    /// provide custom formatters.
85    formatter_factory: Option<&'a dyn ArrayFormatterFactory>,
86}
87
88impl Default for FormatOptions<'_> {
89    fn default() -> Self {
90        Self::new()
91    }
92}
93
94impl PartialEq for FormatOptions<'_> {
95    fn eq(&self, other: &Self) -> bool {
96        self.safe == other.safe
97            && self.null == other.null
98            && self.date_format == other.date_format
99            && self.datetime_format == other.datetime_format
100            && self.timestamp_format == other.timestamp_format
101            && self.timestamp_tz_format == other.timestamp_tz_format
102            && self.time_format == other.time_format
103            && self.duration_format == other.duration_format
104            && self.types_info == other.types_info
105            && match (self.formatter_factory, other.formatter_factory) {
106                (Some(f1), Some(f2)) => std::ptr::eq(f1, f2),
107                (None, None) => true,
108                _ => false,
109            }
110    }
111}
112
113impl Eq for FormatOptions<'_> {}
114
115impl Hash for FormatOptions<'_> {
116    fn hash<H: Hasher>(&self, state: &mut H) {
117        self.safe.hash(state);
118        self.null.hash(state);
119        self.date_format.hash(state);
120        self.datetime_format.hash(state);
121        self.timestamp_format.hash(state);
122        self.timestamp_tz_format.hash(state);
123        self.time_format.hash(state);
124        self.duration_format.hash(state);
125        self.types_info.hash(state);
126        self.formatter_factory
127            .map(|f| f as *const dyn ArrayFormatterFactory)
128            .hash(state);
129    }
130}
131
132impl<'a> FormatOptions<'a> {
133    /// Creates a new set of format options
134    pub const fn new() -> Self {
135        Self {
136            safe: true,
137            null: "",
138            date_format: None,
139            datetime_format: None,
140            timestamp_format: None,
141            timestamp_tz_format: None,
142            time_format: None,
143            duration_format: DurationFormat::ISO8601,
144            types_info: false,
145            formatter_factory: None,
146        }
147    }
148
149    /// If set to `true` any formatting errors will be written to the output
150    /// instead of being converted into a [`std::fmt::Error`]
151    pub const fn with_display_error(mut self, safe: bool) -> Self {
152        self.safe = safe;
153        self
154    }
155
156    /// Overrides the string used to represent a null
157    ///
158    /// Defaults to `""`
159    pub const fn with_null(self, null: &'a str) -> Self {
160        Self { null, ..self }
161    }
162
163    /// Overrides the format used for [`DataType::Date32`] columns
164    pub const fn with_date_format(self, date_format: Option<&'a str>) -> Self {
165        Self {
166            date_format,
167            ..self
168        }
169    }
170
171    /// Overrides the format used for [`DataType::Date64`] columns
172    pub const fn with_datetime_format(self, datetime_format: Option<&'a str>) -> Self {
173        Self {
174            datetime_format,
175            ..self
176        }
177    }
178
179    /// Overrides the format used for [`DataType::Timestamp`] columns without a timezone
180    pub const fn with_timestamp_format(self, timestamp_format: Option<&'a str>) -> Self {
181        Self {
182            timestamp_format,
183            ..self
184        }
185    }
186
187    /// Overrides the format used for [`DataType::Timestamp`] columns with a timezone
188    pub const fn with_timestamp_tz_format(self, timestamp_tz_format: Option<&'a str>) -> Self {
189        Self {
190            timestamp_tz_format,
191            ..self
192        }
193    }
194
195    /// Overrides the format used for [`DataType::Time32`] and [`DataType::Time64`] columns
196    pub const fn with_time_format(self, time_format: Option<&'a str>) -> Self {
197        Self {
198            time_format,
199            ..self
200        }
201    }
202
203    /// Overrides the format used for duration columns
204    ///
205    /// Defaults to [`DurationFormat::ISO8601`]
206    pub const fn with_duration_format(self, duration_format: DurationFormat) -> Self {
207        Self {
208            duration_format,
209            ..self
210        }
211    }
212
213    /// Overrides if types should be shown
214    ///
215    /// Defaults to [`false`]
216    pub const fn with_types_info(self, types_info: bool) -> Self {
217        Self { types_info, ..self }
218    }
219
220    /// Overrides the [`ArrayFormatterFactory`] used to instantiate custom [`ArrayFormatter`]s.
221    ///
222    /// Using [`None`] causes pretty-printers to use the default [`ArrayFormatter`]s.
223    pub const fn with_formatter_factory(
224        self,
225        formatter_factory: Option<&'a dyn ArrayFormatterFactory>,
226    ) -> Self {
227        Self {
228            formatter_factory,
229            ..self
230        }
231    }
232
233    /// Returns whether formatting errors should be written to the output instead of being converted
234    /// into a [`std::fmt::Error`].
235    pub const fn safe(&self) -> bool {
236        self.safe
237    }
238
239    /// Returns the string used for displaying nulls.
240    pub const fn null(&self) -> &'a str {
241        self.null
242    }
243
244    /// Returns the format used for [`DataType::Date32`] columns.
245    pub const fn date_format(&self) -> TimeFormat<'a> {
246        self.date_format
247    }
248
249    /// Returns the format used for [`DataType::Date64`] columns.
250    pub const fn datetime_format(&self) -> TimeFormat<'a> {
251        self.datetime_format
252    }
253
254    /// Returns the format used for [`DataType::Timestamp`] columns without a timezone.
255    pub const fn timestamp_format(&self) -> TimeFormat<'a> {
256        self.timestamp_format
257    }
258
259    /// Returns the format used for [`DataType::Timestamp`] columns with a timezone.
260    pub const fn timestamp_tz_format(&self) -> TimeFormat<'a> {
261        self.timestamp_tz_format
262    }
263
264    /// Returns the format used for [`DataType::Time32`] and [`DataType::Time64`] columns.
265    pub const fn time_format(&self) -> TimeFormat<'a> {
266        self.time_format
267    }
268
269    /// Returns the [`DurationFormat`] used for duration columns.
270    pub const fn duration_format(&self) -> DurationFormat {
271        self.duration_format
272    }
273
274    /// Returns true if type info should be included in a visual representation of batches.
275    pub const fn types_info(&self) -> bool {
276        self.types_info
277    }
278
279    /// Returns the [`ArrayFormatterFactory`] used to instantiate custom [`ArrayFormatter`]s.
280    pub const fn formatter_factory(&self) -> Option<&'a dyn ArrayFormatterFactory> {
281        self.formatter_factory
282    }
283}
284
285/// Allows creating a new [`ArrayFormatter`] for a given [`Array`] and an optional [`Field`].
286///
287/// # Example
288///
289/// The example below shows how to create a custom formatter for a custom type `my_money`. Note that
290/// this example requires the `prettyprint` feature.
291///
292/// ```rust
293/// # #[cfg(feature = "prettyprint")]{
294/// use std::fmt::Write;
295/// use arrow_array::{cast::AsArray, Array, Int32Array};
296/// use arrow_cast::display::{ArrayFormatter, ArrayFormatterFactory, DisplayIndex, FormatOptions, FormatResult};
297/// use arrow_cast::pretty::pretty_format_batches_with_options;
298/// use arrow_schema::{ArrowError, Field};
299///
300/// /// A custom formatter factory that can create a formatter for the special type `my_money`.
301/// ///
302/// /// This struct could have access to some kind of extension type registry that can lookup the
303/// /// correct formatter for an extension type on-demand.
304/// #[derive(Debug)]
305/// struct MyFormatters {}
306///
307/// impl ArrayFormatterFactory for MyFormatters {
308///     fn create_array_formatter<'formatter>(
309///         &self,
310///         array: &'formatter dyn Array,
311///         options: &FormatOptions<'formatter>,
312///         field: Option<&'formatter Field>,
313///     ) -> Result<Option<ArrayFormatter<'formatter>>, ArrowError> {
314///         // check if this is the money type
315///         if field
316///             .map(|f| f.extension_type_name() == Some("my_money"))
317///             .unwrap_or(false)
318///         {
319///             // We assume that my_money always is an Int32.
320///             let array = array.as_primitive();
321///             let display_index = Box::new(MyMoneyFormatter { array, options: options.clone() });
322///             return Ok(Some(ArrayFormatter::new(display_index, options.safe())));
323///         }
324///
325///         Ok(None) // None indicates that the default formatter should be used.
326///     }
327/// }
328///
329/// /// A formatter for the type `my_money` that wraps a specific array and has access to the
330/// /// formatting options.
331/// struct MyMoneyFormatter<'a> {
332///     array: &'a Int32Array,
333///     options: FormatOptions<'a>,
334/// }
335///
336/// impl<'a> DisplayIndex for MyMoneyFormatter<'a> {
337///     fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
338///         match self.array.is_valid(idx) {
339///             true => write!(f, "{} €", self.array.value(idx))?,
340///             false => write!(f, "{}", self.options.null())?,
341///         }
342///
343///         Ok(())
344///     }
345/// }
346///
347/// // Usually, here you would provide your record batches.
348/// let my_batches = vec![];
349///
350/// // Call the pretty printer with the custom formatter factory.
351/// pretty_format_batches_with_options(
352///        &my_batches,
353///        &FormatOptions::new().with_formatter_factory(Some(&MyFormatters {}))
354/// );
355/// # }
356/// ```
357pub trait ArrayFormatterFactory: Debug + Send + Sync {
358    /// Creates a new [`ArrayFormatter`] for the given [`Array`] and an optional [`Field`]. If the
359    /// default implementation should be used, return [`None`].
360    ///
361    /// The field shall be used to look up metadata about the `array` while `options` provide
362    /// information on formatting, for example, dates and times which should be considered by an
363    /// implementor.
364    fn create_array_formatter<'formatter>(
365        &self,
366        array: &'formatter dyn Array,
367        options: &FormatOptions<'formatter>,
368        field: Option<&'formatter Field>,
369    ) -> Result<Option<ArrayFormatter<'formatter>>, ArrowError>;
370}
371
372/// Used to create a new [`ArrayFormatter`] from the given `array`, while also checking whether
373/// there is an override available in the [`ArrayFormatterFactory`].
374pub(crate) fn make_array_formatter<'a>(
375    array: &'a dyn Array,
376    options: &FormatOptions<'a>,
377    field: Option<&'a Field>,
378) -> Result<ArrayFormatter<'a>, ArrowError> {
379    match options.formatter_factory() {
380        None => ArrayFormatter::try_new(array, options),
381        Some(formatters) => formatters
382            .create_array_formatter(array, options, field)
383            .transpose()
384            .unwrap_or_else(|| ArrayFormatter::try_new(array, options)),
385    }
386}
387
388/// Implements [`Display`] for a specific array value
389pub struct ValueFormatter<'a> {
390    idx: usize,
391    formatter: &'a ArrayFormatter<'a>,
392}
393
394impl ValueFormatter<'_> {
395    /// Writes this value to the provided [`Write`]
396    ///
397    /// Note: this ignores [`FormatOptions::with_display_error`] and
398    /// will return an error on formatting issue
399    pub fn write(&self, s: &mut dyn Write) -> Result<(), ArrowError> {
400        match self.formatter.format.write(self.idx, s) {
401            Ok(_) => Ok(()),
402            Err(FormatError::Arrow(e)) => Err(e),
403            Err(FormatError::Format(_)) => Err(ArrowError::CastError("Format error".to_string())),
404        }
405    }
406
407    /// Fallibly converts this to a string
408    pub fn try_to_string(&self) -> Result<String, ArrowError> {
409        let mut s = String::new();
410        self.write(&mut s)?;
411        Ok(s)
412    }
413}
414
415impl Display for ValueFormatter<'_> {
416    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
417        match self.formatter.format.write(self.idx, f) {
418            Ok(()) => Ok(()),
419            Err(FormatError::Arrow(e)) if self.formatter.safe => {
420                write!(f, "ERROR: {e}")
421            }
422            Err(_) => Err(std::fmt::Error),
423        }
424    }
425}
426
427/// A string formatter for an [`Array`]
428///
429/// This can be used with [`std::write`] to write type-erased `dyn Array`
430///
431/// ```
432/// # use std::fmt::{Display, Formatter, Write};
433/// # use arrow_array::{Array, ArrayRef, Int32Array};
434/// # use arrow_cast::display::{ArrayFormatter, FormatOptions};
435/// # use arrow_schema::ArrowError;
436/// struct MyContainer {
437///     values: ArrayRef,
438/// }
439///
440/// impl Display for MyContainer {
441///     fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
442///         let options = FormatOptions::default();
443///         let formatter = ArrayFormatter::try_new(self.values.as_ref(), &options)
444///             .map_err(|_| std::fmt::Error)?;
445///
446///         let mut iter = 0..self.values.len();
447///         if let Some(idx) = iter.next() {
448///             write!(f, "{}", formatter.value(idx))?;
449///         }
450///         for idx in iter {
451///             write!(f, ", {}", formatter.value(idx))?;
452///         }
453///         Ok(())
454///     }
455/// }
456/// ```
457///
458/// [`ValueFormatter::write`] can also be used to get a semantic error, instead of the
459/// opaque [`std::fmt::Error`]
460///
461/// ```
462/// # use std::fmt::Write;
463/// # use arrow_array::Array;
464/// # use arrow_cast::display::{ArrayFormatter, FormatOptions};
465/// # use arrow_schema::ArrowError;
466/// fn format_array(
467///     f: &mut dyn Write,
468///     array: &dyn Array,
469///     options: &FormatOptions,
470/// ) -> Result<(), ArrowError> {
471///     let formatter = ArrayFormatter::try_new(array, options)?;
472///     for i in 0..array.len() {
473///         formatter.value(i).write(f)?
474///     }
475///     Ok(())
476/// }
477/// ```
478///
479pub struct ArrayFormatter<'a> {
480    format: Box<dyn DisplayIndex + 'a>,
481    safe: bool,
482}
483
484impl<'a> ArrayFormatter<'a> {
485    /// Returns an [`ArrayFormatter`] using the provided formatter.
486    pub fn new(format: Box<dyn DisplayIndex + 'a>, safe: bool) -> Self {
487        Self { format, safe }
488    }
489
490    /// Returns an [`ArrayFormatter`] that can be used to format `array`
491    ///
492    /// This returns an error if an array of the given data type cannot be formatted
493    pub fn try_new(array: &'a dyn Array, options: &FormatOptions<'a>) -> Result<Self, ArrowError> {
494        Ok(Self::new(
495            make_default_display_index(array, options)?,
496            options.safe,
497        ))
498    }
499
500    /// Returns a [`ValueFormatter`] that implements [`Display`] for
501    /// the value of the array at `idx`
502    pub fn value(&self, idx: usize) -> ValueFormatter<'_> {
503        ValueFormatter {
504            formatter: self,
505            idx,
506        }
507    }
508}
509
510fn make_default_display_index<'a>(
511    array: &'a dyn Array,
512    options: &FormatOptions<'a>,
513) -> Result<Box<dyn DisplayIndex + 'a>, ArrowError> {
514    downcast_primitive_array! {
515        array => array_format(array, options),
516        DataType::Null => array_format(as_null_array(array), options),
517        DataType::Boolean => array_format(as_boolean_array(array), options),
518        DataType::Utf8 => array_format(array.as_string::<i32>(), options),
519        DataType::LargeUtf8 => array_format(array.as_string::<i64>(), options),
520        DataType::Utf8View => array_format(array.as_string_view(), options),
521        DataType::Binary => array_format(array.as_binary::<i32>(), options),
522        DataType::BinaryView => array_format(array.as_binary_view(), options),
523        DataType::LargeBinary => array_format(array.as_binary::<i64>(), options),
524        DataType::FixedSizeBinary(_) => {
525            let a = array.as_any().downcast_ref::<FixedSizeBinaryArray>().unwrap();
526            array_format(a, options)
527        }
528        DataType::Dictionary(_, _) => downcast_dictionary_array! {
529            array => array_format(array, options),
530            _ => unreachable!()
531        }
532        DataType::List(_) => array_format(as_generic_list_array::<i32>(array), options),
533        DataType::LargeList(_) => array_format(as_generic_list_array::<i64>(array), options),
534        DataType::FixedSizeList(_, _) => {
535            let a = array.as_any().downcast_ref::<FixedSizeListArray>().unwrap();
536            array_format(a, options)
537        }
538        DataType::Struct(_) => array_format(as_struct_array(array), options),
539        DataType::Map(_, _) => array_format(as_map_array(array), options),
540        DataType::Union(_, _) => array_format(as_union_array(array), options),
541        DataType::RunEndEncoded(_, _) => downcast_run_array! {
542            array => array_format(array, options),
543            _ => unreachable!()
544        },
545        d => Err(ArrowError::NotYetImplemented(format!("formatting {d} is not yet supported"))),
546    }
547}
548
549/// Either an [`ArrowError`] or [`std::fmt::Error`]
550pub enum FormatError {
551    /// An error occurred while formatting the array
552    Format(std::fmt::Error),
553    /// An Arrow error occurred while formatting the array.
554    Arrow(ArrowError),
555}
556
557/// The result of formatting an array element via [`DisplayIndex::write`].
558pub type FormatResult = Result<(), FormatError>;
559
560impl From<std::fmt::Error> for FormatError {
561    fn from(value: std::fmt::Error) -> Self {
562        Self::Format(value)
563    }
564}
565
566impl From<ArrowError> for FormatError {
567    fn from(value: ArrowError) -> Self {
568        Self::Arrow(value)
569    }
570}
571
572/// [`Display`] but accepting an index
573pub trait DisplayIndex {
574    /// Write the value of the underlying array at `idx` to `f`.
575    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult;
576}
577
578/// [`DisplayIndex`] with additional state
579trait DisplayIndexState<'a> {
580    type State;
581
582    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError>;
583
584    fn write(&self, state: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult;
585}
586
587impl<'a, T: DisplayIndex> DisplayIndexState<'a> for T {
588    type State = ();
589
590    fn prepare(&self, _options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
591        Ok(())
592    }
593
594    fn write(&self, _: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
595        DisplayIndex::write(self, idx, f)
596    }
597}
598
599struct ArrayFormat<'a, F: DisplayIndexState<'a>> {
600    state: F::State,
601    array: F,
602    null: &'a str,
603}
604
605fn array_format<'a, F>(
606    array: F,
607    options: &FormatOptions<'a>,
608) -> Result<Box<dyn DisplayIndex + 'a>, ArrowError>
609where
610    F: DisplayIndexState<'a> + Array + 'a,
611{
612    let state = array.prepare(options)?;
613    Ok(Box::new(ArrayFormat {
614        state,
615        array,
616        null: options.null,
617    }))
618}
619
620impl<'a, F: DisplayIndexState<'a> + Array> DisplayIndex for ArrayFormat<'a, F> {
621    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
622        if self.array.is_null(idx) {
623            if !self.null.is_empty() {
624                f.write_str(self.null)?
625            }
626            return Ok(());
627        }
628        DisplayIndexState::write(&self.array, &self.state, idx, f)
629    }
630}
631
632impl DisplayIndex for &BooleanArray {
633    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
634        write!(f, "{}", self.value(idx))?;
635        Ok(())
636    }
637}
638
639impl<'a> DisplayIndexState<'a> for &'a NullArray {
640    type State = &'a str;
641
642    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
643        Ok(options.null)
644    }
645
646    fn write(&self, state: &Self::State, _idx: usize, f: &mut dyn Write) -> FormatResult {
647        f.write_str(state)?;
648        Ok(())
649    }
650}
651
652macro_rules! primitive_display {
653    ($($t:ty),+) => {
654        $(impl<'a> DisplayIndex for &'a PrimitiveArray<$t>
655        {
656            fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
657                let value = self.value(idx);
658                let mut buffer = [0u8; <$t as ArrowPrimitiveType>::Native::FORMATTED_SIZE];
659                let b = lexical_core::write(value, &mut buffer);
660                // Lexical core produces valid UTF-8
661                let s = unsafe { std::str::from_utf8_unchecked(b) };
662                f.write_str(s)?;
663                Ok(())
664            }
665        })+
666    };
667}
668
669macro_rules! primitive_display_float {
670    ($($t:ty),+) => {
671        $(impl<'a> DisplayIndex for &'a PrimitiveArray<$t>
672        {
673            fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
674                let value = self.value(idx);
675                let mut buffer = ryu::Buffer::new();
676                f.write_str(buffer.format(value))?;
677                Ok(())
678            }
679        })+
680    };
681}
682
683primitive_display!(Int8Type, Int16Type, Int32Type, Int64Type);
684primitive_display!(UInt8Type, UInt16Type, UInt32Type, UInt64Type);
685primitive_display_float!(Float32Type, Float64Type);
686
687impl DisplayIndex for &PrimitiveArray<Float16Type> {
688    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
689        write!(f, "{}", self.value(idx))?;
690        Ok(())
691    }
692}
693
694macro_rules! decimal_display {
695    ($($t:ty),+) => {
696        $(impl<'a> DisplayIndexState<'a> for &'a PrimitiveArray<$t> {
697            type State = (u8, i8);
698
699            fn prepare(&self, _options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
700                Ok((self.precision(), self.scale()))
701            }
702
703            fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
704                write!(f, "{}", <$t>::format_decimal(self.values()[idx], s.0, s.1))?;
705                Ok(())
706            }
707        })+
708    };
709}
710
711decimal_display!(Decimal32Type, Decimal64Type, Decimal128Type, Decimal256Type);
712
713fn write_timestamp(
714    f: &mut dyn Write,
715    naive: NaiveDateTime,
716    timezone: Option<Tz>,
717    format: Option<&str>,
718) -> FormatResult {
719    match timezone {
720        Some(tz) => {
721            let date = Utc.from_utc_datetime(&naive).with_timezone(&tz);
722            match format {
723                Some(s) => write!(f, "{}", date.format(s))?,
724                None => write!(f, "{}", date.to_rfc3339_opts(SecondsFormat::AutoSi, true))?,
725            }
726        }
727        None => match format {
728            Some(s) => write!(f, "{}", naive.format(s))?,
729            None => write!(f, "{naive:?}")?,
730        },
731    }
732    Ok(())
733}
734
735macro_rules! timestamp_display {
736    ($($t:ty),+) => {
737        $(impl<'a> DisplayIndexState<'a> for &'a PrimitiveArray<$t> {
738            type State = (Option<Tz>, TimeFormat<'a>);
739
740            fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
741                match self.data_type() {
742                    DataType::Timestamp(_, Some(tz)) => Ok((Some(tz.parse()?), options.timestamp_tz_format)),
743                    DataType::Timestamp(_, None) => Ok((None, options.timestamp_format)),
744                    _ => unreachable!(),
745                }
746            }
747
748            fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
749                let value = self.value(idx);
750                let naive = as_datetime::<$t>(value).ok_or_else(|| {
751                    ArrowError::CastError(format!(
752                        "Failed to convert {} to datetime for {}",
753                        value,
754                        self.data_type()
755                    ))
756                })?;
757
758                write_timestamp(f, naive, s.0, s.1.clone())
759            }
760        })+
761    };
762}
763
764timestamp_display!(
765    TimestampSecondType,
766    TimestampMillisecondType,
767    TimestampMicrosecondType,
768    TimestampNanosecondType
769);
770
771macro_rules! temporal_display {
772    ($convert:ident, $format:ident, $t:ty) => {
773        impl<'a> DisplayIndexState<'a> for &'a PrimitiveArray<$t> {
774            type State = TimeFormat<'a>;
775
776            fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
777                Ok(options.$format)
778            }
779
780            fn write(&self, fmt: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
781                let value = self.value(idx);
782                let naive = $convert(value as _).ok_or_else(|| {
783                    ArrowError::CastError(format!(
784                        "Failed to convert {} to temporal for {}",
785                        value,
786                        self.data_type()
787                    ))
788                })?;
789
790                match fmt {
791                    Some(s) => write!(f, "{}", naive.format(s))?,
792                    None => write!(f, "{naive:?}")?,
793                }
794                Ok(())
795            }
796        }
797    };
798}
799
800#[inline]
801fn date32_to_date(value: i32) -> Option<NaiveDate> {
802    Some(date32_to_datetime(value)?.date())
803}
804
805temporal_display!(date32_to_date, date_format, Date32Type);
806temporal_display!(date64_to_datetime, datetime_format, Date64Type);
807temporal_display!(time32s_to_time, time_format, Time32SecondType);
808temporal_display!(time32ms_to_time, time_format, Time32MillisecondType);
809temporal_display!(time64us_to_time, time_format, Time64MicrosecondType);
810temporal_display!(time64ns_to_time, time_format, Time64NanosecondType);
811
812/// Derive [`DisplayIndexState`] for `PrimitiveArray<$t>`
813///
814/// Arguments
815/// * `$convert` - function to convert the value to an `Duration`
816/// * `$t` - [`ArrowPrimitiveType`] of the array
817/// * `$scale` - scale of the duration (passed to `duration_fmt`)
818macro_rules! duration_display {
819    ($convert:ident, $t:ty, $scale:tt) => {
820        impl<'a> DisplayIndexState<'a> for &'a PrimitiveArray<$t> {
821            type State = DurationFormat;
822
823            fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
824                Ok(options.duration_format)
825            }
826
827            fn write(&self, fmt: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
828                let v = self.value(idx);
829                match fmt {
830                    DurationFormat::ISO8601 => write!(f, "{}", $convert(v))?,
831                    DurationFormat::Pretty => duration_fmt!(f, v, $scale)?,
832                }
833                Ok(())
834            }
835        }
836    };
837}
838
839/// Similar to [`duration_display`] but `$convert` returns an `Option`
840macro_rules! duration_option_display {
841    ($convert:ident, $t:ty, $scale:tt) => {
842        impl<'a> DisplayIndexState<'a> for &'a PrimitiveArray<$t> {
843            type State = DurationFormat;
844
845            fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
846                Ok(options.duration_format)
847            }
848
849            fn write(&self, fmt: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
850                let v = self.value(idx);
851                match fmt {
852                    DurationFormat::ISO8601 => match $convert(v) {
853                        Some(td) => write!(f, "{}", td)?,
854                        None => write!(f, "<invalid>")?,
855                    },
856                    DurationFormat::Pretty => match $convert(v) {
857                        Some(_) => duration_fmt!(f, v, $scale)?,
858                        None => write!(f, "<invalid>")?,
859                    },
860                }
861                Ok(())
862            }
863        }
864    };
865}
866
867macro_rules! duration_fmt {
868    ($f:ident, $v:expr, 0) => {{
869        let secs = $v;
870        let mins = secs / 60;
871        let hours = mins / 60;
872        let days = hours / 24;
873
874        let secs = secs - (mins * 60);
875        let mins = mins - (hours * 60);
876        let hours = hours - (days * 24);
877        write!($f, "{days} days {hours} hours {mins} mins {secs} secs")
878    }};
879    ($f:ident, $v:expr, $scale:tt) => {{
880        let subsec = $v;
881        let secs = subsec / 10_i64.pow($scale);
882        let mins = secs / 60;
883        let hours = mins / 60;
884        let days = hours / 24;
885
886        let subsec = subsec - (secs * 10_i64.pow($scale));
887        let secs = secs - (mins * 60);
888        let mins = mins - (hours * 60);
889        let hours = hours - (days * 24);
890        match subsec.is_negative() {
891            true => {
892                write!(
893                    $f,
894                    concat!("{} days {} hours {} mins -{}.{:0", $scale, "} secs"),
895                    days,
896                    hours,
897                    mins,
898                    secs.abs(),
899                    subsec.abs()
900                )
901            }
902            false => {
903                write!(
904                    $f,
905                    concat!("{} days {} hours {} mins {}.{:0", $scale, "} secs"),
906                    days, hours, mins, secs, subsec
907                )
908            }
909        }
910    }};
911}
912
913duration_option_display!(try_duration_s_to_duration, DurationSecondType, 0);
914duration_option_display!(try_duration_ms_to_duration, DurationMillisecondType, 3);
915duration_display!(duration_us_to_duration, DurationMicrosecondType, 6);
916duration_display!(duration_ns_to_duration, DurationNanosecondType, 9);
917
918impl DisplayIndex for &PrimitiveArray<IntervalYearMonthType> {
919    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
920        let interval = self.value(idx) as f64;
921        let years = (interval / 12_f64).floor();
922        let month = interval - (years * 12_f64);
923
924        write!(f, "{years} years {month} mons",)?;
925        Ok(())
926    }
927}
928
929impl DisplayIndex for &PrimitiveArray<IntervalDayTimeType> {
930    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
931        let value = self.value(idx);
932        let mut prefix = "";
933
934        if value.days != 0 {
935            write!(f, "{prefix}{} days", value.days)?;
936            prefix = " ";
937        }
938
939        if value.milliseconds != 0 {
940            let millis_fmt = MillisecondsFormatter {
941                milliseconds: value.milliseconds,
942                prefix,
943            };
944
945            f.write_fmt(format_args!("{millis_fmt}"))?;
946        }
947
948        Ok(())
949    }
950}
951
952impl DisplayIndex for &PrimitiveArray<IntervalMonthDayNanoType> {
953    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
954        let value = self.value(idx);
955        let mut prefix = "";
956
957        if value.months != 0 {
958            write!(f, "{prefix}{} mons", value.months)?;
959            prefix = " ";
960        }
961
962        if value.days != 0 {
963            write!(f, "{prefix}{} days", value.days)?;
964            prefix = " ";
965        }
966
967        if value.nanoseconds != 0 {
968            let nano_fmt = NanosecondsFormatter {
969                nanoseconds: value.nanoseconds,
970                prefix,
971            };
972            f.write_fmt(format_args!("{nano_fmt}"))?;
973        }
974
975        Ok(())
976    }
977}
978
979struct NanosecondsFormatter<'a> {
980    nanoseconds: i64,
981    prefix: &'a str,
982}
983
984impl Display for NanosecondsFormatter<'_> {
985    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
986        let mut prefix = self.prefix;
987
988        let secs = self.nanoseconds / 1_000_000_000;
989        let mins = secs / 60;
990        let hours = mins / 60;
991
992        let secs = secs - (mins * 60);
993        let mins = mins - (hours * 60);
994
995        let nanoseconds = self.nanoseconds % 1_000_000_000;
996
997        if hours != 0 {
998            write!(f, "{prefix}{hours} hours")?;
999            prefix = " ";
1000        }
1001
1002        if mins != 0 {
1003            write!(f, "{prefix}{mins} mins")?;
1004            prefix = " ";
1005        }
1006
1007        if secs != 0 || nanoseconds != 0 {
1008            let secs_sign = if secs < 0 || nanoseconds < 0 { "-" } else { "" };
1009            write!(
1010                f,
1011                "{prefix}{}{}.{:09} secs",
1012                secs_sign,
1013                secs.abs(),
1014                nanoseconds.abs()
1015            )?;
1016        }
1017
1018        Ok(())
1019    }
1020}
1021
1022struct MillisecondsFormatter<'a> {
1023    milliseconds: i32,
1024    prefix: &'a str,
1025}
1026
1027impl Display for MillisecondsFormatter<'_> {
1028    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
1029        let mut prefix = self.prefix;
1030
1031        let secs = self.milliseconds / 1_000;
1032        let mins = secs / 60;
1033        let hours = mins / 60;
1034
1035        let secs = secs - (mins * 60);
1036        let mins = mins - (hours * 60);
1037
1038        let milliseconds = self.milliseconds % 1_000;
1039
1040        if hours != 0 {
1041            write!(f, "{prefix}{hours} hours")?;
1042            prefix = " ";
1043        }
1044
1045        if mins != 0 {
1046            write!(f, "{prefix}{mins} mins")?;
1047            prefix = " ";
1048        }
1049
1050        if secs != 0 || milliseconds != 0 {
1051            let secs_sign = if secs < 0 || milliseconds < 0 {
1052                "-"
1053            } else {
1054                ""
1055            };
1056
1057            write!(
1058                f,
1059                "{prefix}{}{}.{:03} secs",
1060                secs_sign,
1061                secs.abs(),
1062                milliseconds.abs()
1063            )?;
1064        }
1065
1066        Ok(())
1067    }
1068}
1069
1070impl<O: OffsetSizeTrait> DisplayIndex for &GenericStringArray<O> {
1071    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1072        write!(f, "{}", self.value(idx))?;
1073        Ok(())
1074    }
1075}
1076
1077impl DisplayIndex for &StringViewArray {
1078    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1079        write!(f, "{}", self.value(idx))?;
1080        Ok(())
1081    }
1082}
1083
1084impl<O: OffsetSizeTrait> DisplayIndex for &GenericBinaryArray<O> {
1085    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1086        let v = self.value(idx);
1087        for byte in v {
1088            write!(f, "{byte:02x}")?;
1089        }
1090        Ok(())
1091    }
1092}
1093
1094impl DisplayIndex for &BinaryViewArray {
1095    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1096        let v = self.value(idx);
1097        for byte in v {
1098            write!(f, "{byte:02x}")?;
1099        }
1100        Ok(())
1101    }
1102}
1103
1104impl DisplayIndex for &FixedSizeBinaryArray {
1105    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1106        let v = self.value(idx);
1107        for byte in v {
1108            write!(f, "{byte:02x}")?;
1109        }
1110        Ok(())
1111    }
1112}
1113
1114impl<'a, K: ArrowDictionaryKeyType> DisplayIndexState<'a> for &'a DictionaryArray<K> {
1115    type State = Box<dyn DisplayIndex + 'a>;
1116
1117    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1118        make_default_display_index(self.values().as_ref(), options)
1119    }
1120
1121    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1122        let value_idx = self.keys().values()[idx].as_usize();
1123        s.as_ref().write(value_idx, f)
1124    }
1125}
1126
1127impl<'a, K: RunEndIndexType> DisplayIndexState<'a> for &'a RunArray<K> {
1128    type State = ArrayFormatter<'a>;
1129
1130    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1131        let field = match (*self).data_type() {
1132            DataType::RunEndEncoded(_, values_field) => values_field,
1133            _ => unreachable!(),
1134        };
1135        make_array_formatter(self.values().as_ref(), options, Some(field))
1136    }
1137
1138    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1139        let value_idx = self.get_physical_index(idx);
1140        write!(f, "{}", s.value(value_idx))?;
1141        Ok(())
1142    }
1143}
1144
1145fn write_list(
1146    f: &mut dyn Write,
1147    mut range: Range<usize>,
1148    values: &ArrayFormatter<'_>,
1149) -> FormatResult {
1150    f.write_char('[')?;
1151    if let Some(idx) = range.next() {
1152        write!(f, "{}", values.value(idx))?;
1153    }
1154    for idx in range {
1155        write!(f, ", {}", values.value(idx))?;
1156    }
1157    f.write_char(']')?;
1158    Ok(())
1159}
1160
1161impl<'a, O: OffsetSizeTrait> DisplayIndexState<'a> for &'a GenericListArray<O> {
1162    type State = ArrayFormatter<'a>;
1163
1164    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1165        let field = match (*self).data_type() {
1166            DataType::List(f) => f,
1167            DataType::LargeList(f) => f,
1168            _ => unreachable!(),
1169        };
1170        make_array_formatter(self.values().as_ref(), options, Some(field.as_ref()))
1171    }
1172
1173    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1174        let offsets = self.value_offsets();
1175        let end = offsets[idx + 1].as_usize();
1176        let start = offsets[idx].as_usize();
1177        write_list(f, start..end, s)
1178    }
1179}
1180
1181impl<'a> DisplayIndexState<'a> for &'a FixedSizeListArray {
1182    type State = (usize, ArrayFormatter<'a>);
1183
1184    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1185        let field = match (*self).data_type() {
1186            DataType::FixedSizeList(f, _) => f,
1187            _ => unreachable!(),
1188        };
1189        let formatter =
1190            make_array_formatter(self.values().as_ref(), options, Some(field.as_ref()))?;
1191        let length = self.value_length();
1192        Ok((length as usize, formatter))
1193    }
1194
1195    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1196        let start = idx * s.0;
1197        let end = start + s.0;
1198        write_list(f, start..end, &s.1)
1199    }
1200}
1201
1202/// Pairs an [`ArrayFormatter`] with its field name
1203type FieldDisplay<'a> = (&'a str, ArrayFormatter<'a>);
1204
1205impl<'a> DisplayIndexState<'a> for &'a StructArray {
1206    type State = Vec<FieldDisplay<'a>>;
1207
1208    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1209        let fields = match (*self).data_type() {
1210            DataType::Struct(f) => f,
1211            _ => unreachable!(),
1212        };
1213
1214        self.columns()
1215            .iter()
1216            .zip(fields)
1217            .map(|(a, f)| {
1218                let format = make_array_formatter(a.as_ref(), options, Some(f))?;
1219                Ok((f.name().as_str(), format))
1220            })
1221            .collect()
1222    }
1223
1224    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1225        let mut iter = s.iter();
1226        f.write_char('{')?;
1227        if let Some((name, display)) = iter.next() {
1228            write!(f, "{name}: {}", display.value(idx))?;
1229        }
1230        for (name, display) in iter {
1231            write!(f, ", {name}: {}", display.value(idx))?;
1232        }
1233        f.write_char('}')?;
1234        Ok(())
1235    }
1236}
1237
1238impl<'a> DisplayIndexState<'a> for &'a MapArray {
1239    type State = (ArrayFormatter<'a>, ArrayFormatter<'a>);
1240
1241    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1242        let (key_field, value_field) = (*self).entries_fields();
1243
1244        let keys = make_array_formatter(self.keys().as_ref(), options, Some(key_field))?;
1245        let values = make_array_formatter(self.values().as_ref(), options, Some(value_field))?;
1246        Ok((keys, values))
1247    }
1248
1249    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1250        let offsets = self.value_offsets();
1251        let end = offsets[idx + 1].as_usize();
1252        let start = offsets[idx].as_usize();
1253        let mut iter = start..end;
1254
1255        f.write_char('{')?;
1256        if let Some(idx) = iter.next() {
1257            write!(f, "{}: {}", s.0.value(idx), s.1.value(idx))?;
1258        }
1259
1260        for idx in iter {
1261            write!(f, ", {}", s.0.value(idx))?;
1262            write!(f, ": {}", s.1.value(idx))?;
1263        }
1264
1265        f.write_char('}')?;
1266        Ok(())
1267    }
1268}
1269
1270impl<'a> DisplayIndexState<'a> for &'a UnionArray {
1271    type State = (Vec<Option<FieldDisplay<'a>>>, UnionMode);
1272
1273    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1274        let (fields, mode) = match (*self).data_type() {
1275            DataType::Union(fields, mode) => (fields, mode),
1276            _ => unreachable!(),
1277        };
1278
1279        let max_id = fields.iter().map(|(id, _)| id).max().unwrap_or_default() as usize;
1280        let mut out: Vec<Option<FieldDisplay>> = (0..max_id + 1).map(|_| None).collect();
1281        for (i, field) in fields.iter() {
1282            let formatter = make_array_formatter(self.child(i).as_ref(), options, Some(field))?;
1283            out[i as usize] = Some((field.name().as_str(), formatter))
1284        }
1285        Ok((out, *mode))
1286    }
1287
1288    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1289        let id = self.type_id(idx);
1290        let idx = match s.1 {
1291            UnionMode::Dense => self.value_offset(idx),
1292            UnionMode::Sparse => idx,
1293        };
1294        let (name, field) = s.0[id as usize].as_ref().unwrap();
1295
1296        write!(f, "{{{name}={}}}", field.value(idx))?;
1297        Ok(())
1298    }
1299}
1300
1301/// Get the value at the given row in an array as a String.
1302///
1303/// Note this function is quite inefficient and is unlikely to be
1304/// suitable for converting large arrays or record batches.
1305///
1306/// Please see [`ArrayFormatter`] for a more performant interface
1307pub fn array_value_to_string(column: &dyn Array, row: usize) -> Result<String, ArrowError> {
1308    let options = FormatOptions::default().with_display_error(true);
1309    let formatter = ArrayFormatter::try_new(column, &options)?;
1310    Ok(formatter.value(row).to_string())
1311}
1312
1313/// Converts numeric type to a `String`
1314pub fn lexical_to_string<N: lexical_core::ToLexical>(n: N) -> String {
1315    let mut buf = Vec::<u8>::with_capacity(N::FORMATTED_SIZE_DECIMAL);
1316    unsafe {
1317        // JUSTIFICATION
1318        //  Benefit
1319        //      Allows using the faster serializer lexical core and convert to string
1320        //  Soundness
1321        //      Length of buf is set as written length afterwards. lexical_core
1322        //      creates a valid string, so doesn't need to be checked.
1323        let slice = std::slice::from_raw_parts_mut(buf.as_mut_ptr(), buf.capacity());
1324        let len = lexical_core::write(n, slice).len();
1325        buf.set_len(len);
1326        String::from_utf8_unchecked(buf)
1327    }
1328}
1329
1330#[cfg(test)]
1331mod tests {
1332    use super::*;
1333    use arrow_array::builder::StringRunBuilder;
1334
1335    /// Test to verify options can be constant. See #4580
1336    const TEST_CONST_OPTIONS: FormatOptions<'static> = FormatOptions::new()
1337        .with_date_format(Some("foo"))
1338        .with_timestamp_format(Some("404"));
1339
1340    #[test]
1341    fn test_const_options() {
1342        assert_eq!(TEST_CONST_OPTIONS.date_format, Some("foo"));
1343    }
1344
1345    /// See https://github.com/apache/arrow-rs/issues/8875
1346    #[test]
1347    fn test_options_send_sync() {
1348        fn assert_send_sync<T>()
1349        where
1350            T: Send + Sync,
1351        {
1352            // nothing – the compiler does the work
1353        }
1354
1355        assert_send_sync::<FormatOptions<'static>>();
1356    }
1357
1358    #[test]
1359    fn test_map_array_to_string() {
1360        let keys = vec!["a", "b", "c", "d", "e", "f", "g", "h"];
1361        let values_data = UInt32Array::from(vec![0u32, 10, 20, 30, 40, 50, 60, 70]);
1362
1363        // Construct a buffer for value offsets, for the nested array:
1364        //  [[a, b, c], [d, e, f], [g, h]]
1365        let entry_offsets = [0, 3, 6, 8];
1366
1367        let map_array =
1368            MapArray::new_from_strings(keys.clone().into_iter(), &values_data, &entry_offsets)
1369                .unwrap();
1370        assert_eq!(
1371            "{d: 30, e: 40, f: 50}",
1372            array_value_to_string(&map_array, 1).unwrap()
1373        );
1374    }
1375
1376    fn format_array(array: &dyn Array, fmt: &FormatOptions) -> Vec<String> {
1377        let fmt = ArrayFormatter::try_new(array, fmt).unwrap();
1378        (0..array.len()).map(|x| fmt.value(x).to_string()).collect()
1379    }
1380
1381    #[test]
1382    fn test_array_value_to_string_duration() {
1383        let iso_fmt = FormatOptions::new();
1384        let pretty_fmt = FormatOptions::new().with_duration_format(DurationFormat::Pretty);
1385
1386        let array = DurationNanosecondArray::from(vec![
1387            1,
1388            -1,
1389            1000,
1390            -1000,
1391            (45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000_000 + 123456789,
1392            -(45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000_000 - 123456789,
1393        ]);
1394        let iso = format_array(&array, &iso_fmt);
1395        let pretty = format_array(&array, &pretty_fmt);
1396
1397        assert_eq!(iso[0], "PT0.000000001S");
1398        assert_eq!(pretty[0], "0 days 0 hours 0 mins 0.000000001 secs");
1399        assert_eq!(iso[1], "-PT0.000000001S");
1400        assert_eq!(pretty[1], "0 days 0 hours 0 mins -0.000000001 secs");
1401        assert_eq!(iso[2], "PT0.000001S");
1402        assert_eq!(pretty[2], "0 days 0 hours 0 mins 0.000001000 secs");
1403        assert_eq!(iso[3], "-PT0.000001S");
1404        assert_eq!(pretty[3], "0 days 0 hours 0 mins -0.000001000 secs");
1405        assert_eq!(iso[4], "PT3938554.123456789S");
1406        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34.123456789 secs");
1407        assert_eq!(iso[5], "-PT3938554.123456789S");
1408        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34.123456789 secs");
1409
1410        let array = DurationMicrosecondArray::from(vec![
1411            1,
1412            -1,
1413            1000,
1414            -1000,
1415            (45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000 + 123456,
1416            -(45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000 - 123456,
1417        ]);
1418        let iso = format_array(&array, &iso_fmt);
1419        let pretty = format_array(&array, &pretty_fmt);
1420
1421        assert_eq!(iso[0], "PT0.000001S");
1422        assert_eq!(pretty[0], "0 days 0 hours 0 mins 0.000001 secs");
1423        assert_eq!(iso[1], "-PT0.000001S");
1424        assert_eq!(pretty[1], "0 days 0 hours 0 mins -0.000001 secs");
1425        assert_eq!(iso[2], "PT0.001S");
1426        assert_eq!(pretty[2], "0 days 0 hours 0 mins 0.001000 secs");
1427        assert_eq!(iso[3], "-PT0.001S");
1428        assert_eq!(pretty[3], "0 days 0 hours 0 mins -0.001000 secs");
1429        assert_eq!(iso[4], "PT3938554.123456S");
1430        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34.123456 secs");
1431        assert_eq!(iso[5], "-PT3938554.123456S");
1432        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34.123456 secs");
1433
1434        let array = DurationMillisecondArray::from(vec![
1435            1,
1436            -1,
1437            1000,
1438            -1000,
1439            (45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000 + 123,
1440            -(45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000 - 123,
1441        ]);
1442        let iso = format_array(&array, &iso_fmt);
1443        let pretty = format_array(&array, &pretty_fmt);
1444
1445        assert_eq!(iso[0], "PT0.001S");
1446        assert_eq!(pretty[0], "0 days 0 hours 0 mins 0.001 secs");
1447        assert_eq!(iso[1], "-PT0.001S");
1448        assert_eq!(pretty[1], "0 days 0 hours 0 mins -0.001 secs");
1449        assert_eq!(iso[2], "PT1S");
1450        assert_eq!(pretty[2], "0 days 0 hours 0 mins 1.000 secs");
1451        assert_eq!(iso[3], "-PT1S");
1452        assert_eq!(pretty[3], "0 days 0 hours 0 mins -1.000 secs");
1453        assert_eq!(iso[4], "PT3938554.123S");
1454        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34.123 secs");
1455        assert_eq!(iso[5], "-PT3938554.123S");
1456        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34.123 secs");
1457
1458        let array = DurationSecondArray::from(vec![
1459            1,
1460            -1,
1461            1000,
1462            -1000,
1463            45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34,
1464            -45 * 60 * 60 * 24 - 14 * 60 * 60 - 2 * 60 - 34,
1465        ]);
1466        let iso = format_array(&array, &iso_fmt);
1467        let pretty = format_array(&array, &pretty_fmt);
1468
1469        assert_eq!(iso[0], "PT1S");
1470        assert_eq!(pretty[0], "0 days 0 hours 0 mins 1 secs");
1471        assert_eq!(iso[1], "-PT1S");
1472        assert_eq!(pretty[1], "0 days 0 hours 0 mins -1 secs");
1473        assert_eq!(iso[2], "PT1000S");
1474        assert_eq!(pretty[2], "0 days 0 hours 16 mins 40 secs");
1475        assert_eq!(iso[3], "-PT1000S");
1476        assert_eq!(pretty[3], "0 days 0 hours -16 mins -40 secs");
1477        assert_eq!(iso[4], "PT3938554S");
1478        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34 secs");
1479        assert_eq!(iso[5], "-PT3938554S");
1480        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34 secs");
1481    }
1482
1483    #[test]
1484    fn test_null() {
1485        let array = NullArray::new(2);
1486        let options = FormatOptions::new().with_null("NULL");
1487        let formatted = format_array(&array, &options);
1488        assert_eq!(formatted, &["NULL".to_string(), "NULL".to_string()])
1489    }
1490
1491    #[test]
1492    fn test_string_run_arry_to_string() {
1493        let mut builder = StringRunBuilder::<Int32Type>::new();
1494
1495        builder.append_value("input_value");
1496        builder.append_value("input_value");
1497        builder.append_value("input_value");
1498        builder.append_value("input_value1");
1499
1500        let map_array = builder.finish();
1501        assert_eq!("input_value", array_value_to_string(&map_array, 1).unwrap());
1502        assert_eq!(
1503            "input_value1",
1504            array_value_to_string(&map_array, 3).unwrap()
1505        );
1506    }
1507}
arrow_cast/display.rs

arrow_cast/
display.rs
