Skip to main content

ListVector

Struct ListVector 

Source
pub struct ListVector;
Expand description

Operations on LIST vectors.

A LIST vector stores a duckdb_list_entry { offset: u64, length: u64 } per row in the parent vector, and all element values in a flat child vector.

§Write workflow

  1. reserve — ensure child vector has capacity.
  2. Write element values into the child via get_child + VectorWriter.
  3. set_size — tell DuckDB how many elements were written.
  4. set_entry — write the offset/length for each parent row.

Implementations§

Source§

impl ListVector

Source

pub unsafe fn get_child(vector: duckdb_vector) -> duckdb_vector

Returns the child vector containing all list elements (flat, across all rows).

§Safety
  • vector must be a valid DuckDB LIST vector.
  • The returned handle is borrowed from vector.
Source

pub unsafe fn get_size(vector: duckdb_vector) -> usize

Returns the total number of elements currently in the child vector.

§Safety

vector must be a valid DuckDB LIST vector.

Source

pub unsafe fn set_size(vector: duckdb_vector, size: usize)

Sets the number of elements in the child vector.

Call after writing all element values. DuckDB uses this to know how many child elements are valid.

§Safety
  • vector must be a valid DuckDB LIST vector.
  • size must equal the number of elements written into the child vector.
Source

pub unsafe fn reserve(vector: duckdb_vector, capacity: usize)

Reserves capacity in the child vector for at least capacity elements.

Call before writing elements to ensure the child vector has enough space.

ListBuilder checks the capacity limit for you; prefer it when element counts come from input data.

§Safety
  • vector must be a valid DuckDB LIST vector.
  • capacity must not exceed max_child_capacity(vector): 2^37 bytes in the widest buffer the child’s type grows, as a power-of-two element count. Above it DuckDB throws an OutOfRangeException (VectorListBuffer::Reserve, Vector::Resize), which the C API does not catch, so the process aborts. Below it, a reservation the allocator cannot satisfy aborts the same way, so a capacity derived from input data should be bounded to what fits in memory.
Source

pub unsafe fn set_entry( vector: duckdb_vector, row_idx: usize, offset: u64, length: u64, )

Writes the offset/length metadata entry for a parent row.

This tells DuckDB where in the flat child vector this row’s elements start and how many elements it has.

§Safety
  • vector must be a valid DuckDB LIST vector.
  • row_idx must be a valid row index in the parent vector.
  • offset + length must not exceed the size of the child vector.
Source

pub unsafe fn get_entry( vector: duckdb_vector, row_idx: usize, ) -> duckdb_list_entry

Returns the duckdb_list_entry for a given row (for reading).

§NULL rows

DuckDB writes no entry for a NULL row. The slot holds stale or never-written bytes, so for a NULL row offset and length are arbitrary: on DuckDB 2.0.0 a nullif(l, []) column gave NULL rows with lengths around 7·10¹³, and a loop over such an entry reads far outside the child vector (a segmentation fault in a minority of runs). Check the row’s validity before using the entry, or call get_entry_checked, which does that and also refuses an entry that does not lie inside the child.

§Safety
  • vector must be a valid DuckDB LIST vector.
  • row_idx must be a valid row index.
  • For a NULL row the returned entry is meaningless and must not be used to index the child.
Source

pub unsafe fn get_entry_checked( vector: duckdb_vector, row_idx: usize, ) -> Option<duckdb_list_entry>

Returns the entry for a row that is not NULL, or None for a NULL row or an entry that does not lie inside the child vector.

This is the read-side companion of get_entry: it checks the row’s validity first (a vector with no validity mask has no NULL rows), then that offset + length does not exceed get_size. The elements of a returned entry can be indexed in a child reader created with get_size elements.

§Safety
  • vector must be a valid DuckDB LIST vector.
  • row_idx must be a valid row index.
Source

pub unsafe fn child_writer(vector: duckdb_vector) -> VectorWriter

Creates a VectorWriter for the child vector (elements).

§Safety
  • vector must be a valid DuckDB LIST vector.
  • Every index written must be below the capacity most recently reserved with ListVector::reserve.
  • The writer must not be used after the child is grown again (ListVector::reserve with a larger capacity, or a ListBuilder row that grows it): growing reallocates the child’s data and validity buffers, and the writer caches pointers to both. Fetch a new writer after every reserve.
Source

pub unsafe fn child_reader( vector: duckdb_vector, element_count: usize, ) -> VectorReader

Creates a VectorReader for the child vector (reading list elements).

§Safety
  • vector must be a valid DuckDB LIST vector.
  • element_count must equal the total number of elements in the child.

Trait Implementations§

Source§

impl Debug for ListVector

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.