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
933        if value.is_zero() {
934            write!(f, "0 secs")?;
935            return Ok(());
936        }
937
938        let mut prefix = "";
939
940        if value.days != 0 {
941            write!(f, "{prefix}{} days", value.days)?;
942            prefix = " ";
943        }
944
945        if value.milliseconds != 0 {
946            let millis_fmt = MillisecondsFormatter {
947                milliseconds: value.milliseconds,
948                prefix,
949            };
950
951            f.write_fmt(format_args!("{millis_fmt}"))?;
952        }
953
954        Ok(())
955    }
956}
957
958impl DisplayIndex for &PrimitiveArray<IntervalMonthDayNanoType> {
959    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
960        let value = self.value(idx);
961
962        if value.is_zero() {
963            write!(f, "0 secs")?;
964            return Ok(());
965        }
966
967        let mut prefix = "";
968
969        if value.months != 0 {
970            write!(f, "{prefix}{} mons", value.months)?;
971            prefix = " ";
972        }
973
974        if value.days != 0 {
975            write!(f, "{prefix}{} days", value.days)?;
976            prefix = " ";
977        }
978
979        if value.nanoseconds != 0 {
980            let nano_fmt = NanosecondsFormatter {
981                nanoseconds: value.nanoseconds,
982                prefix,
983            };
984            f.write_fmt(format_args!("{nano_fmt}"))?;
985        }
986
987        Ok(())
988    }
989}
990
991struct NanosecondsFormatter<'a> {
992    nanoseconds: i64,
993    prefix: &'a str,
994}
995
996impl Display for NanosecondsFormatter<'_> {
997    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
998        let mut prefix = self.prefix;
999
1000        let secs = self.nanoseconds / 1_000_000_000;
1001        let mins = secs / 60;
1002        let hours = mins / 60;
1003
1004        let secs = secs - (mins * 60);
1005        let mins = mins - (hours * 60);
1006
1007        let nanoseconds = self.nanoseconds % 1_000_000_000;
1008
1009        if hours != 0 {
1010            write!(f, "{prefix}{hours} hours")?;
1011            prefix = " ";
1012        }
1013
1014        if mins != 0 {
1015            write!(f, "{prefix}{mins} mins")?;
1016            prefix = " ";
1017        }
1018
1019        if secs != 0 || nanoseconds != 0 {
1020            let secs_sign = if secs < 0 || nanoseconds < 0 { "-" } else { "" };
1021            write!(
1022                f,
1023                "{prefix}{}{}.{:09} secs",
1024                secs_sign,
1025                secs.abs(),
1026                nanoseconds.abs()
1027            )?;
1028        }
1029
1030        Ok(())
1031    }
1032}
1033
1034struct MillisecondsFormatter<'a> {
1035    milliseconds: i32,
1036    prefix: &'a str,
1037}
1038
1039impl Display for MillisecondsFormatter<'_> {
1040    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
1041        let mut prefix = self.prefix;
1042
1043        let secs = self.milliseconds / 1_000;
1044        let mins = secs / 60;
1045        let hours = mins / 60;
1046
1047        let secs = secs - (mins * 60);
1048        let mins = mins - (hours * 60);
1049
1050        let milliseconds = self.milliseconds % 1_000;
1051
1052        if hours != 0 {
1053            write!(f, "{prefix}{hours} hours")?;
1054            prefix = " ";
1055        }
1056
1057        if mins != 0 {
1058            write!(f, "{prefix}{mins} mins")?;
1059            prefix = " ";
1060        }
1061
1062        if secs != 0 || milliseconds != 0 {
1063            let secs_sign = if secs < 0 || milliseconds < 0 {
1064                "-"
1065            } else {
1066                ""
1067            };
1068
1069            write!(
1070                f,
1071                "{prefix}{}{}.{:03} secs",
1072                secs_sign,
1073                secs.abs(),
1074                milliseconds.abs()
1075            )?;
1076        }
1077
1078        Ok(())
1079    }
1080}
1081
1082impl<O: OffsetSizeTrait> DisplayIndex for &GenericStringArray<O> {
1083    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1084        write!(f, "{}", self.value(idx))?;
1085        Ok(())
1086    }
1087}
1088
1089impl DisplayIndex for &StringViewArray {
1090    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1091        write!(f, "{}", self.value(idx))?;
1092        Ok(())
1093    }
1094}
1095
1096impl<O: OffsetSizeTrait> DisplayIndex for &GenericBinaryArray<O> {
1097    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1098        let v = self.value(idx);
1099        for byte in v {
1100            write!(f, "{byte:02x}")?;
1101        }
1102        Ok(())
1103    }
1104}
1105
1106impl DisplayIndex for &BinaryViewArray {
1107    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1108        let v = self.value(idx);
1109        for byte in v {
1110            write!(f, "{byte:02x}")?;
1111        }
1112        Ok(())
1113    }
1114}
1115
1116impl DisplayIndex for &FixedSizeBinaryArray {
1117    fn write(&self, idx: usize, f: &mut dyn Write) -> FormatResult {
1118        let v = self.value(idx);
1119        for byte in v {
1120            write!(f, "{byte:02x}")?;
1121        }
1122        Ok(())
1123    }
1124}
1125
1126impl<'a, K: ArrowDictionaryKeyType> DisplayIndexState<'a> for &'a DictionaryArray<K> {
1127    type State = Box<dyn DisplayIndex + 'a>;
1128
1129    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1130        make_default_display_index(self.values().as_ref(), options)
1131    }
1132
1133    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1134        let value_idx = self.keys().values()[idx].as_usize();
1135        s.as_ref().write(value_idx, f)
1136    }
1137}
1138
1139impl<'a, K: RunEndIndexType> DisplayIndexState<'a> for &'a RunArray<K> {
1140    type State = ArrayFormatter<'a>;
1141
1142    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1143        let field = match (*self).data_type() {
1144            DataType::RunEndEncoded(_, values_field) => values_field,
1145            _ => unreachable!(),
1146        };
1147        make_array_formatter(self.values().as_ref(), options, Some(field))
1148    }
1149
1150    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1151        let value_idx = self.get_physical_index(idx);
1152        write!(f, "{}", s.value(value_idx))?;
1153        Ok(())
1154    }
1155}
1156
1157fn write_list(
1158    f: &mut dyn Write,
1159    mut range: Range<usize>,
1160    values: &ArrayFormatter<'_>,
1161) -> FormatResult {
1162    f.write_char('[')?;
1163    if let Some(idx) = range.next() {
1164        write!(f, "{}", values.value(idx))?;
1165    }
1166    for idx in range {
1167        write!(f, ", {}", values.value(idx))?;
1168    }
1169    f.write_char(']')?;
1170    Ok(())
1171}
1172
1173impl<'a, O: OffsetSizeTrait> DisplayIndexState<'a> for &'a GenericListArray<O> {
1174    type State = ArrayFormatter<'a>;
1175
1176    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1177        let field = match (*self).data_type() {
1178            DataType::List(f) => f,
1179            DataType::LargeList(f) => f,
1180            _ => unreachable!(),
1181        };
1182        make_array_formatter(self.values().as_ref(), options, Some(field.as_ref()))
1183    }
1184
1185    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1186        let offsets = self.value_offsets();
1187        let end = offsets[idx + 1].as_usize();
1188        let start = offsets[idx].as_usize();
1189        write_list(f, start..end, s)
1190    }
1191}
1192
1193impl<'a> DisplayIndexState<'a> for &'a FixedSizeListArray {
1194    type State = (usize, ArrayFormatter<'a>);
1195
1196    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1197        let field = match (*self).data_type() {
1198            DataType::FixedSizeList(f, _) => f,
1199            _ => unreachable!(),
1200        };
1201        let formatter =
1202            make_array_formatter(self.values().as_ref(), options, Some(field.as_ref()))?;
1203        let length = self.value_length();
1204        Ok((length as usize, formatter))
1205    }
1206
1207    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1208        let start = idx * s.0;
1209        let end = start + s.0;
1210        write_list(f, start..end, &s.1)
1211    }
1212}
1213
1214/// Pairs an [`ArrayFormatter`] with its field name
1215type FieldDisplay<'a> = (&'a str, ArrayFormatter<'a>);
1216
1217impl<'a> DisplayIndexState<'a> for &'a StructArray {
1218    type State = Vec<FieldDisplay<'a>>;
1219
1220    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1221        let fields = match (*self).data_type() {
1222            DataType::Struct(f) => f,
1223            _ => unreachable!(),
1224        };
1225
1226        self.columns()
1227            .iter()
1228            .zip(fields)
1229            .map(|(a, f)| {
1230                let format = make_array_formatter(a.as_ref(), options, Some(f))?;
1231                Ok((f.name().as_str(), format))
1232            })
1233            .collect()
1234    }
1235
1236    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1237        let mut iter = s.iter();
1238        f.write_char('{')?;
1239        if let Some((name, display)) = iter.next() {
1240            write!(f, "{name}: {}", display.value(idx))?;
1241        }
1242        for (name, display) in iter {
1243            write!(f, ", {name}: {}", display.value(idx))?;
1244        }
1245        f.write_char('}')?;
1246        Ok(())
1247    }
1248}
1249
1250impl<'a> DisplayIndexState<'a> for &'a MapArray {
1251    type State = (ArrayFormatter<'a>, ArrayFormatter<'a>);
1252
1253    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1254        let (key_field, value_field) = (*self).entries_fields();
1255
1256        let keys = make_array_formatter(self.keys().as_ref(), options, Some(key_field))?;
1257        let values = make_array_formatter(self.values().as_ref(), options, Some(value_field))?;
1258        Ok((keys, values))
1259    }
1260
1261    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1262        let offsets = self.value_offsets();
1263        let end = offsets[idx + 1].as_usize();
1264        let start = offsets[idx].as_usize();
1265        let mut iter = start..end;
1266
1267        f.write_char('{')?;
1268        if let Some(idx) = iter.next() {
1269            write!(f, "{}: {}", s.0.value(idx), s.1.value(idx))?;
1270        }
1271
1272        for idx in iter {
1273            write!(f, ", {}", s.0.value(idx))?;
1274            write!(f, ": {}", s.1.value(idx))?;
1275        }
1276
1277        f.write_char('}')?;
1278        Ok(())
1279    }
1280}
1281
1282impl<'a> DisplayIndexState<'a> for &'a UnionArray {
1283    type State = (Vec<Option<FieldDisplay<'a>>>, UnionMode);
1284
1285    fn prepare(&self, options: &FormatOptions<'a>) -> Result<Self::State, ArrowError> {
1286        let (fields, mode) = match (*self).data_type() {
1287            DataType::Union(fields, mode) => (fields, mode),
1288            _ => unreachable!(),
1289        };
1290
1291        let max_id = fields.iter().map(|(id, _)| id).max().unwrap_or_default() as usize;
1292        let mut out: Vec<Option<FieldDisplay>> = (0..max_id + 1).map(|_| None).collect();
1293        for (i, field) in fields.iter() {
1294            let formatter = make_array_formatter(self.child(i).as_ref(), options, Some(field))?;
1295            out[i as usize] = Some((field.name().as_str(), formatter))
1296        }
1297        Ok((out, *mode))
1298    }
1299
1300    fn write(&self, s: &Self::State, idx: usize, f: &mut dyn Write) -> FormatResult {
1301        let id = self.type_id(idx);
1302        let idx = match s.1 {
1303            UnionMode::Dense => self.value_offset(idx),
1304            UnionMode::Sparse => idx,
1305        };
1306        let (name, field) = s.0[id as usize].as_ref().unwrap();
1307
1308        write!(f, "{{{name}={}}}", field.value(idx))?;
1309        Ok(())
1310    }
1311}
1312
1313/// Get the value at the given row in an array as a String.
1314///
1315/// Note this function is quite inefficient and is unlikely to be
1316/// suitable for converting large arrays or record batches.
1317///
1318/// Please see [`ArrayFormatter`] for a more performant interface
1319pub fn array_value_to_string(column: &dyn Array, row: usize) -> Result<String, ArrowError> {
1320    let options = FormatOptions::default().with_display_error(true);
1321    let formatter = ArrayFormatter::try_new(column, &options)?;
1322    Ok(formatter.value(row).to_string())
1323}
1324
1325/// Converts numeric type to a `String`
1326pub fn lexical_to_string<N: lexical_core::ToLexical>(n: N) -> String {
1327    let mut buf = Vec::<u8>::with_capacity(N::FORMATTED_SIZE_DECIMAL);
1328    unsafe {
1329        // JUSTIFICATION
1330        //  Benefit
1331        //      Allows using the faster serializer lexical core and convert to string
1332        //  Soundness
1333        //      Length of buf is set as written length afterwards. lexical_core
1334        //      creates a valid string, so doesn't need to be checked.
1335        let slice = std::slice::from_raw_parts_mut(buf.as_mut_ptr(), buf.capacity());
1336        let len = lexical_core::write(n, slice).len();
1337        buf.set_len(len);
1338        String::from_utf8_unchecked(buf)
1339    }
1340}
1341
1342#[cfg(test)]
1343mod tests {
1344    use super::*;
1345    use arrow_array::builder::StringRunBuilder;
1346
1347    /// Test to verify options can be constant. See #4580
1348    const TEST_CONST_OPTIONS: FormatOptions<'static> = FormatOptions::new()
1349        .with_date_format(Some("foo"))
1350        .with_timestamp_format(Some("404"));
1351
1352    #[test]
1353    fn test_const_options() {
1354        assert_eq!(TEST_CONST_OPTIONS.date_format, Some("foo"));
1355    }
1356
1357    /// See https://github.com/apache/arrow-rs/issues/8875
1358    #[test]
1359    fn test_options_send_sync() {
1360        fn assert_send_sync<T>()
1361        where
1362            T: Send + Sync,
1363        {
1364            // nothing – the compiler does the work
1365        }
1366
1367        assert_send_sync::<FormatOptions<'static>>();
1368    }
1369
1370    #[test]
1371    fn test_map_array_to_string() {
1372        let keys = vec!["a", "b", "c", "d", "e", "f", "g", "h"];
1373        let values_data = UInt32Array::from(vec![0u32, 10, 20, 30, 40, 50, 60, 70]);
1374
1375        // Construct a buffer for value offsets, for the nested array:
1376        //  [[a, b, c], [d, e, f], [g, h]]
1377        let entry_offsets = [0, 3, 6, 8];
1378
1379        let map_array =
1380            MapArray::new_from_strings(keys.clone().into_iter(), &values_data, &entry_offsets)
1381                .unwrap();
1382        assert_eq!(
1383            "{d: 30, e: 40, f: 50}",
1384            array_value_to_string(&map_array, 1).unwrap()
1385        );
1386    }
1387
1388    fn format_array(array: &dyn Array, fmt: &FormatOptions) -> Vec<String> {
1389        let fmt = ArrayFormatter::try_new(array, fmt).unwrap();
1390        (0..array.len()).map(|x| fmt.value(x).to_string()).collect()
1391    }
1392
1393    #[test]
1394    fn test_array_value_to_string_duration() {
1395        let iso_fmt = FormatOptions::new();
1396        let pretty_fmt = FormatOptions::new().with_duration_format(DurationFormat::Pretty);
1397
1398        let array = DurationNanosecondArray::from(vec![
1399            1,
1400            -1,
1401            1000,
1402            -1000,
1403            (45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000_000 + 123456789,
1404            -(45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000_000 - 123456789,
1405        ]);
1406        let iso = format_array(&array, &iso_fmt);
1407        let pretty = format_array(&array, &pretty_fmt);
1408
1409        assert_eq!(iso[0], "PT0.000000001S");
1410        assert_eq!(pretty[0], "0 days 0 hours 0 mins 0.000000001 secs");
1411        assert_eq!(iso[1], "-PT0.000000001S");
1412        assert_eq!(pretty[1], "0 days 0 hours 0 mins -0.000000001 secs");
1413        assert_eq!(iso[2], "PT0.000001S");
1414        assert_eq!(pretty[2], "0 days 0 hours 0 mins 0.000001000 secs");
1415        assert_eq!(iso[3], "-PT0.000001S");
1416        assert_eq!(pretty[3], "0 days 0 hours 0 mins -0.000001000 secs");
1417        assert_eq!(iso[4], "PT3938554.123456789S");
1418        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34.123456789 secs");
1419        assert_eq!(iso[5], "-PT3938554.123456789S");
1420        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34.123456789 secs");
1421
1422        let array = DurationMicrosecondArray::from(vec![
1423            1,
1424            -1,
1425            1000,
1426            -1000,
1427            (45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000 + 123456,
1428            -(45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000_000 - 123456,
1429        ]);
1430        let iso = format_array(&array, &iso_fmt);
1431        let pretty = format_array(&array, &pretty_fmt);
1432
1433        assert_eq!(iso[0], "PT0.000001S");
1434        assert_eq!(pretty[0], "0 days 0 hours 0 mins 0.000001 secs");
1435        assert_eq!(iso[1], "-PT0.000001S");
1436        assert_eq!(pretty[1], "0 days 0 hours 0 mins -0.000001 secs");
1437        assert_eq!(iso[2], "PT0.001S");
1438        assert_eq!(pretty[2], "0 days 0 hours 0 mins 0.001000 secs");
1439        assert_eq!(iso[3], "-PT0.001S");
1440        assert_eq!(pretty[3], "0 days 0 hours 0 mins -0.001000 secs");
1441        assert_eq!(iso[4], "PT3938554.123456S");
1442        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34.123456 secs");
1443        assert_eq!(iso[5], "-PT3938554.123456S");
1444        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34.123456 secs");
1445
1446        let array = DurationMillisecondArray::from(vec![
1447            1,
1448            -1,
1449            1000,
1450            -1000,
1451            (45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000 + 123,
1452            -(45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34) * 1_000 - 123,
1453        ]);
1454        let iso = format_array(&array, &iso_fmt);
1455        let pretty = format_array(&array, &pretty_fmt);
1456
1457        assert_eq!(iso[0], "PT0.001S");
1458        assert_eq!(pretty[0], "0 days 0 hours 0 mins 0.001 secs");
1459        assert_eq!(iso[1], "-PT0.001S");
1460        assert_eq!(pretty[1], "0 days 0 hours 0 mins -0.001 secs");
1461        assert_eq!(iso[2], "PT1S");
1462        assert_eq!(pretty[2], "0 days 0 hours 0 mins 1.000 secs");
1463        assert_eq!(iso[3], "-PT1S");
1464        assert_eq!(pretty[3], "0 days 0 hours 0 mins -1.000 secs");
1465        assert_eq!(iso[4], "PT3938554.123S");
1466        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34.123 secs");
1467        assert_eq!(iso[5], "-PT3938554.123S");
1468        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34.123 secs");
1469
1470        let array = DurationSecondArray::from(vec![
1471            1,
1472            -1,
1473            1000,
1474            -1000,
1475            45 * 60 * 60 * 24 + 14 * 60 * 60 + 2 * 60 + 34,
1476            -45 * 60 * 60 * 24 - 14 * 60 * 60 - 2 * 60 - 34,
1477        ]);
1478        let iso = format_array(&array, &iso_fmt);
1479        let pretty = format_array(&array, &pretty_fmt);
1480
1481        assert_eq!(iso[0], "PT1S");
1482        assert_eq!(pretty[0], "0 days 0 hours 0 mins 1 secs");
1483        assert_eq!(iso[1], "-PT1S");
1484        assert_eq!(pretty[1], "0 days 0 hours 0 mins -1 secs");
1485        assert_eq!(iso[2], "PT1000S");
1486        assert_eq!(pretty[2], "0 days 0 hours 16 mins 40 secs");
1487        assert_eq!(iso[3], "-PT1000S");
1488        assert_eq!(pretty[3], "0 days 0 hours -16 mins -40 secs");
1489        assert_eq!(iso[4], "PT3938554S");
1490        assert_eq!(pretty[4], "45 days 14 hours 2 mins 34 secs");
1491        assert_eq!(iso[5], "-PT3938554S");
1492        assert_eq!(pretty[5], "-45 days -14 hours -2 mins -34 secs");
1493    }
1494
1495    #[test]
1496    fn test_null() {
1497        let array = NullArray::new(2);
1498        let options = FormatOptions::new().with_null("NULL");
1499        let formatted = format_array(&array, &options);
1500        assert_eq!(formatted, &["NULL".to_string(), "NULL".to_string()])
1501    }
1502
1503    #[test]
1504    fn test_string_run_arry_to_string() {
1505        let mut builder = StringRunBuilder::<Int32Type>::new();
1506
1507        builder.append_value("input_value");
1508        builder.append_value("input_value");
1509        builder.append_value("input_value");
1510        builder.append_value("input_value1");
1511
1512        let map_array = builder.finish();
1513        assert_eq!("input_value", array_value_to_string(&map_array, 1).unwrap());
1514        assert_eq!(
1515            "input_value1",
1516            array_value_to_string(&map_array, 3).unwrap()
1517        );
1518    }
1519}
arrow_cast/display.rs

arrow_cast/
display.rs
