Struct arrow2::buffer::MutableBuffer

pub struct MutableBuffer<T: NativeType> { /* fields omitted */ }

A MutableBuffer is this crates’ interface to store types that are byte-like, such as i32. It behaves like a Vec, with the following differences:

• memory is allocated along cache lines and in multiple of 64 bytes.
• it can only hold types supported by the arrow format (u8-u64, i8-i128, f32,f64 and crate::types::days_ms) A MutableBuffer can be converted to a Buffer via .into.

Example

let mut buffer = MutableBuffer::<u32>::new();
buffer.push(256);
buffer.extend_from_slice(&[1]);
let buffer: Buffer<u32> = buffer.into();
assert_eq!(buffer.as_slice(), &[256, 1])

Implementations

impl<T: NativeType> MutableBuffer<T>

pub fn new() -> Self

Creates an empty MutableBuffer. This does not allocate in the heap.

pub fn with_capacity(capacity: usize) -> Self

Allocate a new MutableBuffer with initial capacity to be at least capacity.

pub fn from_len_zeroed(len: usize) -> Self

Allocates a new MutableBuffer with len and capacity to be at least len where all bytes are guaranteed to be 0u8.

Example

let mut buffer = MutableBuffer::<u8>::from_len_zeroed(127);
assert_eq!(buffer.len(), 127);
assert!(buffer.capacity() >= 127);
let data = buffer.as_mut_slice();
assert_eq!(data[126], 0u8);

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

Ensures that this buffer has at least self.len + additional bytes. This re-allocates iff self.len + additional > capacity.

Example

let mut buffer = MutableBuffer::<u8>::new();
buffer.reserve(253); // allocates for the first time
(0..253u8).for_each(|i| buffer.push(i)); // no reallocation
let buffer: Buffer<u8> = buffer.into();
assert_eq!(buffer.len(), 253);

pub fn resize(&mut self, new_len: usize, value: T)

Resizes the buffer, either truncating its contents (with no change in capacity), or growing it (potentially reallocating it) and writing value in the newly available bytes.

Example

let mut buffer = MutableBuffer::<u8>::new();
buffer.resize(253, 2); // allocates for the first time
assert_eq!(buffer.as_slice()[252], 2u8);

pub fn is_empty(&self) -> bool

Returns whether this buffer is empty or not.

pub fn len(&self) -> usize

Returns the length (the number of bytes written) in this buffer. The invariant buffer.len() <= buffer.capacity() is always upheld.

pub fn capacity(&self) -> usize

Returns the total capacity in this buffer. The invariant buffer.len() <= buffer.capacity() is always upheld.

pub fn clear(&mut self)

Clear all existing data from this buffer.

pub fn truncate(&mut self, len: usize)

Shortens the buffer. If len is greater or equal to the buffers’ current length, this has no effect.

pub fn as_slice(&self) -> &[T]

Returns the data stored in this buffer as a slice.

pub fn as_mut_slice(&mut self) -> &mut [T]

Returns the data stored in this buffer as a mutable slice.

pub fn as_ptr(&self) -> *const T

Returns a raw pointer to this buffer’s internal memory This pointer is guaranteed to be aligned along cache-lines.

pub fn as_mut_ptr(&mut self) -> *mut T

Returns a mutable raw pointer to this buffer’s internal memory This pointer is guaranteed to be aligned along cache-lines.

pub fn extend_from_slice(&mut self, items: &[T])

Extends this buffer from a slice of items that can be represented in bytes, increasing its capacity if needed.

Example

let mut buffer = MutableBuffer::new();
buffer.extend_from_slice(&[2u32, 0]);
assert_eq!(buffer.len(), 2)

pub fn push(&mut self, item: T)

Extends the buffer with a new item, increasing its capacity if needed.

Example

let mut buffer = MutableBuffer::new();
buffer.push(256u32);
assert_eq!(buffer.len(), 1)

pub unsafe fn set_len(&mut self, len: usize)

Safety

The caller must ensure that the buffer was properly initialized up to len.

pub fn extend_constant(&mut self, additional: usize, value: T)

pub fn shrink_to_fit(&mut self)

Shrinks the capacity of the MutableBuffer to fit its current length. The new capacity will be a multiple of 64 bytes.

Example

let mut buffer = MutableBuffer::<u64>::with_capacity(16);
assert_eq!(buffer.capacity(), 16);
buffer.push(1);
buffer.push(2);

buffer.shrink_to_fit();
assert!(buffer.capacity() == 8);

impl<T: NativeType> MutableBuffer<T>

pub fn extend_from_trusted_len_iter<I: TrustedLen<Item = T>>(
    &mut self,
    iterator: I
)

Extends self from a TrustedLen iterator.

pub unsafe fn extend_from_trusted_len_iter_unchecked<I: Iterator<Item = T>>(
    &mut self,
    iterator: I
)

Extends self from an iterator.

Safety

This method assumes that the iterator’s size is correct and is undefined behavior to use it on an iterator that reports an incorrect length.

pub fn from_trusted_len_iter<I: Iterator<Item = T> + TrustedLen>(
    iterator: I
) -> Self

Creates a MutableBuffer from an Iterator with a trusted (upper) length. Prefer this to collect whenever possible, as it is faster ~60% faster.

Example

let v = vec![1u32];
let iter = v.iter().map(|x| x * 2);
let buffer = unsafe { MutableBuffer::from_trusted_len_iter(iter) };
assert_eq!(buffer.len(), 1)

Safety

This method assumes that the iterator’s size is correct and is undefined behavior to use it on an iterator that reports an incorrect length.

pub unsafe fn from_trusted_len_iter_unchecked<I: Iterator<Item = T>>(
    iterator: I
) -> Self

Creates a MutableBuffer from an Iterator with a trusted (upper) length. Prefer this to collect whenever possible, as it is faster ~60% faster.

Example

let v = vec![1u32];
let iter = v.iter().map(|x| x * 2);
let buffer = unsafe { MutableBuffer::from_trusted_len_iter(iter) };
assert_eq!(buffer.len(), 1)

Safety

This method assumes that the iterator’s size is correct and is undefined behavior to use it on an iterator that reports an incorrect length.

pub fn try_from_trusted_len_iter<E, I: TrustedLen<Item = Result<T, E>>>(
    iterator: I
) -> Result<Self, E>

Creates a MutableBuffer from an Iterator with a TrustedLen iterator, or errors if any of the items of the iterator is an error.

pub unsafe fn try_from_trusted_len_iter_unchecked<E, I: Iterator<Item = Result<T, E>>>(
    iterator: I
) -> Result<Self, E>

Creates a MutableBuffer from an Iterator with a trusted (upper) length or errors if any of the items of the iterator is an error. Prefer this to collect whenever possible, as it is faster ~60% faster. The only difference between this and [try_from_trusted_len_iter] is that this works on any iterator, while try_from_trusted_len_iter requires the iterator to implement the trait TrustedLen, which not every iterator currently implements due to limitations of the Rust compiler.

Safety

This method assumes that the iterator’s size is correct and is undefined behavior to use it on an iterator that reports an incorrect length.

impl MutableBuffer<u8>

pub fn from_chunk_iter<I: TrustedLen<Item = u64>>(iter: I) -> Self

pub unsafe fn from_chunk_iter_unchecked<I: Iterator<Item = u64>>(
    iter: I
) -> Self

Safety

This method assumes that the iterator’s size is correct and is undefined behavior to use it on an iterator that reports an incorrect length.

Trait Implementations

impl<T: Debug + NativeType> Debug for MutableBuffer<T>

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

Formats the value using the given formatter.

impl<T: NativeType> Default for MutableBuffer<T>

fn default() -> Self

Returns the “default value” for a type.

impl<T: NativeType> Deref for MutableBuffer<T>

type Target = [T]

The resulting type after dereferencing.

fn deref(&self) -> &[T]

Dereferences the value.

impl<T: NativeType> DerefMut for MutableBuffer<T>

fn deref_mut(&mut self) -> &mut [T]

Mutably dereferences the value.

impl<T: NativeType> Drop for MutableBuffer<T>

fn drop(&mut self)

Executes the destructor for this type.

impl<A: NativeType> Extend<A> for MutableBuffer<A>

fn extend<T: IntoIterator<Item = A>>(&mut self, iter: T)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬 This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬 This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl<T: NativeType> From<MutableBuffer<T>> for Buffer<T>

fn from(buffer: MutableBuffer<T>) -> Self

Performs the conversion.

impl From<MutableBuffer<u64>> for MutableBuffer<u8>

fn from(buffer: MutableBuffer<u64>) -> Self

Performs the conversion.

impl<T: NativeType, P: AsRef<[T]>> From<P> for MutableBuffer<T>

fn from(slice: P) -> Self

Performs the conversion.

impl<T: NativeType> FromIterator<T> for MutableBuffer<T>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: NativeType> PartialEq<MutableBuffer<T>> for MutableBuffer<T>

fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=.