docs: Add examples for creating MutableBuffer from Vec

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<u32>`
+/// ```
+/// # 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<T>`
+/// ```
+/// # 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};