Give ListValue a Column-like read API (#11)

* Give `ListValue` a `Column`-like read API

`ListValue` (one element of a list column) was iterator-only. It now
mirrors `Column`'s read API so a list element behaves like a borrowed,
single-typed column:

- `len` / `is_empty`
- `get` / `value` (zero-copy views) and `get_owned` / `value_owned`
- `iter` (non-consuming) / `iter_owned` / `to_vec`
- `as_slice` for primitive items (contiguous, zero-copy)
- `list[i]` indexing for borrowable items

It stays an `Iterator` (so `.map`/`.collect`/`.sum` keep working) and is
now `Copy`; the random-access methods operate on the remaining items.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* Make `ListValue` iteration fast

The items sit in `index..end`, all in bounds, so override the
`Iterator` combinators (`count`, `last`, `nth`, `fold`) and add
`DoubleEndedIterator` (`next_back`, `nth_back`, `rfold`) plus
`FusedIterator`. These give `sum`/`for_each`/`collect`/`skip`/`rev`
tight loops instead of the default per-element `Option` plumbing.

Primitive items keep the even-faster zero-overhead path via `as_slice`.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: emilk

crates/quiver/tests/column.rs

@@ -1519,3 +1519,88 @@ fn utf8_string_encodings() {
     let values: Vec<Option<&str>> = nullable.iter().collect();
     assert_eq!(values, [Some("a"), None]);
 }
+
+#[test]
+fn list_value_column_like_api() {
+    // A `ListValue` (one list element) mirrors `Column`'s read API.
+    let column = Column::<List<i64>>::from_values([vec![10, 20, 30], vec![]]);
+
+    let first = column.value(0);
+    assert_eq!(first.len(), 3);
+    assert!(!first.is_empty());
+
+    // Random access by item index:
+    assert_eq!(first.value(0), 10);
+    assert_eq!(first.value(2), 30);
+    assert_eq!(first.get(1), Some(20));
+    assert_eq!(first.get(3), None);
+
+    // `list[i]` borrows from the array (primitive items):
+    assert_eq!(first[1], 20);
+
+    // Bulk zero-copy slice, and owned copies:
+    assert_eq!(first.as_slice(), &[10, 20, 30]);
+    assert_eq!(first.to_vec(), vec![10, 20, 30]);
+
+    // `iter` does not consume the view; the struct is `Copy`:
+    let sum: i64 = first.iter().sum();
+    assert_eq!(sum, 60);
+    let sum_again: i64 = first.iter().sum();
+    assert_eq!(sum_again, 60);
+
+    // Iterating still works directly (it is an `Iterator`):
+    let collected: Vec<i64> = first.collect();
+    assert_eq!(collected, [10, 20, 30]);
+
+    // Overridden combinators behave like the defaults:
+    assert_eq!(first.iter().count(), 3);
+    assert_eq!(first.iter().last(), Some(30));
+    assert_eq!(first.iter().nth(1), Some(20));
+    assert_eq!(first.iter().nth(3), None);
+    assert_eq!(
+        first
+            .iter()
+            .fold(String::new(), |acc, x| format!("{acc}{x}")),
+        "102030"
+    );
+
+    // Double-ended: `rev`, `next_back`, `nth_back`, `rfold`:
+    let rev: Vec<i64> = first.iter().rev().collect();
+    assert_eq!(rev, [30, 20, 10]);
+    let mut cursor = first.iter();
+    assert_eq!(cursor.next_back(), Some(30));
+    assert_eq!(cursor.next(), Some(10));
+    assert_eq!(cursor.next_back(), Some(20));
+    assert_eq!(cursor.next_back(), None);
+    assert_eq!(first.iter().nth_back(1), Some(20));
+    assert_eq!(first.iter().nth_back(3), None);
+    assert_eq!(
+        first
+            .iter()
+            .rfold(String::new(), |acc, x| format!("{acc}{x}")),
+        "302010"
+    );
+
+    // Empty element:
+    let second = column.value(1);
+    assert!(second.is_empty());
+    assert_eq!(second.len(), 0);
+    assert_eq!(second.get(0), None);
+    assert_eq!(second.as_slice(), &[] as &[i64]);
+
+    // String items: owned access and indexing.
+    let strings = Column::<List<Utf8>>::from_values([vec!["a".to_owned(), "b".to_owned()]]);
+    let row = strings.value(0);
+    assert_eq!(&row[0], "a");
+    assert_eq!(row.value_owned(1), "b".to_owned());
+    assert_eq!(row.get_owned(0), Some("a".to_owned()));
+    assert_eq!(row.to_vec(), vec!["a".to_owned(), "b".to_owned()]);
+}
+
+#[test]
+#[should_panic(expected = "out of bounds for length 2")]
+fn list_value_index_out_of_bounds() {
+    let column = Column::<List<i64>>::from_values([vec![1, 2]]);
+    let value: i64 = column.value(0).value(2);
+    assert_eq!(value, 0); // unreachable: the line above panics
+}

crates/quiver_types/src/list.rs

@@ -20,7 +20,9 @@ use arrow::array::{Array, ArrayRef, OffsetSizeTrait};
 use arrow::datatypes::ArrowNativeType as _;
 use arrow::datatypes::DataType;
 
-use crate::datatype::{ColumnError, InfallibleBuild, LogicalType, downcast_array};
+use crate::datatype::{
+    ColumnError, InfallibleBuild, LogicalType, PrimitiveType, RefType, downcast_array,
+};
 
 /// Marker for an arrow `List` column with items of logical type `L`.
 ///
@@ -155,20 +157,189 @@ pub(crate) use impl_list_datatype;
 
 impl_list_datatype!(List, TypedList, arrow::array::ListArray, List);
 
-/// One list element of a `Column<List<L>>`: an iterator over the typed items.
+/// One list element of a list column (`List`, [`LargeList`](crate::LargeList),
+/// [`FixedSizeList`](crate::FixedSizeList), …): a zero-copy, random-access view
+/// of that row's typed items.
+///
+/// It mirrors [`Column`](crate::Column)'s read API — the items behave like a
+/// borrowed slice of a single-typed column:
+///
+/// - length: [`len`](ListValue::len), [`is_empty`](ListValue::is_empty)
+/// - by-item access: [`get`](ListValue::get) / [`value`](ListValue::value)
+///   (zero-copy views) and [`get_owned`](ListValue::get_owned) /
+///   [`value_owned`](ListValue::value_owned) (owned), plus `list[i]` where the
+///   item can be borrowed from the array (see the [`Index`](std::ops::Index) impl)
+/// - bulk: [`to_vec`](ListValue::to_vec), and [`as_slice`](ListValue::as_slice)
+///   for primitive items (one contiguous zero-copy slice)
+/// - iteration: [`iter`](ListValue::iter) / [`iter_owned`](ListValue::iter_owned)
+///
+/// `ListValue` is itself an [`Iterator`] over the items, so `.map(…)` /
+/// `.collect()` / `.sum()` work directly on it. It is [`Copy`]: consuming it as
+/// an iterator advances a cursor (the random-access methods then see the
+/// remaining items), while [`iter`](ListValue::iter) hands out a fresh cursor
+/// without consuming the original.
+///
+/// ```
+/// use quiver::{Column, List};
+///
+/// let column = Column::<List<i64>>::from_values([vec![10, 20, 30], vec![]]);
+/// let row = column.value(0);
+///
+/// assert_eq!(row.len(), 3);
+/// assert_eq!(row.value(1), 20);     // by item index
+/// assert_eq!(row[2], 30);           // borrowed (primitive items)
+/// assert_eq!(row.as_slice(), &[10, 20, 30]); // contiguous, zero-copy
+/// assert_eq!(row.to_vec(), vec![10, 20, 30]);
+///
+/// let sum: i64 = row.iter().sum();  // `iter` does not consume `row`
+/// assert_eq!(sum, 60);
+///
+/// assert!(column.value(1).is_empty());
+/// ```
 pub struct ListValue<'a, L: LogicalType> {
     values: &'a L::Typed,
     index: usize,
     end: usize,
 }
 
-impl<'a, L: LogicalType> ListValue<'a, L> {
+impl<L: LogicalType> Clone for ListValue<'_, L> {
+    fn clone(&self) -> Self {
+        *self
+    }
+}
+
+impl<L: LogicalType> Copy for ListValue<'_, L> {}
+
+impl<'a, L: LogicalType + 'a> ListValue<'a, L> {
     /// `index..end` into `values`.
     pub(crate) fn new(values: &'a L::Typed, index: usize, end: usize) -> Self {
         Self { values, index, end }
     }
+
+    /// The number of items in this list element.
+    #[must_use]
+    pub fn len(&self) -> usize {
+        self.end - self.index
+    }
+
+    /// Is this list element empty?
+    #[must_use]
+    pub fn is_empty(&self) -> bool {
+        self.index == self.end
+    }
+
+    /// The item at `index`, or `None` if out of bounds.
+    ///
+    /// See [`ListValue::value`] for the returned view;
+    /// [`ListValue::get_owned`] returns the owned value instead.
+    #[must_use]
+    pub fn get(&self, index: usize) -> Option<L::Value<'a>> {
+        let item = self.index.checked_add(index)?;
+        (item < self.end).then(|| L::value(self.values, item))
+    }
+
+    /// The owned item at `index`, or `None` if out of bounds —
+    /// e.g. `String` where [`ListValue::get`] returns `&str`.
+    #[must_use]
+    pub fn get_owned(&self, index: usize) -> Option<L::Owned> {
+        self.get(index).map(L::to_owned_value)
+    }
+
+    /// The item at `index`, returning the zero-copy view
+    /// ([`LogicalType::Value`]); for the owned value see [`ListValue::value_owned`].
+    ///
+    /// Where the item can be borrowed from the array, `list[index]` works too
+    /// (see the [`Index`](std::ops::Index) impl).
+    ///
+    /// Panics if out of bounds.
+    #[must_use]
+    pub fn value(&self, index: usize) -> L::Value<'a> {
+        assert!(
+            index < self.len(),
+            "ListValue index {index} out of bounds for length {}",
+            self.len()
+        );
+        L::value(self.values, self.index + index)
+    }
+
+    /// The owned item at `index` — e.g. `String` where [`ListValue::value`]
+    /// returns `&str`.
+    ///
+    /// Panics if out of bounds.
+    #[must_use]
+    pub fn value_owned(&self, index: usize) -> L::Owned {
+        L::to_owned_value(self.value(index))
+    }
+
+    /// Iterates over the zero-copy views ([`LogicalType::Value`]) of the
+    /// remaining items, without consuming `self`.
+    ///
+    /// For owned values, see [`ListValue::iter_owned`].
+    #[must_use]
+    pub fn iter(&self) -> Self {
+        *self
+    }
+
+    /// Iterates over the owned values of the remaining items —
+    /// e.g. `String` where [`ListValue::iter`] yields `&str`.
+    pub fn iter_owned(&self) -> impl Iterator<Item = L::Owned> + 'a {
+        self.iter().map(L::to_owned_value)
+    }
+
+    /// Copies the items into a `Vec` of owned values,
+    /// e.g. `Vec<String>` for a `List<Utf8>` element.
+    #[must_use]
+    pub fn to_vec(self) -> Vec<L::Owned> {
+        self.iter_owned().collect()
+    }
 }
 
+/// `for item in &list` — iterates the items without consuming the view.
+impl<'a, L: LogicalType + 'a> IntoIterator for &ListValue<'a, L> {
+    type Item = L::Value<'a>;
+    type IntoIter = ListValue<'a, L>;
+
+    fn into_iter(self) -> Self::IntoIter {
+        *self
+    }
+}
+
+/// `list[index]`: like [`ListValue::value`], but borrows from the array —
+/// `&list[i]` is `&str` for a `List<Utf8>` element, `&i64` for `List<i64>`.
+///
+/// Available for items that can be borrowed from the array: strings, binaries,
+/// and primitives — but not `bool`, `Option<…>`, or nested `List<…>` items.
+///
+/// Panics if out of bounds (like [`ListValue::value`]).
+impl<L: RefType> std::ops::Index<usize> for ListValue<'_, L> {
+    type Output = L::Ref;
+
+    fn index(&self, index: usize) -> &Self::Output {
+        assert!(
+            index < self.len(),
+            "ListValue index {index} out of bounds for length {}",
+            self.len()
+        );
+        L::value_ref(self.values, self.index + index)
+    }
+}
+
+impl<'a, L: PrimitiveType> ListValue<'a, L> {
+    /// The items as a contiguous zero-copy slice,
+    /// e.g. `&[f32]` for a `List<f32>` element.
+    ///
+    /// Only available for primitive and fixed-size binary items
+    /// (`bool` is excluded: arrow bit-packs it).
+    #[must_use]
+    pub fn as_slice(&self) -> &'a [L::Native] {
+        &L::values(self.values)[self.index..self.end]
+    }
+}
+
+// Iteration mirrors a slice's: the items live in `self.index..self.end`, all
+// in bounds, so the combinators are overridden to skip the per-element `Option`
+// plumbing of the default `next`-based implementations. (Primitive items have
+// an even faster path: [`ListValue::as_slice`].)
 impl<'a, L: LogicalType + 'a> Iterator for ListValue<'a, L> {
     type Item = L::Value<'a>;
 
@@ -186,10 +357,81 @@ impl<'a, L: LogicalType + 'a> Iterator for ListValue<'a, L> {
         let remaining = self.end - self.index;
         (remaining, Some(remaining))
     }
+
+    fn count(self) -> usize {
+        self.end - self.index
+    }
+
+    fn last(self) -> Option<Self::Item> {
+        (self.index < self.end).then(|| L::value(self.values, self.end - 1))
+    }
+
+    fn nth(&mut self, n: usize) -> Option<Self::Item> {
+        match self.index.checked_add(n) {
+            Some(target) if target < self.end => {
+                self.index = target + 1;
+                Some(L::value(self.values, target))
+            }
+            _ => {
+                self.index = self.end;
+                None
+            }
+        }
+    }
+
+    fn fold<B, F>(self, init: B, mut f: F) -> B
+    where
+        F: FnMut(B, Self::Item) -> B,
+    {
+        let Self { values, index, end } = self;
+        let mut acc = init;
+        for i in index..end {
+            acc = f(acc, L::value(values, i));
+        }
+        acc
+    }
+}
+
+impl<'a, L: LogicalType + 'a> DoubleEndedIterator for ListValue<'a, L> {
+    fn next_back(&mut self) -> Option<Self::Item> {
+        if self.index < self.end {
+            self.end -= 1;
+            Some(L::value(self.values, self.end))
+        } else {
+            None
+        }
+    }
+
+    fn nth_back(&mut self, n: usize) -> Option<Self::Item> {
+        match self.end.checked_sub(n + 1) {
+            Some(target) if self.index <= target => {
+                self.end = target;
+                Some(L::value(self.values, target))
+            }
+            _ => {
+                self.end = self.index;
+                None
+            }
+        }
+    }
+
+    fn rfold<B, F>(self, init: B, mut f: F) -> B
+    where
+        F: FnMut(B, Self::Item) -> B,
+    {
+        let Self { values, index, end } = self;
+        let mut acc = init;
+        for i in (index..end).rev() {
+            acc = f(acc, L::value(values, i));
+        }
+        acc
+    }
 }
 
 impl<'a, L: LogicalType + 'a> ExactSizeIterator for ListValue<'a, L> {}
 
+impl<'a, L: LogicalType + 'a> std::iter::FusedIterator for ListValue<'a, L> {}
+
 /// Counts the nulls among the *reachable* items of a list array (`List` or
 /// `LargeList` — it is generic over the offset width):
 /// items inside the ranges of valid (non-null) rows.