Struct arrow::array::BufferBuilder

pub struct BufferBuilder<T: ArrowNativeType> { /* private fields */ }

Builder for creating a Buffer object.

A Buffer is the underlying data structure of Arrow’s Arrays.

For all supported types, there are type definitions for the generic version of BufferBuilder<T>, e.g. UInt8BufferBuilder.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(100);
builder.append_slice(&[42, 43, 44]);
builder.append(45);
let buffer = builder.finish();

assert_eq!(unsafe { buffer.typed_data::<u8>() }, &[42, 43, 44, 45]);

Implementations

impl<T: ArrowNativeType> BufferBuilder<T>

pub fn new(capacity: usize) -> Self

Creates a new builder with initial capacity for at least capacity elements of type T.

The capacity can later be manually adjusted with the reserve() method. Also the append(), append_slice() and advance() methods automatically increase the capacity if needed.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);

assert!(builder.capacity() >= 10);

pub fn len(&self) -> usize

Returns the current number of array elements in the internal buffer.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.append(42);

assert_eq!(builder.len(), 1);

pub fn is_empty(&self) -> bool

Returns whether the internal buffer is empty.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.append(42);

assert_eq!(builder.is_empty(), false);

pub fn capacity(&self) -> usize

Returns the actual capacity (number of elements) of the internal buffer.

Note: the internal capacity returned by this method might be larger than what you’d expect after setting the capacity in the new() or reserve() functions.

pub fn advance(&mut self, i: usize)

Increases the number of elements in the internal buffer by n and resizes the buffer as needed.

The values of the newly added elements are 0. This method is usually used when appending NULL values to the buffer as they still require physical memory space.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.advance(2);

assert_eq!(builder.len(), 2);

pub fn reserve(&mut self, n: usize)

Reserves memory for at least n more elements of type T.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.reserve(10);

assert!(builder.capacity() >= 20);

pub fn append(&mut self, v: T)

Appends a value of type T into the builder, growing the internal buffer as needed.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.append(42);

assert_eq!(builder.len(), 1);

pub fn append_n(&mut self, n: usize, v: T)

Appends a value of type T into the builder N times, growing the internal buffer as needed.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.append_n(10, 42);

assert_eq!(builder.len(), 10);

pub fn append_slice(&mut self, slice: &[T])

Appends a slice of type T, growing the internal buffer as needed.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.append_slice(&[42, 44, 46]);

assert_eq!(builder.len(), 3);

pub unsafe fn append_trusted_len_iter(
    &mut self,
    iter: impl IntoIterator<Item = T>
)

Safety

This requires the iterator be a trusted length. This could instead require the iterator implement TrustedLen once that is stabilized.

pub fn finish(&mut self) -> Buffer

Resets this builder and returns an immutable Buffer.

Example:

use arrow::array::UInt8BufferBuilder;

let mut builder = UInt8BufferBuilder::new(10);
builder.append_slice(&[42, 44, 46]);

let buffer = builder.finish();

assert_eq!(unsafe { buffer.typed_data::<u8>() }, &[42, 44, 46]);

Trait Implementations

impl<T: Debug + ArrowNativeType> Debug for BufferBuilder<T>

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

Formats the value using the given formatter.