diff --git a/arrow-buffer/src/buffer/mutable.rs b/arrow-buffer/src/buffer/mutable.rs index 7458bed3ca00..75f77242b9e1 100644 --- a/arrow-buffer/src/buffer/mutable.rs +++ b/arrow-buffer/src/buffer/mutable.rs @@ -33,13 +33,16 @@ use std::sync::Mutex; use super::Buffer; -/// A [`MutableBuffer`] is Arrow's interface to build a [`Buffer`] out of items or slices of items. +/// A [`MutableBuffer`] is a wrapper over memory regions, used to build +/// [`Buffer`]s out of items or slices of items. /// -/// [`Buffer`]s created from [`MutableBuffer`] (via `into`) are guaranteed to be aligned -/// along cache lines and in multiple of 64 bytes. +/// [`Buffer`]s created from [`MutableBuffer`] (via `into`) are guaranteed to be +/// aligned along cache lines and in multiples of 64 bytes. /// /// Use [MutableBuffer::push] to insert an item, [MutableBuffer::extend_from_slice] -/// to insert many items, and `into` to convert it to [`Buffer`]. +/// to insert many items, and `into` to convert it to [`Buffer`]. For typed data, +/// it is often more efficient to use [`Vec`] and convert it to [`Buffer`] rather +/// than using [`MutableBuffer`] (see examples below). /// /// # See Also /// * For a safe, strongly typed API consider using [`Vec`] and [`ScalarBuffer`](crate::ScalarBuffer) @@ -48,17 +51,34 @@ use super::Buffer; /// [`apply_bitwise_binary_op`]: crate::bit_util::apply_bitwise_binary_op /// [`apply_bitwise_unary_op`]: crate::bit_util::apply_bitwise_unary_op /// -/// # Example -/// +/// # Example: Creating a [`Buffer`] from a [`MutableBuffer`] /// ``` /// # use arrow_buffer::buffer::{Buffer, MutableBuffer}; /// let mut buffer = MutableBuffer::new(0); /// buffer.push(256u32); /// buffer.extend_from_slice(&[1u32]); -/// let buffer: Buffer = buffer.into(); +/// let buffer = Buffer::from(buffer); /// assert_eq!(buffer.as_slice(), &[0u8, 1, 0, 0, 1, 0, 0, 0]) /// ``` /// +/// The same can be achieved more efficiently by using a `Vec` +/// ``` +/// # use arrow_buffer::buffer::Buffer; +/// let mut vec = Vec::new(); +/// vec.push(256u32); +/// vec.extend_from_slice(&[1u32]); +/// let buffer = Buffer::from(vec); +/// assert_eq!(buffer.as_slice(), &[0u8, 1, 0, 0, 1, 0, 0, 0]); +/// ``` +/// +/// # Example: Creating a [`MutableBuffer`] from a `Vec` +/// ``` +/// # use arrow_buffer::buffer::MutableBuffer; +/// let vec = vec![1u32, 2, 3]; +/// let mutable_buffer = MutableBuffer::from(vec); // reuses the allocation from vec +/// assert_eq!(mutable_buffer.len(), 12); // 3 * 4 bytes +/// ``` +/// /// # Example: Creating a [`MutableBuffer`] from a [`Buffer`] /// ``` /// # use arrow_buffer::buffer::{Buffer, MutableBuffer};