Chore: rename some methods (#4710)

Makes 2 method names more consistent:

- `fixed_size_list_at` -> `fixed_size_list_elements_at` for
`FixedSizeListArray`
- `elements_at` -> `list_elements_at` for `ListArray`

Also adds a better doc comment for `FixedSizeListArray`

---------

Signed-off-by: Connor Tsui <[email protected]>

Author: connortsui20

encodings/sparse/src/canonical.rs

@@ -321,7 +321,7 @@ fn canonicalize_sparse_fixed_size_list_inner<I: NativePType>(
 
         // Append the patch value, handling null patches by appending defaults.
         if values.validity().is_valid(patch_idx) {
-            let patch_list = values.fixed_size_list_at(patch_idx);
+            let patch_list = values.fixed_size_list_elements_at(patch_idx);
             for i in 0..list_size as usize {
                 builder
                     .append_scalar(&patch_list.scalar_at(i))

vortex-array/src/arrays/constant/canonical.rs

@@ -471,7 +471,7 @@ mod tests {
 
         // Check that each list is [10, 20, 30].
         for i in 0..4 {
-            let list = canonical.fixed_size_list_at(i);
+            let list = canonical.fixed_size_list_elements_at(i);
             let list_primitive = list.to_primitive();
             assert_eq!(list_primitive.as_slice::<i32>(), [10, 20, 30]);
         }

vortex-array/src/arrays/fixed_size_list/mod.rs

@@ -19,6 +19,49 @@ mod tests;
 mod compute;
 
 /// The canonical encoding for fixed-size list arrays.
+///
+/// A fixed-size list array stores lists where each list has the same number of elements. This is
+/// similar to a 2D array or matrix where the inner dimension is fixed.
+///
+/// ## Data Layout
+///
+/// Unlike [`ListArray`] which uses offsets, `FixedSizeListArray` stores elements contiguously and
+/// uses a fixed `list_size`:
+///
+/// - **Elements array**: A flat array containing all list elements concatenated together
+/// - **List size**: The fixed number of elements in each list
+/// - **Validity**: Optional mask indicating which lists are null
+///
+/// The list at index `i` contains elements from `elements[i * list_size..(i + 1) * list_size]`.
+///
+/// [`ListArray`]: crate::arrays::ListArray
+///
+/// # Examples
+///
+/// ```
+/// use vortex_array::arrays::{FixedSizeListArray, PrimitiveArray};
+/// use vortex_array::validity::Validity;
+/// use vortex_array::IntoArray;
+/// use vortex_buffer::buffer;
+///
+/// // Create a fixed-size list array representing [[1, 2] [3, 4], [5, 6], [7, 8]]
+/// let elements = buffer![1i32, 2, 3, 4, 5, 6, 7, 8].into_array();
+/// let list_size = 2;
+///
+/// let fixed_list_array = FixedSizeListArray::new(
+///     elements.into_array(),
+///     list_size,
+///     Validity::NonNullable,
+///     4, // 4 lists
+/// );
+///
+/// assert_eq!(fixed_list_array.len(), 4);
+/// assert_eq!(fixed_list_array.list_size(), 2);
+///
+/// // Access individual lists
+/// let first_list = fixed_list_array.fixed_size_list_elements_at(0);
+/// assert_eq!(first_list.len(), 2);
+/// ```
 #[derive(Clone, Debug)]
 pub struct FixedSizeListArray {
     /// The [`DType`] of the fixed-size list.
@@ -145,12 +188,12 @@ impl FixedSizeListArray {
         self.list_size
     }
 
-    /// Returns the elements at the given index from the list array.
+    /// Returns the elements of the fixed-size list scalar at the given index of the list array.
     ///
     /// # Panics
     ///
     /// Panics if the index is out of bounds.
-    pub fn fixed_size_list_at(&self, index: usize) -> ArrayRef {
+    pub fn fixed_size_list_elements_at(&self, index: usize) -> ArrayRef {
         debug_assert!(
             index < self.len,
             "index out of bounds: the len is {} but the index is {index}",

vortex-array/src/arrays/fixed_size_list/tests/basic.rs

@@ -32,22 +32,22 @@ fn test_basic_fixed_size_list() {
     ));
 
     // Check the actual values in each list.
-    let first_list = fsl.fixed_size_list_at(0);
+    let first_list = fsl.fixed_size_list_elements_at(0);
     assert_eq!(first_list.scalar_at(0), 1i32.into());
     assert_eq!(first_list.scalar_at(1), 2i32.into());
     assert_eq!(first_list.scalar_at(2), 3i32.into());
 
-    let second_list = fsl.fixed_size_list_at(1);
+    let second_list = fsl.fixed_size_list_elements_at(1);
     assert_eq!(second_list.scalar_at(0), 4i32.into());
     assert_eq!(second_list.scalar_at(1), 5i32.into());
     assert_eq!(second_list.scalar_at(2), 6i32.into());
 
-    let third_list = fsl.fixed_size_list_at(2);
+    let third_list = fsl.fixed_size_list_elements_at(2);
     assert_eq!(third_list.scalar_at(0), 7i32.into());
     assert_eq!(third_list.scalar_at(1), 8i32.into());
     assert_eq!(third_list.scalar_at(2), 9i32.into());
 
-    let fourth_list = fsl.fixed_size_list_at(3);
+    let fourth_list = fsl.fixed_size_list_elements_at(3);
     assert_eq!(fourth_list.scalar_at(0), 10i32.into());
     assert_eq!(fourth_list.scalar_at(1), 11i32.into());
     assert_eq!(fourth_list.scalar_at(2), 12i32.into());
@@ -73,7 +73,7 @@ fn test_scalar_at() {
     );
 
     // Additionally check individual elements via fixed_size_list_at.
-    let first_list = fsl.fixed_size_list_at(0);
+    let first_list = fsl.fixed_size_list_elements_at(0);
     assert_eq!(first_list.scalar_at(0), 1i32.into());
     assert_eq!(first_list.scalar_at(1), 2i32.into());
     assert_eq!(first_list.scalar_at(2), 3i32.into());
@@ -90,7 +90,7 @@ fn test_scalar_at() {
     );
 
     // Additionally check individual elements via fixed_size_list_at.
-    let second_list = fsl.fixed_size_list_at(1);
+    let second_list = fsl.fixed_size_list_elements_at(1);
     assert_eq!(second_list.scalar_at(0), 4i32.into());
     assert_eq!(second_list.scalar_at(1), 5i32.into());
     assert_eq!(second_list.scalar_at(2), 6i32.into());
@@ -105,13 +105,13 @@ fn test_fixed_size_list_at() {
     let fsl = FixedSizeListArray::new(elements, list_size, Validity::AllValid, len);
 
     // Get the first list [1.0, 2.0].
-    let first_list = fsl.fixed_size_list_at(0);
+    let first_list = fsl.fixed_size_list_elements_at(0);
     assert_eq!(first_list.len(), list_size as usize);
     assert_eq!(first_list.scalar_at(0), 1.0f64.into());
     assert_eq!(first_list.scalar_at(1), 2.0f64.into());
 
     // Get the third list [5.0, 6.0].
-    let third_list = fsl.fixed_size_list_at(2);
+    let third_list = fsl.fixed_size_list_elements_at(2);
     assert_eq!(third_list.len(), list_size as usize);
     assert_eq!(third_list.scalar_at(0), 5.0f64.into());
     assert_eq!(third_list.scalar_at(1), 6.0f64.into());

vortex-array/src/arrays/fixed_size_list/tests/filter.rs

@@ -62,12 +62,12 @@ fn test_filter_alternating() {
     assert_eq!(filtered_fsl.elements().len(), 4);
 
     // First list should be [1, 2].
-    let first = filtered_fsl.fixed_size_list_at(0);
+    let first = filtered_fsl.fixed_size_list_elements_at(0);
     assert_eq!(first.scalar_at(0), 1i32.into());
     assert_eq!(first.scalar_at(1), 2i32.into());
 
     // Second list should be [5, 6].
-    let second = filtered_fsl.fixed_size_list_at(1);
+    let second = filtered_fsl.fixed_size_list_elements_at(1);
     assert_eq!(second.scalar_at(0), 5i32.into());
     assert_eq!(second.scalar_at(1), 6i32.into());
 }
@@ -86,13 +86,13 @@ fn test_filter_selective() {
     assert_eq!(filtered_fsl.elements().len(), 6);
 
     // First list should be [4.0, 5.0, 6.0].
-    let first = filtered_fsl.fixed_size_list_at(0);
+    let first = filtered_fsl.fixed_size_list_elements_at(0);
     assert_eq!(first.scalar_at(0), 4.0f64.into());
     assert_eq!(first.scalar_at(1), 5.0f64.into());
     assert_eq!(first.scalar_at(2), 6.0f64.into());
 
     // Second list should be [7.0, 8.0, 9.0].
-    let second = filtered_fsl.fixed_size_list_at(1);
+    let second = filtered_fsl.fixed_size_list_elements_at(1);
     assert_eq!(second.scalar_at(0), 7.0f64.into());
     assert_eq!(second.scalar_at(1), 8.0f64.into());
     assert_eq!(second.scalar_at(2), 9.0f64.into());
@@ -126,7 +126,7 @@ fn test_filter_single_element() {
     assert_eq!(filtered_fsl.list_size(), 3);
     assert_eq!(filtered_fsl.elements().len(), 3);
 
-    let first = filtered_fsl.fixed_size_list_at(0);
+    let first = filtered_fsl.fixed_size_list_elements_at(0);
     assert_eq!(first.scalar_at(0), 42i32.into());
     assert_eq!(first.scalar_at(1), 43i32.into());
     assert_eq!(first.scalar_at(2), 44i32.into());
@@ -222,12 +222,12 @@ fn test_filter_with_nulls() {
     assert_eq!(filtered_fsl.list_size(), 2);
 
     // First list should be [1, 2] and valid.
-    let first = filtered_fsl.fixed_size_list_at(0);
+    let first = filtered_fsl.fixed_size_list_elements_at(0);
     assert_eq!(first.scalar_at(0), 1i32.into());
     assert_eq!(first.scalar_at(1), 2i32.into());
 
     // Second list should be [5, 6] and valid.
-    let second = filtered_fsl.fixed_size_list_at(1);
+    let second = filtered_fsl.fixed_size_list_elements_at(1);
     assert_eq!(second.scalar_at(0), 5i32.into());
     assert_eq!(second.scalar_at(1), 6i32.into());
 }
@@ -292,15 +292,15 @@ fn test_filter_nested_fixed_size_lists() {
     assert_eq!(filtered_inner.list_size(), 2);
 
     // Check the actual values.
-    let inner_list_0 = filtered_inner.fixed_size_list_at(0);
+    let inner_list_0 = filtered_inner.fixed_size_list_elements_at(0);
     assert_eq!(inner_list_0.scalar_at(0), 7i32.into());
     assert_eq!(inner_list_0.scalar_at(1), 8i32.into());
 
-    let inner_list_1 = filtered_inner.fixed_size_list_at(1);
+    let inner_list_1 = filtered_inner.fixed_size_list_elements_at(1);
     assert_eq!(inner_list_1.scalar_at(0), 9i32.into());
     assert_eq!(inner_list_1.scalar_at(1), 10i32.into());
 
-    let inner_list_2 = filtered_inner.fixed_size_list_at(2);
+    let inner_list_2 = filtered_inner.fixed_size_list_elements_at(2);
     assert_eq!(inner_list_2.scalar_at(0), 11i32.into());
     assert_eq!(inner_list_2.scalar_at(1), 12i32.into());
 }
@@ -442,7 +442,7 @@ fn test_complex_filter_pattern() {
     // Original indices kept: 0, 1, 3, 6, 7, 8.
     let expected_starts = [0i32, 3, 9, 18, 21, 24];
     for (i, &start) in expected_starts.iter().enumerate() {
-        let list = filtered_fsl.fixed_size_list_at(i);
+        let list = filtered_fsl.fixed_size_list_elements_at(i);
         assert_eq!(list.scalar_at(0), (start).into());
         assert_eq!(list.scalar_at(1), (start + 1).into());
         assert_eq!(list.scalar_at(2), (start + 2).into());
@@ -474,13 +474,13 @@ fn test_filter_large_list_size() {
     assert_eq!(filtered_fsl.elements().len(), 3 * list_size as usize);
 
     // Check that the correct lists were kept (indices 1, 3, 4).
-    let list_0 = filtered_fsl.fixed_size_list_at(0);
+    let list_0 = filtered_fsl.fixed_size_list_elements_at(0);
     assert_eq!(list_0.scalar_at(0), 100i64.into()); // Start of original list 1.
 
-    let list_1 = filtered_fsl.fixed_size_list_at(1);
+    let list_1 = filtered_fsl.fixed_size_list_elements_at(1);
     assert_eq!(list_1.scalar_at(0), 300i64.into()); // Start of original list 3.
 
-    let list_2 = filtered_fsl.fixed_size_list_at(2);
+    let list_2 = filtered_fsl.fixed_size_list_elements_at(2);
     assert_eq!(list_2.scalar_at(0), 400i64.into()); // Start of original list 4.
 }
 
@@ -556,13 +556,13 @@ fn test_mask_expansion_threshold_boundary() {
     assert_eq!(filtered_fsl.elements().len(), 3 * list_size as usize);
 
     // Verify correct elements were kept.
-    let first = filtered_fsl.fixed_size_list_at(0);
+    let first = filtered_fsl.fixed_size_list_elements_at(0);
     assert_eq!(first.scalar_at(0), (5i32 * list_size as i32).into());
 
-    let second = filtered_fsl.fixed_size_list_at(1);
+    let second = filtered_fsl.fixed_size_list_elements_at(1);
     assert_eq!(second.scalar_at(0), (25i32 * list_size as i32).into());
 
-    let third = filtered_fsl.fixed_size_list_at(2);
+    let third = filtered_fsl.fixed_size_list_elements_at(2);
     assert_eq!(third.scalar_at(0), (75i32 * list_size as i32).into());
 
     // Test with list_size == 7 (just below threshold).

vortex-array/src/arrays/fixed_size_list/tests/nested.rs

@@ -58,7 +58,7 @@ fn test_fsl_of_fsl_basic() {
     ));
 
     // Get the first outer list.
-    let first_outer = outer_fsl.fixed_size_list_at(0);
+    let first_outer = outer_fsl.fixed_size_list_elements_at(0);
     assert_eq!(first_outer.len(), outer_list_size as usize);
 
     // The first outer list should contain 3 inner lists.
@@ -68,38 +68,50 @@ fn test_fsl_of_fsl_basic() {
 
     // Check the actual values in the nested structure.
     // First outer list contains: [[1,2], [3,4], [5,6]].
-    let first_outer_list = outer_fsl.fixed_size_list_at(0);
+    let first_outer_list = outer_fsl.fixed_size_list_elements_at(0);
 
     // Check first inner list [1,2].
-    let inner_list_0 = first_outer_list.to_fixed_size_list().fixed_size_list_at(0);
+    let inner_list_0 = first_outer_list
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(0);
     assert_eq!(inner_list_0.scalar_at(0), 1i32.into());
     assert_eq!(inner_list_0.scalar_at(1), 2i32.into());
 
     // Check second inner list [3,4].
-    let inner_list_1 = first_outer_list.to_fixed_size_list().fixed_size_list_at(1);
+    let inner_list_1 = first_outer_list
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(1);
     assert_eq!(inner_list_1.scalar_at(0), 3i32.into());
     assert_eq!(inner_list_1.scalar_at(1), 4i32.into());
 
     // Check third inner list [5,6].
-    let inner_list_2 = first_outer_list.to_fixed_size_list().fixed_size_list_at(2);
+    let inner_list_2 = first_outer_list
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(2);
     assert_eq!(inner_list_2.scalar_at(0), 5i32.into());
     assert_eq!(inner_list_2.scalar_at(1), 6i32.into());
 
     // Second outer list contains: [[7,8], [9,10], [11,12]].
-    let second_outer_list = outer_fsl.fixed_size_list_at(1);
+    let second_outer_list = outer_fsl.fixed_size_list_elements_at(1);
 
     // Check first inner list [7,8].
-    let inner_list_0 = second_outer_list.to_fixed_size_list().fixed_size_list_at(0);
+    let inner_list_0 = second_outer_list
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(0);
     assert_eq!(inner_list_0.scalar_at(0), 7i32.into());
     assert_eq!(inner_list_0.scalar_at(1), 8i32.into());
 
     // Check second inner list [9,10].
-    let inner_list_1 = second_outer_list.to_fixed_size_list().fixed_size_list_at(1);
+    let inner_list_1 = second_outer_list
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(1);
     assert_eq!(inner_list_1.scalar_at(0), 9i32.into());
     assert_eq!(inner_list_1.scalar_at(1), 10i32.into());
 
     // Check third inner list [11,12].
-    let inner_list_2 = second_outer_list.to_fixed_size_list().fixed_size_list_at(2);
+    let inner_list_2 = second_outer_list
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(2);
     assert_eq!(inner_list_2.scalar_at(0), 11i32.into());
     assert_eq!(inner_list_2.scalar_at(1), 12i32.into());
 }
@@ -194,25 +206,29 @@ fn test_deeply_nested_fsl() {
 
     // Check the actual deeply nested values.
     // Structure: [[[1,2],[3,4]],[[5,6],[7,8]]].
-    let top_level = level3.fixed_size_list_at(0);
-    let level2_0 = top_level.to_fixed_size_list().fixed_size_list_at(0);
-    let level2_1 = top_level.to_fixed_size_list().fixed_size_list_at(1);
+    let top_level = level3.fixed_size_list_elements_at(0);
+    let level2_0 = top_level
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(0);
+    let level2_1 = top_level
+        .to_fixed_size_list()
+        .fixed_size_list_elements_at(1);
 
     // First level-2 list: [[1,2],[3,4]].
-    let level1_0_0 = level2_0.to_fixed_size_list().fixed_size_list_at(0);
+    let level1_0_0 = level2_0.to_fixed_size_list().fixed_size_list_elements_at(0);
     assert_eq!(level1_0_0.scalar_at(0), 1i32.into());
     assert_eq!(level1_0_0.scalar_at(1), 2i32.into());
 
-    let level1_0_1 = level2_0.to_fixed_size_list().fixed_size_list_at(1);
+    let level1_0_1 = level2_0.to_fixed_size_list().fixed_size_list_elements_at(1);
     assert_eq!(level1_0_1.scalar_at(0), 3i32.into());
     assert_eq!(level1_0_1.scalar_at(1), 4i32.into());
 
     // Second level-2 list: [[5,6],[7,8]].
-    let level1_1_0 = level2_1.to_fixed_size_list().fixed_size_list_at(0);
+    let level1_1_0 = level2_1.to_fixed_size_list().fixed_size_list_elements_at(0);
     assert_eq!(level1_1_0.scalar_at(0), 5i32.into());
     assert_eq!(level1_1_0.scalar_at(1), 6i32.into());
 
-    let level1_1_1 = level2_1.to_fixed_size_list().fixed_size_list_at(1);
+    let level1_1_1 = level2_1.to_fixed_size_list().fixed_size_list_elements_at(1);
     assert_eq!(level1_1_1.scalar_at(0), 7i32.into());
     assert_eq!(level1_1_1.scalar_at(1), 8i32.into());
 }