feat[array]: compositional array display logic

vortex-array/public-api.lock

@@ -9938,12 +9938,112 @@ impl core::default::Default for vortex_array::display::DisplayOptions
 
 pub fn vortex_array::display::DisplayOptions::default() -> Self
 
+pub struct vortex_array::display::BufferExtractor
+
+pub vortex_array::display::BufferExtractor::show_percent: bool
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::BufferExtractor
+
+pub fn vortex_array::display::BufferExtractor::write_details(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::BufferExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
 pub struct vortex_array::display::DisplayArrayAs<'a>(pub &'a dyn vortex_array::DynArray, pub vortex_array::display::DisplayOptions)
 
 impl core::fmt::Display for vortex_array::display::DisplayArrayAs<'_>
 
 pub fn vortex_array::display::DisplayArrayAs<'_>::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
 
+pub struct vortex_array::display::EncodingSummaryExtractor
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::EncodingSummaryExtractor
+
+pub fn vortex_array::display::EncodingSummaryExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::EncodingSummaryExtractor::write_header(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+pub struct vortex_array::display::MetadataExtractor
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::MetadataExtractor
+
+pub fn vortex_array::display::MetadataExtractor::write_details(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::MetadataExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+pub struct vortex_array::display::NbytesExtractor
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::NbytesExtractor
+
+pub fn vortex_array::display::NbytesExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::NbytesExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+pub struct vortex_array::display::StatsExtractor
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::StatsExtractor
+
+pub fn vortex_array::display::StatsExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::StatsExtractor::write_header(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+pub struct vortex_array::display::TreeContext
+
+impl vortex_array::display::TreeContext
+
+pub fn vortex_array::display::TreeContext::parent_total_size(&self) -> core::option::Option<u64>
+
+pub struct vortex_array::display::TreeDisplay
+
+impl vortex_array::display::TreeDisplay
+
+pub fn vortex_array::display::TreeDisplay::default_display(array: vortex_array::ArrayRef) -> Self
+
+pub fn vortex_array::display::TreeDisplay::new(array: vortex_array::ArrayRef) -> Self
+
+pub fn vortex_array::display::TreeDisplay::with<E: vortex_array::display::TreeExtractor + 'static>(self, extractor: E) -> Self
+
+pub fn vortex_array::display::TreeDisplay::with_boxed(self, extractor: alloc::boxed::Box<dyn vortex_array::display::TreeExtractor>) -> Self
+
+impl core::fmt::Display for vortex_array::display::TreeDisplay
+
+pub fn vortex_array::display::TreeDisplay::fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+pub trait vortex_array::display::TreeExtractor: core::marker::Send + core::marker::Sync
+
+pub fn vortex_array::display::TreeExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::TreeExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::BufferExtractor
+
+pub fn vortex_array::display::BufferExtractor::write_details(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::BufferExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::EncodingSummaryExtractor
+
+pub fn vortex_array::display::EncodingSummaryExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::EncodingSummaryExtractor::write_header(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::MetadataExtractor
+
+pub fn vortex_array::display::MetadataExtractor::write_details(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::MetadataExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::NbytesExtractor
+
+pub fn vortex_array::display::NbytesExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::NbytesExtractor::write_header(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
+impl vortex_array::display::TreeExtractor for vortex_array::display::StatsExtractor
+
+pub fn vortex_array::display::StatsExtractor::write_details(&self, array: &dyn vortex_array::DynArray, ctx: &vortex_array::display::TreeContext, f: &mut dyn core::fmt::Write) -> core::fmt::Result
+
+pub fn vortex_array::display::StatsExtractor::write_header(&self, array: &dyn vortex_array::DynArray, _ctx: &vortex_array::display::TreeContext, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+
 pub mod vortex_array::dtype
 
 pub use vortex_array::dtype::half
@@ -22038,7 +22138,7 @@ pub fn vortex_array::ArrayAdapter<V>::is_host(&self) -> bool
 
 pub fn vortex_array::ArrayAdapter<V>::metadata(&self) -> vortex_error::VortexResult<core::option::Option<alloc::vec::Vec<u8>>>
 
-pub fn vortex_array::ArrayAdapter<V>::metadata_fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn vortex_array::ArrayAdapter<V>::metadata_fmt(&self, f: &mut dyn core::fmt::Write) -> core::fmt::Result
 
 pub fn vortex_array::ArrayAdapter<V>::named_buffers(&self) -> alloc::vec::Vec<(alloc::string::String, vortex_array::buffer::BufferHandle)>
 
@@ -22330,7 +22430,7 @@ pub fn vortex_array::ArrayVisitor::is_host(&self) -> bool
 
 pub fn vortex_array::ArrayVisitor::metadata(&self) -> vortex_error::VortexResult<core::option::Option<alloc::vec::Vec<u8>>>
 
-pub fn vortex_array::ArrayVisitor::metadata_fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn vortex_array::ArrayVisitor::metadata_fmt(&self, f: &mut dyn core::fmt::Write) -> core::fmt::Result
 
 pub fn vortex_array::ArrayVisitor::named_buffers(&self) -> alloc::vec::Vec<(alloc::string::String, vortex_array::buffer::BufferHandle)>
 
@@ -22358,7 +22458,7 @@ pub fn alloc::sync::Arc<dyn vortex_array::DynArray>::is_host(&self) -> bool
 
 pub fn alloc::sync::Arc<dyn vortex_array::DynArray>::metadata(&self) -> vortex_error::VortexResult<core::option::Option<alloc::vec::Vec<u8>>>
 
-pub fn alloc::sync::Arc<dyn vortex_array::DynArray>::metadata_fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn alloc::sync::Arc<dyn vortex_array::DynArray>::metadata_fmt(&self, f: &mut dyn core::fmt::Write) -> core::fmt::Result
 
 pub fn alloc::sync::Arc<dyn vortex_array::DynArray>::named_buffers(&self) -> alloc::vec::Vec<(alloc::string::String, vortex_array::buffer::BufferHandle)>
 
@@ -22386,7 +22486,7 @@ pub fn vortex_array::ArrayAdapter<V>::is_host(&self) -> bool
 
 pub fn vortex_array::ArrayAdapter<V>::metadata(&self) -> vortex_error::VortexResult<core::option::Option<alloc::vec::Vec<u8>>>
 
-pub fn vortex_array::ArrayAdapter<V>::metadata_fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result
+pub fn vortex_array::ArrayAdapter<V>::metadata_fmt(&self, f: &mut dyn core::fmt::Write) -> core::fmt::Result
 
 pub fn vortex_array::ArrayAdapter<V>::named_buffers(&self) -> alloc::vec::Vec<(alloc::string::String, vortex_array::buffer::BufferHandle)>
 

vortex-array/src/array/mod.rs

@@ -737,10 +737,11 @@ impl<V: VTable> ArrayVisitor for ArrayAdapter<V> {
         V::serialize(V::metadata(&self.0)?)
     }
 
-    fn metadata_fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    fn metadata_fmt(&self, f: &mut dyn std::fmt::Write) -> std::fmt::Result {
         match V::metadata(&self.0) {
             Err(e) => write!(f, "<serde error: {e}>"),
-            Ok(metadata) => Debug::fmt(&metadata, f),
+            #[expect(clippy::use_debug)]
+            Ok(metadata) => write!(f, "{metadata:?}"),
         }
     }
 

vortex-array/src/array/visitor.rs

@@ -1,7 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: Copyright the Vortex contributors
 
-use std::fmt::Formatter;
 use std::sync::Arc;
 
 use vortex_buffer::ByteBuffer;
@@ -49,7 +48,7 @@ pub trait ArrayVisitor {
     fn metadata(&self) -> VortexResult<Option<Vec<u8>>>;
 
     /// Formats a human-readable metadata description.
-    fn metadata_fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result;
+    fn metadata_fmt(&self, f: &mut dyn std::fmt::Write) -> std::fmt::Result;
 
     /// Checks if all buffers in the array tree are host-resident.
     ///
@@ -102,7 +101,7 @@ impl ArrayVisitor for Arc<dyn DynArray> {
         self.as_ref().metadata()
     }
 
-    fn metadata_fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+    fn metadata_fmt(&self, f: &mut dyn std::fmt::Write) -> std::fmt::Result {
         self.as_ref().metadata_fmt(f)
     }
 

vortex-array/src/display/extractor.rs

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+use std::fmt;
+use std::fmt::Write;
+
+use crate::DynArray;
+
+/// Context threaded through tree traversal for percentage calculations etc.
+pub struct TreeContext {
+    /// Stack of ancestor nbytes values. `None` entries reset the percentage root
+    /// (e.g. for chunked arrays where each chunk is its own root).
+    pub(crate) ancestor_sizes: Vec<Option<u64>>,
+}
+
+impl TreeContext {
+    pub(crate) fn new() -> Self {
+        Self {
+            ancestor_sizes: Vec::new(),
+        }
+    }
+
+    /// The total size used as the denominator for percentage calculations.
+    /// Returns `None` if there is no ancestor (i.e., this node is the root or
+    /// a chunk boundary reset the percentage root).
+    pub fn parent_total_size(&self) -> Option<u64> {
+        self.ancestor_sizes.last().cloned().flatten()
+    }
+
+    pub(crate) fn push(&mut self, size: Option<u64>) {
+        self.ancestor_sizes.push(size);
+    }
+
+    pub(crate) fn pop(&mut self) {
+        self.ancestor_sizes.pop();
+    }
+}
+
+/// A formatter wrapper that automatically prepends indentation at the start of each line.
+pub(crate) struct IndentedFormatter<'a, 'b> {
+    inner: &'a mut fmt::Formatter<'b>,
+    indent: &'a str,
+    at_line_start: bool,
+}
+
+impl<'a, 'b> IndentedFormatter<'a, 'b> {
+    pub(crate) fn new(f: &'a mut fmt::Formatter<'b>, indent: &'a str) -> Self {
+        Self {
+            inner: f,
+            indent,
+            at_line_start: true,
+        }
+    }
+}
+
+impl Write for IndentedFormatter<'_, '_> {
+    fn write_str(&mut self, s: &str) -> fmt::Result {
+        let mut parts = s.split('\n');
+
+        if let Some(first) = parts.next()
+            && !first.is_empty()
+        {
+            if self.at_line_start {
+                self.inner.write_str(self.indent)?;
+                self.at_line_start = false;
+            }
+            self.inner.write_str(first)?;
+        }
+
+        for part in parts {
+            self.inner.write_char('\n')?;
+            self.at_line_start = true;
+            if !part.is_empty() {
+                self.inner.write_str(self.indent)?;
+                self.at_line_start = false;
+                self.inner.write_str(part)?;
+            }
+        }
+
+        Ok(())
+    }
+}
+
+/// Trait for contributing display information to tree nodes.
+///
+/// Each extractor represents one "dimension" of display (e.g., nbytes, stats, metadata, buffers).
+/// Extractors are composable: you can combine any number of them via [`TreeDisplay::with`].
+///
+/// [`TreeDisplay::with`]: super::TreeDisplay::with
+pub trait TreeExtractor: Send + Sync {
+    /// Write header annotations (space-prefixed) to the formatter.
+    fn write_header(
+        &self,
+        array: &dyn DynArray,
+        ctx: &TreeContext,
+        f: &mut fmt::Formatter<'_>,
+    ) -> fmt::Result {
+        let _ = (array, ctx, f);
+        Ok(())
+    }
+
+    /// Write detail lines below the header.
+    ///
+    /// The caller handles indentation — extractors just write their content directly.
+    fn write_details(
+        &self,
+        array: &dyn DynArray,
+        ctx: &TreeContext,
+        f: &mut dyn Write,
+    ) -> fmt::Result {
+        let _ = (array, ctx, f);
+        Ok(())
+    }
+}

vortex-array/src/display/extractors/buffer.rs

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+use std::fmt;
+
+use humansize::DECIMAL;
+use humansize::format_size;
+
+use crate::DynArray;
+use crate::display::extractor::TreeContext;
+use crate::display::extractor::TreeExtractor;
+
+/// Extractor that adds buffer detail lines.
+pub struct BufferExtractor {
+    /// Whether to show buffer-level percentage of parent nbytes.
+    pub show_percent: bool,
+}
+
+impl TreeExtractor for BufferExtractor {
+    fn write_details(
+        &self,
+        array: &dyn DynArray,
+        _ctx: &TreeContext,
+        f: &mut dyn fmt::Write,
+    ) -> fmt::Result {
+        let nbytes = array.nbytes();
+        for (name, buffer) in array.named_buffers() {
+            let loc = if buffer.is_on_device() {
+                "device"
+            } else if buffer.is_on_host() {
+                "host"
+            } else {
+                "location-unknown"
+            };
+            let align = if buffer.is_on_host() {
+                buffer.as_host().alignment().to_string()
+            } else {
+                String::new()
+            };
+
+            if self.show_percent {
+                let buffer_percent = if nbytes == 0 {
+                    0.0
+                } else {
+                    100_f64 * buffer.len() as f64 / nbytes as f64
+                };
+                writeln!(
+                    f,
+                    "buffer: {} {loc} {} (align={}) ({:.2}%)",
+                    name,
+                    format_size(buffer.len(), DECIMAL),
+                    align,
+                    buffer_percent,
+                )?;
+            } else {
+                writeln!(
+                    f,
+                    "buffer: {} {loc} {} (align={})",
+                    name,
+                    format_size(buffer.len(), DECIMAL),
+                    align,
+                )?;
+            }
+        }
+        Ok(())
+    }
+}

vortex-array/src/display/extractors/encoding_summary.rs

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright the Vortex contributors
+
+use std::fmt;
+
+use crate::DynArray;
+use crate::display::DisplayOptions;
+use crate::display::extractor::TreeContext;
+use crate::display::extractor::TreeExtractor;
+
+/// Extractor that adds the encoding summary (e.g. `vortex.primitive(i16, len=5)`) to the header.
+pub struct EncodingSummaryExtractor;
+
+impl TreeExtractor for EncodingSummaryExtractor {
+    fn write_header(
+        &self,
+        array: &dyn DynArray,
+        _ctx: &TreeContext,
+        f: &mut fmt::Formatter<'_>,
+    ) -> fmt::Result {
+        write!(f, " {}", array.display_as(DisplayOptions::MetadataOnly))
+    }
+}