Skip to main content

vortex_array/display/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4mod extractor;
5mod extractors;
6mod tree_display;
7
8use std::fmt::Display;
9use std::iter::repeat_n;
10
11pub use extractor::IndentedFormatter;
12pub use extractor::TreeContext;
13pub use extractor::TreeExtractor;
14pub use extractors::BufferExtractor;
15pub use extractors::EncodingSummaryExtractor;
16pub use extractors::MetadataExtractor;
17pub use extractors::NbytesExtractor;
18pub use extractors::StatsExtractor;
19use itertools::Itertools as _;
20pub use tree_display::TreeDisplay;
21
22use crate::ArrayRef;
23use crate::ExecutionCtx;
24
25/// Describe how to convert an array to a string.
26///
27/// See also:
28/// [Array::display_as](../trait.Array.html#method.display_as)
29/// and [DisplayArrayAs].
30pub enum DisplayOptions {
31    /// Only the top-level encoding id and limited metadata: `vortex.primitive(i16, len=5)`.
32    ///
33    /// ```
34    /// # use vortex_session::VortexSession;
35    /// # use vortex_array::VortexSessionExecute;
36    /// # let ctx = VortexSession::empty().create_execution_ctx();
37    /// # use vortex_array::display::DisplayOptions;
38    /// # use vortex_array::IntoArray;
39    /// # use vortex_buffer::buffer;
40    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
41    /// assert_eq!(
42    ///     format!("{}", array.display_as(DisplayOptions::MetadataOnly, &ctx)),
43    ///     "vortex.primitive(i16, len=5)",
44    /// );
45    /// ```
46    MetadataOnly,
47    /// Only the logical values of the array: `[0i16, 1i16, 2i16, 3i16, 4i16]`.
48    ///
49    /// ```
50    /// # use vortex_session::VortexSession;
51    /// # use vortex_array::VortexSessionExecute;
52    /// # let ctx = VortexSession::empty().create_execution_ctx();
53    /// # use vortex_array::display::DisplayOptions;
54    /// # use vortex_array::IntoArray;
55    /// # use vortex_buffer::buffer;
56    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
57    /// assert_eq!(
58    ///     format!("{}", array.display_as(DisplayOptions::default(), &ctx)),
59    ///     "[0i16, 1i16, 2i16, 3i16, 4i16]",
60    /// );
61    /// assert_eq!(
62    ///     format!("{}", array.display_as(DisplayOptions::default(), &ctx)),
63    ///     format!("{}", array.display_values(&ctx)),
64    /// );
65    /// ```
66    CommaSeparatedScalars { omit_comma_after_space: bool },
67    /// The tree of encodings without any concrete values.
68    ///
69    /// With buffers, metadata, and stats:
70    ///
71    /// ```
72    /// # use vortex_session::VortexSession;
73    /// # use vortex_array::VortexSessionExecute;
74    /// # let ctx = VortexSession::empty().create_execution_ctx();
75    /// # use vortex_array::display::DisplayOptions;
76    /// # use vortex_array::IntoArray;
77    /// # use vortex_buffer::buffer;
78    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
79    /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
80    ///   metadata: ptype: i16
81    ///   buffer: values host 10 B (align=2) (100.00%)
82    /// ";
83    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: true }, &ctx)), expected);
84    ///
85    /// # use vortex_array::arrays::StructArray;
86    /// let array = StructArray::from_fields(&[
87    ///     ("x", buffer![1, 2].into_array()),
88    ///     ("y", buffer![3, 4].into_array()),
89    /// ]).unwrap().into_array();
90    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
91    ///   metadata:\x20
92    ///   x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
93    ///     metadata: ptype: i32
94    ///     buffer: values host 8 B (align=4) (100.00%)
95    ///   y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
96    ///     metadata: ptype: i32
97    ///     buffer: values host 8 B (align=4) (100.00%)
98    /// ";
99    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: true }, &ctx)), expected);
100    /// ```
101    ///
102    /// With metadata and stats but no buffers:
103    ///
104    /// ```
105    /// # use vortex_session::VortexSession;
106    /// # use vortex_array::VortexSessionExecute;
107    /// # let ctx = VortexSession::empty().create_execution_ctx();
108    /// # use vortex_array::display::DisplayOptions;
109    /// # use vortex_array::IntoArray;
110    /// # use vortex_buffer::buffer;
111    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
112    /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
113    ///   metadata: ptype: i16
114    /// ";
115    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: true }, &ctx)), expected);
116    ///
117    /// # use vortex_array::arrays::StructArray;
118    /// let array = StructArray::from_fields(&[
119    ///     ("x", buffer![1, 2].into_array()),
120    ///     ("y", buffer![3, 4].into_array()),
121    /// ]).unwrap().into_array();
122    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
123    ///   metadata:\x20
124    ///   x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
125    ///     metadata: ptype: i32
126    ///   y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
127    ///     metadata: ptype: i32
128    /// ";
129    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: true }, &ctx)), expected);
130    /// ```
131    ///
132    /// With metadata and buffers but no stats:
133    ///
134    /// ```
135    /// # use vortex_session::VortexSession;
136    /// # use vortex_array::VortexSessionExecute;
137    /// # let ctx = VortexSession::empty().create_execution_ctx();
138    /// # use vortex_array::display::DisplayOptions;
139    /// # use vortex_array::IntoArray;
140    /// # use vortex_buffer::buffer;
141    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
142    /// let expected = "root: vortex.primitive(i16, len=5)
143    ///   metadata: ptype: i16
144    ///   buffer: values host 10 B (align=2)
145    /// ";
146    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: false }, &ctx)), expected);
147    ///
148    /// # use vortex_array::arrays::StructArray;
149    /// let array = StructArray::from_fields(&[
150    ///     ("x", buffer![1, 2].into_array()),
151    ///     ("y", buffer![3, 4].into_array()),
152    /// ]).unwrap().into_array();
153    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
154    ///   metadata:\x20
155    ///   x: vortex.primitive(i32, len=2)
156    ///     metadata: ptype: i32
157    ///     buffer: values host 8 B (align=4)
158    ///   y: vortex.primitive(i32, len=2)
159    ///     metadata: ptype: i32
160    ///     buffer: values host 8 B (align=4)
161    /// ";
162    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: true, stats: false }, &ctx)), expected);
163    /// ```
164    ///
165    /// With buffers and stats but no metadata:
166    ///
167    /// ```
168    /// # use vortex_session::VortexSession;
169    /// # use vortex_array::VortexSessionExecute;
170    /// # let ctx = VortexSession::empty().create_execution_ctx();
171    /// # use vortex_array::display::DisplayOptions;
172    /// # use vortex_array::IntoArray;
173    /// # use vortex_buffer::buffer;
174    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
175    /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
176    ///   buffer: values host 10 B (align=2) (100.00%)
177    /// ";
178    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: true }, &ctx)), expected);
179    ///
180    /// # use vortex_array::arrays::StructArray;
181    /// let array = StructArray::from_fields(&[
182    ///     ("x", buffer![1, 2].into_array()),
183    ///     ("y", buffer![3, 4].into_array()),
184    /// ]).unwrap().into_array();
185    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
186    ///   x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
187    ///     buffer: values host 8 B (align=4) (100.00%)
188    ///   y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
189    ///     buffer: values host 8 B (align=4) (100.00%)
190    /// ";
191    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: true }, &ctx)), expected);
192    /// ```
193    ///
194    /// With just buffers:
195    ///
196    /// ```
197    /// # use vortex_session::VortexSession;
198    /// # use vortex_array::VortexSessionExecute;
199    /// # let ctx = VortexSession::empty().create_execution_ctx();
200    /// # use vortex_array::display::DisplayOptions;
201    /// # use vortex_array::IntoArray;
202    /// # use vortex_buffer::buffer;
203    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
204    /// let expected = "root: vortex.primitive(i16, len=5)
205    ///   buffer: values host 10 B (align=2)
206    /// ";
207    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: false }, &ctx)), expected);
208    ///
209    /// # use vortex_array::arrays::StructArray;
210    /// let array = StructArray::from_fields(&[
211    ///     ("x", buffer![1, 2].into_array()),
212    ///     ("y", buffer![3, 4].into_array()),
213    /// ]).unwrap().into_array();
214    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
215    ///   x: vortex.primitive(i32, len=2)
216    ///     buffer: values host 8 B (align=4)
217    ///   y: vortex.primitive(i32, len=2)
218    ///     buffer: values host 8 B (align=4)
219    /// ";
220    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: true, metadata: false, stats: false }, &ctx)), expected);
221    /// ```
222    ///
223    /// With just metadata:
224    ///
225    /// ```
226    /// # use vortex_session::VortexSession;
227    /// # use vortex_array::VortexSessionExecute;
228    /// # let ctx = VortexSession::empty().create_execution_ctx();
229    /// # use vortex_array::display::DisplayOptions;
230    /// # use vortex_array::IntoArray;
231    /// # use vortex_buffer::buffer;
232    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
233    /// let expected = "root: vortex.primitive(i16, len=5)
234    ///   metadata: ptype: i16
235    /// ";
236    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: false }, &ctx)), expected);
237    ///
238    /// # use vortex_array::arrays::StructArray;
239    /// let array = StructArray::from_fields(&[
240    ///     ("x", buffer![1, 2].into_array()),
241    ///     ("y", buffer![3, 4].into_array()),
242    /// ]).unwrap().into_array();
243    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
244    ///   metadata:\x20
245    ///   x: vortex.primitive(i32, len=2)
246    ///     metadata: ptype: i32
247    ///   y: vortex.primitive(i32, len=2)
248    ///     metadata: ptype: i32
249    /// ";
250    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: true, stats: false }, &ctx)), expected);
251    /// ```
252    ///
253    /// With just stats:
254    ///
255    /// ```
256    /// # use vortex_session::VortexSession;
257    /// # use vortex_array::VortexSessionExecute;
258    /// # let ctx = VortexSession::empty().create_execution_ctx();
259    /// # use vortex_array::display::DisplayOptions;
260    /// # use vortex_array::IntoArray;
261    /// # use vortex_buffer::buffer;
262    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
263    /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
264    /// ";
265    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: true }, &ctx)), expected);
266    ///
267    /// # use vortex_array::arrays::StructArray;
268    /// let array = StructArray::from_fields(&[
269    ///     ("x", buffer![1, 2].into_array()),
270    ///     ("y", buffer![3, 4].into_array()),
271    /// ]).unwrap().into_array();
272    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2) nbytes=16 B (100.00%)
273    ///   x: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
274    ///   y: vortex.primitive(i32, len=2) nbytes=8 B (50.00%)
275    /// ";
276    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: true }, &ctx)), expected);
277    /// ```
278    ///
279    /// With neither buffers, metadata, stats, nor values:
280    ///
281    /// ```
282    /// # use vortex_session::VortexSession;
283    /// # use vortex_array::VortexSessionExecute;
284    /// # let ctx = VortexSession::empty().create_execution_ctx();
285    /// # use vortex_array::display::DisplayOptions;
286    /// # use vortex_array::IntoArray;
287    /// # use vortex_buffer::buffer;
288    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
289    /// let expected = "root: vortex.primitive(i16, len=5)\n";
290    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: false }, &ctx)), expected);
291    ///
292    /// # use vortex_array::arrays::StructArray;
293    /// let array = StructArray::from_fields(&[
294    ///     ("x", buffer![1, 2].into_array()),
295    ///     ("y", buffer![3, 4].into_array()),
296    /// ]).unwrap().into_array();
297    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
298    ///   x: vortex.primitive(i32, len=2)
299    ///   y: vortex.primitive(i32, len=2)
300    /// ";
301    /// assert_eq!(format!("{}", array.display_as(DisplayOptions::TreeDisplay { buffers: false, metadata: false, stats: false }, &ctx)), expected);
302    /// ```
303    TreeDisplay {
304        buffers: bool,
305        metadata: bool,
306        stats: bool,
307    },
308    /// Display values in a formatted table with columns.
309    ///
310    /// For struct arrays, displays a column for each field in the struct.
311    /// For regular arrays, displays a single column with values.
312    ///
313    /// ```
314    /// # use vortex_session::VortexSession;
315    /// # use vortex_array::VortexSessionExecute;
316    /// # let ctx = VortexSession::empty().create_execution_ctx();
317    /// # use vortex_array::display::DisplayOptions;
318    /// # use vortex_array::arrays::StructArray;
319    /// # use vortex_array::IntoArray;
320    /// # use vortex_buffer::buffer;
321    /// let s = StructArray::from_fields(&[
322    ///     ("x", buffer![1, 2].into_array()),
323    ///     ("y", buffer![3, 4].into_array()),
324    /// ]).unwrap().into_array();
325    /// let expected = "
326    /// ┌──────┬──────┐
327    /// │  x   │  y   │
328    /// ├──────┼──────┤
329    /// │ 1i32 │ 3i32 │
330    /// ├──────┼──────┤
331    /// │ 2i32 │ 4i32 │
332    /// └──────┴──────┘".trim();
333    /// assert_eq!(format!("{}", s.display_as(DisplayOptions::TableDisplay, &ctx)), expected);
334    /// ```
335    #[cfg(feature = "table-display")]
336    TableDisplay,
337}
338
339impl Default for DisplayOptions {
340    fn default() -> Self {
341        Self::CommaSeparatedScalars {
342            omit_comma_after_space: false,
343        }
344    }
345}
346
347/// A shim used to display an array as specified in the options.
348///
349/// Values are read with a clone of the execution context, made each time the array is formatted.
350///
351/// See also:
352/// [Array::display_as](../trait.Array.html#method.display_as)
353/// and [DisplayOptions].
354pub struct DisplayArrayAs<'a> {
355    array: &'a ArrayRef,
356    options: DisplayOptions,
357    ctx: &'a ExecutionCtx,
358}
359
360impl<'a> DisplayArrayAs<'a> {
361    /// Display `array` as specified by `options`, reading values with `ctx`.
362    pub fn new(array: &'a ArrayRef, options: DisplayOptions, ctx: &'a ExecutionCtx) -> Self {
363        Self {
364            array,
365            options,
366            ctx,
367        }
368    }
369}
370
371impl Display for DisplayArrayAs<'_> {
372    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
373        self.array.fmt_as(f, &self.options, &mut self.ctx.clone())
374    }
375}
376
377/// Display the encoding and limited metadata of this array.
378///
379/// # Examples
380/// ```
381/// # use vortex_array::IntoArray;
382/// # use vortex_buffer::buffer;
383/// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
384/// assert_eq!(
385///     format!("{}", array),
386///     "vortex.primitive(i16, len=5)",
387/// );
388/// ```
389impl Display for ArrayRef {
390    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
391        EncodingSummaryExtractor::write(self, f)
392    }
393}
394
395const DISPLAY_LIMIT: usize = 16;
396impl ArrayRef {
397    /// Display logical values of the array
398    ///
399    /// For example, an `i16` typed array containing the first five non-negative integers is displayed
400    /// as: `[0i16, 1i16, 2i16, 3i16, 4i16]`.
401    ///
402    /// # Examples
403    ///
404    /// ```
405    /// # use vortex_session::VortexSession;
406    /// # use vortex_array::VortexSessionExecute;
407    /// # let ctx = VortexSession::empty().create_execution_ctx();
408    /// # use vortex_array::IntoArray;
409    /// # use vortex_buffer::buffer;
410    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
411    /// assert_eq!(
412    ///     format!("{}", array.display_values(&ctx)),
413    ///     "[0i16, 1i16, 2i16, 3i16, 4i16]",
414    /// )
415    /// ```
416    ///
417    /// See also:
418    /// [Array::display_as](..//trait.Array.html#method.display_as),
419    /// [DisplayArrayAs], and [DisplayOptions].
420    pub fn display_values<'a>(&'a self, ctx: &'a ExecutionCtx) -> DisplayArrayAs<'a> {
421        DisplayArrayAs::new(
422            self,
423            DisplayOptions::CommaSeparatedScalars {
424                omit_comma_after_space: false,
425            },
426            ctx,
427        )
428    }
429
430    /// Display the array as specified by the options, reading values with `ctx`.
431    ///
432    /// See [DisplayOptions] for examples.
433    pub fn display_as<'a>(
434        &'a self,
435        options: DisplayOptions,
436        ctx: &'a ExecutionCtx,
437    ) -> DisplayArrayAs<'a> {
438        DisplayArrayAs::new(self, options, ctx)
439    }
440
441    /// Display the tree of array encodings and lengths without metadata, buffers, or stats.
442    ///
443    /// # Examples
444    /// ```
445    /// # use vortex_array::display::DisplayOptions;
446    /// # use vortex_array::IntoArray;
447    /// # use vortex_buffer::buffer;
448    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
449    /// let expected = "root: vortex.primitive(i16, len=5)\n";
450    /// assert_eq!(format!("{}", array.display_tree_encodings_only()), expected);
451    ///
452    /// # use vortex_array::arrays::StructArray;
453    /// let array = StructArray::from_fields(&[
454    ///     ("x", buffer![1, 2].into_array()),
455    ///     ("y", buffer![3, 4].into_array()),
456    /// ]).unwrap().into_array();
457    /// let expected = "root: vortex.struct({x=i32, y=i32}, len=2)
458    ///   x: vortex.primitive(i32, len=2)
459    ///   y: vortex.primitive(i32, len=2)
460    /// ";
461    /// assert_eq!(format!("{}", array.display_tree_encodings_only()), expected);
462    /// ```
463    pub fn display_tree_encodings_only(&self) -> TreeDisplay {
464        self.tree_display_builder().with(EncodingSummaryExtractor)
465    }
466
467    /// Display the tree of encodings of this array as an indented lists.
468    ///
469    /// While some metadata (such as length, bytes and validity-rate) are included, the logical
470    /// values of the array are not displayed. To view the logical values see
471    /// [Array::display_as](../trait.Array.html#method.display_as)
472    /// and [DisplayOptions].
473    ///
474    /// # Examples
475    /// ```
476    /// # use vortex_array::display::DisplayOptions;
477    /// # use vortex_array::IntoArray;
478    /// # use vortex_buffer::buffer;
479    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
480    /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
481    ///   metadata: ptype: i16
482    ///   buffer: values host 10 B (align=2) (100.00%)
483    /// ";
484    /// assert_eq!(format!("{}", array.display_tree()), expected);
485    /// ```
486    pub fn display_tree(&self) -> TreeDisplay {
487        TreeDisplay::default_display(self.clone())
488    }
489
490    /// Create a tree display with all built-in extractors (nbytes, stats, metadata, buffers).
491    ///
492    /// This is the default, fully-detailed tree display. Use
493    /// `tree_display_builder()` for a blank slate.
494    ///
495    /// # Examples
496    /// ```
497    /// # use vortex_array::IntoArray;
498    /// # use vortex_buffer::buffer;
499    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
500    /// let expected = "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)
501    ///   metadata: ptype: i16
502    ///   buffer: values host 10 B (align=2) (100.00%)
503    /// ";
504    /// assert_eq!(array.tree_display().to_string(), expected);
505    /// ```
506    pub fn tree_display(&self) -> TreeDisplay {
507        TreeDisplay::default_display(self.clone())
508    }
509
510    /// Create a composable tree display builder with no extractors.
511    ///
512    /// With no extractors, only the node names are shown.
513    /// Add extractors with [`.with()`][TreeDisplay::with] to include additional information.
514    /// Most builders should start with [`EncodingSummaryExtractor`] to include encoding headers.
515    ///
516    /// # Examples
517    /// ```
518    /// # use vortex_array::IntoArray;
519    /// # use vortex_buffer::buffer;
520    /// use vortex_array::display::{EncodingSummaryExtractor, NbytesExtractor, MetadataExtractor, BufferExtractor};
521    ///
522    /// let array = buffer![0_i16, 1, 2, 3, 4].into_array();
523    ///
524    /// // Encodings only
525    /// let encodings = array.tree_display_builder()
526    ///     .with(EncodingSummaryExtractor)
527    ///     .to_string();
528    /// assert_eq!(encodings, "root: vortex.primitive(i16, len=5)\n");
529    ///
530    /// // With encoding + nbytes
531    /// let with_nbytes = array.tree_display_builder()
532    ///     .with(EncodingSummaryExtractor)
533    ///     .with(NbytesExtractor)
534    ///     .to_string();
535    /// assert_eq!(with_nbytes, "root: vortex.primitive(i16, len=5) nbytes=10 B (100.00%)\n");
536    ///
537    /// // With encoding, metadata, and buffers
538    /// let detailed = array.tree_display_builder()
539    ///     .with(EncodingSummaryExtractor)
540    ///     .with(MetadataExtractor)
541    ///     .with(BufferExtractor { show_percent: false })
542    ///     .to_string();
543    /// let expected = "root: vortex.primitive(i16, len=5)\n  metadata: ptype: i16\n  buffer: values host 10 B (align=2)\n";
544    /// assert_eq!(detailed, expected);
545    /// ```
546    pub fn tree_display_builder(&self) -> TreeDisplay {
547        TreeDisplay::new(self.clone())
548    }
549
550    /// Display the array as a formatted table.
551    ///
552    /// For struct arrays, displays a column for each field in the struct.
553    /// For regular arrays, displays a single column with values.
554    ///
555    /// # Examples
556    /// ```
557    /// # use vortex_session::VortexSession;
558    /// # use vortex_array::VortexSessionExecute;
559    /// # let ctx = VortexSession::empty().create_execution_ctx();
560    /// # #[cfg(feature = "table-display")]
561    /// # {
562    /// # use vortex_array::arrays::StructArray;
563    /// # use vortex_array::IntoArray;
564    /// # use vortex_buffer::buffer;
565    /// let s = StructArray::from_fields(&[
566    ///     ("x", buffer![1, 2].into_array()),
567    ///     ("y", buffer![3, 4].into_array()),
568    /// ]).unwrap().into_array();
569    /// let expected = "
570    /// ┌──────┬──────┐
571    /// │  x   │  y   │
572    /// ├──────┼──────┤
573    /// │ 1i32 │ 3i32 │
574    /// ├──────┼──────┤
575    /// │ 2i32 │ 4i32 │
576    /// └──────┴──────┘".trim();
577    /// assert_eq!(format!("{}", s.display_table(&ctx)), expected);
578    /// # }
579    /// ```
580    #[cfg(feature = "table-display")]
581    pub fn display_table<'a>(&'a self, ctx: &'a ExecutionCtx) -> DisplayArrayAs<'a> {
582        DisplayArrayAs::new(self, DisplayOptions::TableDisplay, ctx)
583    }
584
585    fn fmt_as(
586        &self,
587        f: &mut std::fmt::Formatter,
588        options: &DisplayOptions,
589        ctx: &mut ExecutionCtx,
590    ) -> std::fmt::Result {
591        match options {
592            DisplayOptions::MetadataOnly => EncodingSummaryExtractor::write(self, f),
593            DisplayOptions::CommaSeparatedScalars {
594                omit_comma_after_space,
595            } => {
596                let opening_brace = if f.alternate() { "[\n" } else { "[" };
597                let closing_brace = if f.alternate() { "\n]" } else { "]" };
598
599                let sep = if *omit_comma_after_space { "," } else { ", " };
600                let sep = if f.alternate() { ",\n" } else { sep };
601                let limit = self.len().min(f.precision().unwrap_or(DISPLAY_LIMIT));
602                let is_truncated = self.len() > limit;
603
604                let mut fmt_scalar = |i| {
605                    self.execute_scalar(i, ctx)
606                        .map_or_else(|e| format!("<error: {e}>"), |s| s.to_string())
607                };
608                let head = (0..limit.saturating_sub(3))
609                    .map(&mut fmt_scalar)
610                    .collect::<Vec<_>>();
611                let tail = (self.len().saturating_sub(3)..self.len())
612                    .map(&mut fmt_scalar)
613                    .collect::<Vec<_>>();
614                write!(
615                    f,
616                    "{opening_brace}{}{closing_brace}",
617                    head.into_iter()
618                        .chain(repeat_n("...".to_string(), is_truncated as usize))
619                        .chain(tail)
620                        .format(sep)
621                )
622            }
623            DisplayOptions::TreeDisplay {
624                buffers,
625                metadata,
626                stats,
627            } => {
628                let extractors: [(bool, Box<dyn TreeExtractor<ArrayRef, TreeContext>>); 5] = [
629                    (true, Box::new(EncodingSummaryExtractor)),
630                    (*stats, Box::new(NbytesExtractor)),
631                    (*stats, Box::new(StatsExtractor)),
632                    (*metadata, Box::new(MetadataExtractor)),
633                    (
634                        *buffers,
635                        Box::new(BufferExtractor {
636                            show_percent: *stats,
637                        }),
638                    ),
639                ];
640                let mut display = TreeDisplay::new(self.clone());
641                for (enabled, extractor) in extractors {
642                    if enabled {
643                        display = display.with_boxed(extractor);
644                    }
645                }
646                write!(f, "{display}")
647            }
648            #[cfg(feature = "table-display")]
649            DisplayOptions::TableDisplay => {
650                use vortex_mask::Mask;
651
652                use crate::arrays::StructArray;
653                use crate::arrays::struct_::StructArrayExt;
654                use crate::dtype::DType;
655
656                let mut builder = tabled::builder::Builder::default();
657
658                // Special logic for struct arrays.
659                let DType::Struct(sf, _) = self.dtype() else {
660                    // For non-struct arrays, simply display a single column table without header.
661                    for row_idx in 0..self.len() {
662                        let value = self
663                            .execute_scalar(row_idx, ctx)
664                            .map_or_else(|e| format!("<error: {e}>"), |s| s.to_string());
665                        builder.push_record([value]);
666                    }
667
668                    let mut table = builder.build();
669                    table.with(tabled::settings::Style::modern());
670
671                    return write!(f, "{table}");
672                };
673
674                let struct_ = match self.clone().execute::<StructArray>(ctx) {
675                    Ok(struct_) => struct_,
676                    Err(e) => return write!(f, "<error: {e}>"),
677                };
678                builder.push_record(sf.names().iter().map(|name| name.to_string()));
679
680                // Resolve validity to a mask once instead of probing it per row.
681                let validity = self
682                    .validity()
683                    .and_then(|v| v.execute_mask(self.len(), ctx))
684                    .unwrap_or_else(|_| Mask::new_false(self.len()));
685
686                for row_idx in 0..self.len() {
687                    if !validity.value(row_idx) {
688                        let null_row = vec!["null".to_string(); sf.names().len()];
689                        builder.push_record(null_row);
690                    } else {
691                        let mut row = Vec::with_capacity(struct_.struct_fields().nfields());
692                        for field_array in StructArrayExt::iter_unmasked_fields(&struct_) {
693                            let value = field_array
694                                .execute_scalar(row_idx, ctx)
695                                .map_or_else(|e| format!("<error: {e}>"), |s| s.to_string());
696                            row.push(value);
697                        }
698                        builder.push_record(row);
699                    }
700                }
701
702                let mut table = builder.build();
703                table.with(tabled::settings::Style::modern());
704
705                // Center headers
706                for col_idx in 0..sf.names().len() {
707                    table.modify((0, col_idx), tabled::settings::Alignment::center());
708                }
709
710                for row_idx in 0..self.len() {
711                    if !validity.value(row_idx) {
712                        table.modify(
713                            (1 + row_idx, 0),
714                            tabled::settings::Span::column(sf.names().len() as isize),
715                        );
716                        table.modify((1 + row_idx, 0), tabled::settings::Alignment::center());
717                    }
718                }
719
720                write!(f, "{table}")
721            }
722        }
723    }
724}
725
726#[cfg(test)]
727mod test {
728    use std::sync::LazyLock;
729
730    use vortex_buffer::Buffer;
731    use vortex_buffer::buffer;
732    use vortex_session::VortexSession;
733
734    use crate::IntoArray as _;
735    use crate::VortexSessionExecute;
736    use crate::arrays::BoolArray;
737    use crate::arrays::ListArray;
738    use crate::arrays::PrimitiveArray;
739    use crate::arrays::StructArray;
740    use crate::display::DISPLAY_LIMIT;
741    use crate::dtype::FieldNames;
742    use crate::validity::Validity;
743
744    static SESSION: LazyLock<VortexSession> = LazyLock::new(VortexSession::empty);
745
746    #[test]
747    fn test_primitive() {
748        let ctx = SESSION.create_execution_ctx();
749        let x = Buffer::<u32>::empty().into_array();
750        assert_eq!(x.display_values(&ctx).to_string(), "[]");
751
752        let x = buffer![1].into_array();
753        assert_eq!(x.display_values(&ctx).to_string(), "[1i32]");
754
755        let x = buffer![1, 2, 3, 4].into_array();
756        assert_eq!(
757            x.display_values(&ctx).to_string(),
758            "[1i32, 2i32, 3i32, 4i32]"
759        );
760
761        let x =
762            PrimitiveArray::from_iter(0i32..i32::try_from(DISPLAY_LIMIT).unwrap() + 1).into_array();
763        assert_eq!(
764            x.display_values(&ctx).to_string(),
765            "[0i32, 1i32, 2i32, 3i32, 4i32, 5i32, 6i32, 7i32, 8i32, 9i32, 10i32, 11i32, 12i32, ..., 14i32, 15i32, 16i32]"
766        );
767    }
768
769    #[test]
770    fn test_empty_struct() {
771        let ctx = SESSION.create_execution_ctx();
772        let s = StructArray::try_new(
773            FieldNames::empty(),
774            vec![],
775            3,
776            Validity::Array(BoolArray::from_iter([true, false, true]).into_array()),
777        )
778        .unwrap()
779        .into_array();
780        assert_eq!(s.display_values(&ctx).to_string(), "[{}, null, {}]");
781    }
782
783    #[test]
784    fn test_simple_struct() {
785        let ctx = SESSION.create_execution_ctx();
786        let s = StructArray::from_fields(&[
787            ("x", buffer![1, 2, 3, 4].into_array()),
788            ("y", buffer![-1, -2, -3, -4].into_array()),
789        ])
790        .unwrap()
791        .into_array();
792        assert_eq!(
793            s.display_values(&ctx).to_string(),
794            "[{x: 1i32, y: -1i32}, {x: 2i32, y: -2i32}, {x: 3i32, y: -3i32}, {x: 4i32, y: -4i32}]"
795        );
796    }
797
798    #[test]
799    fn test_list() {
800        let mut ctx = SESSION.create_execution_ctx();
801        let x = ListArray::try_new(
802            buffer![1, 2, 3, 4].into_array(),
803            buffer![0, 0, 1, 1, 2, 4].into_array(),
804            Validity::Array(BoolArray::from_iter([true, true, false, true, true]).into_array()),
805            &mut ctx,
806        )
807        .unwrap()
808        .into_array();
809        assert_eq!(
810            x.display_values(&ctx).to_string(),
811            "[[], [1i32], null, [2i32], [3i32, 4i32]]"
812        );
813    }
814
815    #[test]
816    fn test_display_tree_nullable_primitive_validity_child() {
817        let array =
818            PrimitiveArray::from_option_iter([Some(1i64), Some(2), None, Some(3)]).into_array();
819        let expected = "root: vortex.primitive(i64?, len=4) nbytes=33 B (100.00%)\n  metadata: ptype: i64\n  buffer: values host 32 B (align=8) (96.97%)\n  validity: vortex.bool(bool, len=4) nbytes=1 B (3.03%)\n    metadata: offset: 0\n    buffer: bits host 1 B (align=1) (100.00%)\n";
820        assert_eq!(format!("{}", array.display_tree()), expected);
821    }
822
823    #[test]
824    fn test_table_display_primitive() {
825        let ctx = SESSION.create_execution_ctx();
826        use crate::display::DisplayOptions;
827
828        let array = buffer![1, 2, 3, 4].into_array();
829        let table_display = array.display_as(DisplayOptions::TableDisplay, &ctx);
830        assert_eq!(
831            table_display.to_string(),
832            r"
833┌──────┐
834│ 1i32 │
835├──────┤
836│ 2i32 │
837├──────┤
838│ 3i32 │
839├──────┤
840│ 4i32 │
841└──────┘"
842                .trim()
843        );
844    }
845
846    #[test]
847    fn test_table_display() {
848        let ctx = SESSION.create_execution_ctx();
849        use crate::display::DisplayOptions;
850
851        let array =
852            PrimitiveArray::from_option_iter(vec![Some(-1), Some(-2), Some(-3), None]).into_array();
853
854        let struct_ = StructArray::try_from_iter_with_validity(
855            [("x", buffer![1, 2, 3, 4].into_array()), ("y", array)],
856            Validity::Array(BoolArray::from_iter([true, false, true, true]).into_array()),
857        )
858        .unwrap()
859        .into_array();
860
861        let table_display = struct_.display_as(DisplayOptions::TableDisplay, &ctx);
862        assert_eq!(
863            table_display.to_string(),
864            r"
865┌──────┬───────┐
866│  x   │   y   │
867├──────┼───────┤
868│ 1i32 │ -1i32 │
869├──────┼───────┤
870│     null     │
871├──────┼───────┤
872│ 3i32 │ -3i32 │
873├──────┼───────┤
874│ 4i32 │ null  │
875└──────┴───────┘"
876                .trim()
877        );
878    }
879}