16935267080

Committed 13 Aug 2025 11:00AM UTC coverage: 24.312% (-63.3%) from 87.658%

Build # 16935267080

Build Type

Pull #4226

github

Committed by

web-flow

Commit Message

Merge 81b48c7fb into baa6ea202

Pull Request Pull Request #4226: Support converting TimestampTZ to and from duckdb

Run Details

0 of 2 new or added lines in 1 file covered. (0.0%)

20666 existing lines in 469 files now uncovered.

8726 of 35892 relevant lines covered (24.31%)

147.74 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

49.66

/vortex-buffer/src/buffer.rs

// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright the Vortex contributors

use std::any::type_name;
use std::cmp::Ordering;
use std::collections::Bound;
use std::fmt::{Debug, Formatter};
use std::hash::{Hash, Hasher};
use std::ops::{Deref, RangeBounds};

use bytes::{Buf, Bytes};
use vortex_error::{VortexExpect, vortex_panic};

use crate::debug::TruncatedDebug;
use crate::trusted_len::TrustedLen;
use crate::{Alignment, BufferMut, ByteBuffer};

/// An immutable buffer of items of `T`.
#[derive(Clone)]
pub struct Buffer<T> {
    pub(crate) bytes: Bytes,
    pub(crate) length: usize,
    pub(crate) alignment: Alignment,
    pub(crate) _marker: std::marker::PhantomData<T>,
}

impl<T> PartialEq for Buffer<T> {
    fn eq(&self, other: &Self) -> bool {
        self.bytes == other.bytes
    }
}

impl<T> Eq for Buffer<T> {}

impl<T> Ord for Buffer<T> {
    fn cmp(&self, other: &Self) -> Ordering {
        self.bytes.cmp(&other.bytes)
    }
}

impl<T> PartialOrd for Buffer<T> {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

impl<T> Hash for Buffer<T> {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.bytes.as_ref().hash(state)
    }
}

impl<T> Buffer<T> {
    /// Returns a new `Buffer<T>` copied from the provided `Vec<T>`, `&[T]`, etc.
    ///
    /// Due to our underlying usage of `bytes::Bytes`, we are unable to take zero-copy ownership
    /// of the provided `Vec<T>` while maintaining the ability to convert it back into a mutable
    /// buffer. We could fix this by forking `Bytes`, or in many other complex ways, but for now
    /// callers should prefer to construct `Buffer<T>` from a `BufferMut<T>`.
    pub fn copy_from(values: impl AsRef<[T]>) -> Self {
        BufferMut::copy_from(values).freeze()
    }

    /// Returns a new `Buffer<T>` copied from the provided slice and with the requested alignment.
    pub fn copy_from_aligned(values: impl AsRef<[T]>, alignment: Alignment) -> Self {
        BufferMut::copy_from_aligned(values, alignment).freeze()
    }

    /// Create a new zeroed `Buffer` with the given value.
    pub fn zeroed(len: usize) -> Self {
        Self::zeroed_aligned(len, Alignment::of::<T>())
    }

    /// Create a new zeroed `Buffer` with the given value.
    pub fn zeroed_aligned(len: usize, alignment: Alignment) -> Self {
        BufferMut::zeroed_aligned(len, alignment).freeze()
    }

    /// Create a new empty `ByteBuffer` with the provided alignment.
    pub fn empty() -> Self {
        BufferMut::empty().freeze()
    }

    /// Create a new empty `ByteBuffer` with the provided alignment.
    pub fn empty_aligned(alignment: Alignment) -> Self {
        BufferMut::empty_aligned(alignment).freeze()
    }

    /// Create a new full `ByteBuffer` with the given value.
    pub fn full(item: T, len: usize) -> Self
    where
        T: Copy,
    {
        BufferMut::full(item, len).freeze()
    }

    /// Create a `Buffer<T>` zero-copy from a `ByteBuffer`.
    ///
    /// ## Panics
    ///
    /// Panics if the buffer is not aligned to the size of `T`, or the length is not a multiple of
    /// the size of `T`.
    pub fn from_byte_buffer(buffer: ByteBuffer) -> Self {
        // TODO(ngates): should this preserve the current alignment of the buffer?
        Self::from_byte_buffer_aligned(buffer, Alignment::of::<T>())
    }

    /// Create a `Buffer<T>` zero-copy from a `ByteBuffer`.
    ///
    /// ## Panics
    ///
    /// Panics if the buffer is not aligned to the given alignment, if the length is not a multiple
    /// of the size of `T`, or if the given alignment is not aligned to that of `T`.
    pub fn from_byte_buffer_aligned(buffer: ByteBuffer, alignment: Alignment) -> Self {
        Self::from_bytes_aligned(buffer.into_inner(), alignment)
    }

    /// Create a `Buffer<T>` zero-copy from a `Bytes`.
    ///
    /// ## Panics
    ///
    /// Panics if the buffer is not aligned to the size of `T`, or the length is not a multiple of
    /// the size of `T`.
    pub fn from_bytes_aligned(bytes: Bytes, alignment: Alignment) -> Self {
        if !alignment.is_aligned_to(Alignment::of::<T>()) {
            vortex_panic!(
                "Alignment {} must be compatible with the scalar type's alignment {}",
                alignment,
                Alignment::of::<T>(),
            );
        }
        if bytes.as_ptr().align_offset(*alignment) != 0 {
            vortex_panic!(
                "Bytes alignment must align to the requested alignment {}",
                alignment,
            );
        }
        if bytes.len() % size_of::<T>() != 0 {
            vortex_panic!(
                "Bytes length {} must be a multiple of the scalar type's size {}",
                bytes.len(),
                size_of::<T>()
            );
        }
        let length = bytes.len() / size_of::<T>();
        Self {
            bytes,
            length,
            alignment,
            _marker: Default::default(),
        }
    }

    /// Create a buffer with values from the TrustedLen iterator.
    /// Should be preferred over `from_iter` when the iterator is known to be `TrustedLen`.
    pub fn from_trusted_len_iter<I: TrustedLen<Item = T>>(iter: I) -> Self {
        let (_, high) = iter.size_hint();
        let mut buffer =
            BufferMut::with_capacity(high.vortex_expect("TrustedLen iterator has no upper bound"));
        buffer.extend_trusted(iter);
        buffer.freeze()
    }

    /// Returns the length of the buffer in elements of type T.
    #[inline(always)]
    pub fn len(&self) -> usize {
        self.length
    }

    /// Returns whether the buffer is empty.
    #[inline(always)]
    pub fn is_empty(&self) -> bool {
        self.length == 0
    }

    /// Returns the alignment of the buffer.
    #[inline(always)]
    pub fn alignment(&self) -> Alignment {
        self.alignment
    }

    /// Returns a slice over the buffer of elements of type T.
    #[inline(always)]
    pub fn as_slice(&self) -> &[T] {
        let raw_slice = self.bytes.as_ref();
        // SAFETY: alignment of Buffer is checked on construction
        unsafe { std::slice::from_raw_parts(raw_slice.as_ptr().cast(), self.length) }
    }

    /// Returns an iterator over the buffer of elements of type T.
    pub fn iter(&self) -> Iter<'_, T> {
        Iter {
            inner: self.as_slice().iter(),
        }
    }

    /// Returns a slice of self for the provided range.
    ///
    /// # Panics
    ///
    /// Requires that `begin <= end` and `end <= self.len()`.
    /// Also requires that both `begin` and `end` are aligned to the buffer's required alignment.
    #[inline(always)]
    pub fn slice(&self, range: impl RangeBounds<usize>) -> Self {
        self.slice_with_alignment(range, self.alignment)
    }

    /// Returns a slice of self for the provided range, with no guarantees about the resulting
    /// alignment.
    ///
    /// # Panics
    ///
    /// Requires that `begin <= end` and `end <= self.len()`.
    #[inline(always)]
    pub fn slice_unaligned(&self, range: impl RangeBounds<usize>) -> Self {
        self.slice_with_alignment(range, Alignment::of::<u8>())
    }

    /// Returns a slice of self for the provided range, ensuring the resulting slice has the
    /// given alignment.
    ///
    /// # Panics
    ///
    /// Requires that `begin <= end` and `end <= self.len()`.
    /// Also requires that both `begin` and `end` are aligned to the given alignment.
    pub fn slice_with_alignment(
        &self,
        range: impl RangeBounds<usize>,
        alignment: Alignment,
    ) -> Self {
        let len = self.len();
        let begin = match range.start_bound() {
            Bound::Included(&n) => n,
            Bound::Excluded(&n) => n.checked_add(1).vortex_expect("out of range"),
            Bound::Unbounded => 0,
        };
        let end = match range.end_bound() {
            Bound::Included(&n) => n.checked_add(1).vortex_expect("out of range"),
            Bound::Excluded(&n) => n,
            Bound::Unbounded => len,
        };

        if begin > end {
            vortex_panic!(
                "range start must not be greater than end: {:?} <= {:?}",
                begin,
                end
            );
        }
        if end > len {
            vortex_panic!("range end out of bounds: {:?} <= {:?}", end, len);
        }

        if end == begin {
            // We prefer to return a new empty buffer instead of sharing this one and creating a
            // strong reference just to hold an empty slice.
            return Self::empty_aligned(alignment);
        }

        let begin_byte = begin * size_of::<T>();
        let end_byte = end * size_of::<T>();

        if !begin_byte.is_multiple_of(*alignment) {
            vortex_panic!("range start must be aligned to {:?}", alignment);
        }
        if !end_byte.is_multiple_of(*alignment) {
            vortex_panic!("range end must be aligned to {:?}", alignment);
        }
        if !alignment.is_aligned_to(Alignment::of::<T>()) {
            vortex_panic!("Slice alignment must at least align to type T")
        }

        Self {
            bytes: self.bytes.slice(begin_byte..end_byte),
            length: end - begin,
            alignment,
            _marker: Default::default(),
        }
    }

    /// Returns a slice of self that is equivalent to the given subset.
    ///
    /// When processing the buffer you will often end up with &\[T\] that is a subset
    /// of the underlying buffer. This function turns the slice into a slice of the buffer
    /// it has been taken from.
    ///
    /// # Panics:
    /// Requires that the given sub slice is in fact contained within the Bytes buffer; otherwise this function will panic.
    #[inline(always)]
    pub fn slice_ref(&self, subset: &[T]) -> Self {
        self.slice_ref_with_alignment(subset, Alignment::of::<T>())
    }

    /// Returns a slice of self that is equivalent to the given subset.
    ///
    /// When processing the buffer you will often end up with &\[T\] that is a subset
    /// of the underlying buffer. This function turns the slice into a slice of the buffer
    /// it has been taken from.
    ///
    /// # Panics:
    /// Requires that the given sub slice is in fact contained within the Bytes buffer; otherwise this function will panic.
    /// Also requires that the given alignment aligns to the type of slice and is smaller or equal to the buffers alignment
    pub fn slice_ref_with_alignment(&self, subset: &[T], alignment: Alignment) -> Self {
        if !alignment.is_aligned_to(Alignment::of::<T>()) {
            vortex_panic!("slice_ref alignment must at least align to type T")
        }

        if !self.alignment.is_aligned_to(alignment) {
            vortex_panic!("slice_ref subset alignment must at least align to the buffer alignment")
        }

        if subset.as_ptr().align_offset(*alignment) != 0 {
            vortex_panic!("slice_ref subset must be aligned to {:?}", alignment);
        }

        let subset_u8 =
            unsafe { std::slice::from_raw_parts(subset.as_ptr().cast(), size_of_val(subset)) };

        Self {
            bytes: self.bytes.slice_ref(subset_u8),
            length: subset.len(),
            alignment,
            _marker: Default::default(),
        }
    }

    /// Returns the underlying aligned buffer.
    pub fn inner(&self) -> &Bytes {
        debug_assert_eq!(
            self.length * size_of::<T>(),
            self.bytes.len(),
            "Own length has to be the same as the underlying bytes length"
        );
        &self.bytes
    }

    /// Returns the underlying aligned buffer.
    pub fn into_inner(self) -> Bytes {
        debug_assert_eq!(
            self.length * size_of::<T>(),
            self.bytes.len(),
            "Own length has to be the same as the underlying bytes length"
        );
        self.bytes
    }

    /// Return the ByteBuffer for this `Buffer<T>`.
    pub fn into_byte_buffer(self) -> ByteBuffer {
        ByteBuffer {
            bytes: self.bytes,
            length: self.length * size_of::<T>(),
            alignment: self.alignment,
            _marker: Default::default(),
        }
    }

    /// Convert self into `BufferMut<T>`, copying if there are multiple strong references.
    pub fn into_mut(self) -> BufferMut<T> {
        self.try_into_mut()
            .unwrap_or_else(|buffer| BufferMut::<T>::copy_from(&buffer))
    }

    /// Try to convert self into `BufferMut<T>` if there is only a single strong reference.
    pub fn try_into_mut(self) -> Result<BufferMut<T>, Self> {
        self.bytes
            .try_into_mut()
            .map(|bytes| BufferMut {
                bytes,
                length: self.length,
                alignment: self.alignment,
                _marker: Default::default(),
            })
            .map_err(|bytes| Self {
                bytes,
                length: self.length,
                alignment: self.alignment,
                _marker: Default::default(),
            })
    }

    /// Returns whether a `Buffer<T>` is aligned to the given alignment.
    pub fn is_aligned(&self, alignment: Alignment) -> bool {
        self.bytes.as_ptr().align_offset(*alignment) == 0
    }

    /// Return a `Buffer<T>` with the given alignment. Where possible, this will be zero-copy.
    pub fn aligned(mut self, alignment: Alignment) -> Self {
        if self.as_ptr().align_offset(*alignment) == 0 {
            self.alignment = alignment;
            self
        } else {
            #[cfg(feature = "warn-copy")]
            {
                let bt = std::backtrace::Backtrace::capture();
                log::warn!(
                    "Buffer is not aligned to requested alignment {alignment}, copying: {bt}"
                )
            }
            Self::copy_from_aligned(self, alignment)
        }
    }

    /// Return a `Buffer<T>` with the given alignment. Panics if the buffer is not aligned.
    pub fn ensure_aligned(mut self, alignment: Alignment) -> Self {
        if self.as_ptr().align_offset(*alignment) == 0 {
            self.alignment = alignment;
            self
        } else {
            vortex_panic!("Buffer is not aligned to requested alignment {}", alignment)
        }
    }
}

/// An iterator over Buffer elements.
///
/// This is an analog to the `std::slice::Iter` type.
pub struct Iter<'a, T> {
    inner: std::slice::Iter<'a, T>,
}

impl<'a, T> Iterator for Iter<'a, T> {
    type Item = &'a T;

    fn next(&mut self) -> Option<Self::Item> {
        self.inner.next()
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }

    fn count(self) -> usize {
        self.inner.count()
    }

    fn last(self) -> Option<Self::Item> {
        self.inner.last()
    }

    fn nth(&mut self, n: usize) -> Option<Self::Item> {
        self.inner.nth(n)
    }
}

impl<T> ExactSizeIterator for Iter<'_, T> {
    fn len(&self) -> usize {
        self.inner.len()
    }
}

impl<T: Debug> Debug for Buffer<T> {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        f.debug_struct(&format!("Buffer<{}>", type_name::<T>()))
            .field("length", &self.length)
            .field("alignment", &self.alignment)
            .field("as_slice", &TruncatedDebug(self.as_slice()))
            .finish()
    }
}

impl<T> Deref for Buffer<T> {
    type Target = [T];

    fn deref(&self) -> &Self::Target {
        self.as_slice()
    }
}

impl<T> AsRef<[T]> for Buffer<T> {
    fn as_ref(&self) -> &[T] {
        self.as_slice()
    }
}

impl<T> FromIterator<T> for Buffer<T> {
    fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
        BufferMut::from_iter(iter).freeze()
    }
}

/// Only for `Buffer<u8>` can we zero-copy from a `Vec<u8>` since we can use a 1-byte alignment.
impl From<Vec<u8>> for ByteBuffer {
    fn from(value: Vec<u8>) -> Self {
        Self::from(Bytes::from(value))
    }
}

/// Only for `Buffer<u8>` can we zero-copy from a `Bytes` since we can use a 1-byte alignment.
impl From<Bytes> for ByteBuffer {
    fn from(bytes: Bytes) -> Self {
        let length = bytes.len();
        Self {
            bytes,
            length,
            alignment: Alignment::of::<u8>(),
            _marker: Default::default(),
        }
    }
}

impl Buf for ByteBuffer {
    fn remaining(&self) -> usize {
        self.len()
    }

    fn chunk(&self) -> &[u8] {
        self.as_slice()
    }

    fn advance(&mut self, cnt: usize) {
        if !cnt.is_multiple_of(*self.alignment) {
            vortex_panic!(
                "Cannot advance buffer by {} items, resulting alignment is not {}",
                cnt,
                self.alignment
            );
        }
        self.bytes.advance(cnt);
        self.length -= cnt;
    }
}

/// Owned iterator over a [`Buffer`].
pub struct BufferIterator<T> {
    buffer: Buffer<T>,
    index: usize,
}

impl<T: Copy> Iterator for BufferIterator<T> {
    type Item = T;

    fn next(&mut self) -> Option<Self::Item> {
        (self.index < self.buffer.len()).then(move || {
            let value = self.buffer[self.index];
            self.index += 1;
            value
        })
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        let remaining = self.buffer.len() - self.index;
        (remaining, Some(remaining))
    }
}

impl<T: Copy> IntoIterator for Buffer<T> {
    type Item = T;
    type IntoIter = BufferIterator<T>;

    fn into_iter(self) -> Self::IntoIter {
        BufferIterator {
            buffer: self,
            index: 0,
        }
    }
}

impl<T> From<BufferMut<T>> for Buffer<T> {
    fn from(value: BufferMut<T>) -> Self {
        value.freeze()
    }
}

#[cfg(test)]
mod test {
    use bytes::Buf;

    use crate::{Alignment, ByteBuffer, buffer};

    #[test]
    fn align() {
        let buf = buffer![0u8, 1, 2];
        let aligned = buf.aligned(Alignment::new(32));
        assert_eq!(aligned.alignment(), Alignment::new(32));
        assert_eq!(aligned.as_slice(), &[0, 1, 2]);
    }

    #[test]
    fn slice() {
        let buf = buffer![0, 1, 2, 3, 4];
        assert_eq!(buf.slice(1..3).as_slice(), &[1, 2]);
        assert_eq!(buf.slice(1..=3).as_slice(), &[1, 2, 3]);
    }

    #[test]
    fn slice_unaligned() {
        let buf = buffer![0i32, 1, 2, 3, 4].into_byte_buffer();
        // With a regular slice, this would panic. See [`slice_bad_alignment`].
        buf.slice_unaligned(1..2);
    }

    #[test]
    #[should_panic]
    fn slice_bad_alignment() {
        let buf = buffer![0i32, 1, 2, 3, 4].into_byte_buffer();
        // We should only be able to slice this buffer on 4-byte (i32) boundaries.
        buf.slice(1..2);
    }

    #[test]
    fn bytes_buf() {
        let mut buf = ByteBuffer::copy_from("helloworld".as_bytes());
        assert_eq!(buf.remaining(), 10);
        assert_eq!(buf.chunk(), b"helloworld");

        Buf::advance(&mut buf, 5);
        assert_eq!(buf.remaining(), 5);
        assert_eq!(buf.as_slice(), b"world");
        assert_eq!(buf.chunk(), b"world");
    }
}

1	// SPDX-License-Identifier: Apache-2.0
2	// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4	use std::any::type_name;
5	use std::cmp::Ordering;
6	use std::collections::Bound;
7	use std::fmt::{Debug, Formatter};
8	use std::hash::{Hash, Hasher};
9	use std::ops::{Deref, RangeBounds};
10
11	use bytes::{Buf, Bytes};
12	use vortex_error::{VortexExpect, vortex_panic};
13
14	use crate::debug::TruncatedDebug;
15	use crate::trusted_len::TrustedLen;
16	use crate::{Alignment, BufferMut, ByteBuffer};
17
18	/// An immutable buffer of items of `T`.
19	#[derive(Clone)]
20	pub struct Buffer<T> {
21	pub(crate) bytes: Bytes,
22	pub(crate) length: usize,
23	pub(crate) alignment: Alignment,
24	pub(crate) _marker: std::marker::PhantomData<T>,
25	}
26
27	impl<T> PartialEq for Buffer<T> {
UNCOV 28	fn eq(&self, other: &Self) -> bool {	×
UNCOV 29	self.bytes == other.bytes	×
UNCOV 30	}	×
31	}
32
33	impl<T> Eq for Buffer<T> {}
34
35	impl<T> Ord for Buffer<T> {
UNCOV 36	fn cmp(&self, other: &Self) -> Ordering {	×
UNCOV 37	self.bytes.cmp(&other.bytes)	×
UNCOV 38	}	×
39	}
40
41	impl<T> PartialOrd for Buffer<T> {
42	fn partial_cmp(&self, other: &Self) -> Option<Ordering> {	×
43	Some(self.cmp(other))	×
44	}	×
45	}
46
47	impl<T> Hash for Buffer<T> {
UNCOV 48	fn hash<H: Hasher>(&self, state: &mut H) {	×
UNCOV 49	self.bytes.as_ref().hash(state)	×
UNCOV 50	}	×
51	}
52
53	impl<T> Buffer<T> {
54	/// Returns a new `Buffer<T>` copied from the provided `Vec<T>`, `&[T]`, etc.
55	///
56	/// Due to our underlying usage of `bytes::Bytes`, we are unable to take zero-copy ownership
57	/// of the provided `Vec<T>` while maintaining the ability to convert it back into a mutable
58	/// buffer. We could fix this by forking `Bytes`, or in many other complex ways, but for now
59	/// callers should prefer to construct `Buffer<T>` from a `BufferMut<T>`.
60	pub fn copy_from(values: impl AsRef<[T]>) -> Self {	10✔
61	BufferMut::copy_from(values).freeze()	10✔
62	}	10✔
63
64	/// Returns a new `Buffer<T>` copied from the provided slice and with the requested alignment.
65	pub fn copy_from_aligned(values: impl AsRef<[T]>, alignment: Alignment) -> Self {	10✔
66	BufferMut::copy_from_aligned(values, alignment).freeze()	10✔
67	}	10✔
68
69	/// Create a new zeroed `Buffer` with the given value.
70	pub fn zeroed(len: usize) -> Self {	14✔
71	Self::zeroed_aligned(len, Alignment::of::<T>())	14✔
72	}	14✔
73
74	/// Create a new zeroed `Buffer` with the given value.
75	pub fn zeroed_aligned(len: usize, alignment: Alignment) -> Self {	22✔
76	BufferMut::zeroed_aligned(len, alignment).freeze()	22✔
77	}	22✔
78
79	/// Create a new empty `ByteBuffer` with the provided alignment.
80	pub fn empty() -> Self {	10✔
81	BufferMut::empty().freeze()	10✔
82	}	10✔
83
84	/// Create a new empty `ByteBuffer` with the provided alignment.
UNCOV 85	pub fn empty_aligned(alignment: Alignment) -> Self {	×
UNCOV 86	BufferMut::empty_aligned(alignment).freeze()	×
UNCOV 87	}	×
88
89	/// Create a new full `ByteBuffer` with the given value.
UNCOV 90	pub fn full(item: T, len: usize) -> Self	×
UNCOV 91	where	×
UNCOV 92	T: Copy,	×
93	{
UNCOV 94	BufferMut::full(item, len).freeze()	×
UNCOV 95	}	×
96
97	/// Create a `Buffer<T>` zero-copy from a `ByteBuffer`.
98	///
99	/// ## Panics
100	///
101	/// Panics if the buffer is not aligned to the size of `T`, or the length is not a multiple of
102	/// the size of `T`.
103	pub fn from_byte_buffer(buffer: ByteBuffer) -> Self {	284✔
104	// TODO(ngates): should this preserve the current alignment of the buffer?
105	Self::from_byte_buffer_aligned(buffer, Alignment::of::<T>())	284✔
106	}	284✔
107
108	/// Create a `Buffer<T>` zero-copy from a `ByteBuffer`.
109	///
110	/// ## Panics
111	///
112	/// Panics if the buffer is not aligned to the given alignment, if the length is not a multiple
113	/// of the size of `T`, or if the given alignment is not aligned to that of `T`.
114	pub fn from_byte_buffer_aligned(buffer: ByteBuffer, alignment: Alignment) -> Self {	284✔
115	Self::from_bytes_aligned(buffer.into_inner(), alignment)	284✔
116	}	284✔
117
118	/// Create a `Buffer<T>` zero-copy from a `Bytes`.
119	///
120	/// ## Panics
121	///
122	/// Panics if the buffer is not aligned to the size of `T`, or the length is not a multiple of
123	/// the size of `T`.
124	pub fn from_bytes_aligned(bytes: Bytes, alignment: Alignment) -> Self {	284✔
125	if !alignment.is_aligned_to(Alignment::of::<T>()) {	284✔
126	vortex_panic!(	×
127	"Alignment {} must be compatible with the scalar type's alignment {}",	×
128	alignment,
129	Alignment::of::<T>(),	×
130	);
131	}	284✔
132	if bytes.as_ptr().align_offset(*alignment) != 0 {	284✔
133	vortex_panic!(	×
134	"Bytes alignment must align to the requested alignment {}",	×
135	alignment,
136	);
137	}	284✔
138	if bytes.len() % size_of::<T>() != 0 {	284✔
139	vortex_panic!(	×
140	"Bytes length {} must be a multiple of the scalar type's size {}",	×
141	bytes.len(),	×
142	size_of::<T>()
143	);
144	}	284✔
145	let length = bytes.len() / size_of::<T>();	284✔
146	Self {	284✔
147	bytes,	284✔
148	length,	284✔
149	alignment,	284✔
150	_marker: Default::default(),	284✔
151	}	284✔
152	}	284✔
153
154	/// Create a buffer with values from the TrustedLen iterator.
155	/// Should be preferred over `from_iter` when the iterator is known to be `TrustedLen`.
UNCOV 156	pub fn from_trusted_len_iter<I: TrustedLen<Item = T>>(iter: I) -> Self {	×
UNCOV 157	let (_, high) = iter.size_hint();	×
UNCOV 158	let mut buffer =	×
UNCOV 159	BufferMut::with_capacity(high.vortex_expect("TrustedLen iterator has no upper bound"));	×
UNCOV 160	buffer.extend_trusted(iter);	×
UNCOV 161	buffer.freeze()	×
UNCOV 162	}	×
163
164	/// Returns the length of the buffer in elements of type T.
165	#[inline(always)]
166	pub fn len(&self) -> usize {	24,884✔
167	self.length	24,884✔
168	}	24,884✔
169
170	/// Returns whether the buffer is empty.
171	#[inline(always)]
172	pub fn is_empty(&self) -> bool {	14✔
173	self.length == 0	14✔
174	}	14✔
175
176	/// Returns the alignment of the buffer.
177	#[inline(always)]
178	pub fn alignment(&self) -> Alignment {	104✔
179	self.alignment	104✔
180	}	104✔
181
182	/// Returns a slice over the buffer of elements of type T.
183	#[inline(always)]
184	pub fn as_slice(&self) -> &[T] {	22,362✔
185	let raw_slice = self.bytes.as_ref();	22,362✔
186	// SAFETY: alignment of Buffer is checked on construction
187	unsafe { std::slice::from_raw_parts(raw_slice.as_ptr().cast(), self.length) }	22,362✔
188	}	22,362✔
189
190	/// Returns an iterator over the buffer of elements of type T.
UNCOV 191	pub fn iter(&self) -> Iter<'_, T> {	×
UNCOV 192	Iter {	×
UNCOV 193	inner: self.as_slice().iter(),	×
UNCOV 194	}	×
UNCOV 195	}	×
196
197	/// Returns a slice of self for the provided range.
198	///
199	/// # Panics
200	///
201	/// Requires that `begin <= end` and `end <= self.len()`.
202	/// Also requires that both `begin` and `end` are aligned to the buffer's required alignment.
203	#[inline(always)]
204	pub fn slice(&self, range: impl RangeBounds<usize>) -> Self {	290✔
205	self.slice_with_alignment(range, self.alignment)	290✔
206	}	290✔
207
208	/// Returns a slice of self for the provided range, with no guarantees about the resulting
209	/// alignment.
210	///
211	/// # Panics
212	///
213	/// Requires that `begin <= end` and `end <= self.len()`.
214	#[inline(always)]
UNCOV 215	pub fn slice_unaligned(&self, range: impl RangeBounds<usize>) -> Self {	×
UNCOV 216	self.slice_with_alignment(range, Alignment::of::<u8>())	×
UNCOV 217	}	×
218
219	/// Returns a slice of self for the provided range, ensuring the resulting slice has the
220	/// given alignment.
221	///
222	/// # Panics
223	///
224	/// Requires that `begin <= end` and `end <= self.len()`.
225	/// Also requires that both `begin` and `end` are aligned to the given alignment.
226	pub fn slice_with_alignment(	290✔
227	&self,	290✔
228	range: impl RangeBounds<usize>,	290✔
229	alignment: Alignment,	290✔
230	) -> Self {	290✔
231	let len = self.len();	290✔
232	let begin = match range.start_bound() {	290✔
233	Bound::Included(&n) => n,	290✔
234	Bound::Excluded(&n) => n.checked_add(1).vortex_expect("out of range"),	×
235	Bound::Unbounded => 0,	×
236	};
237	let end = match range.end_bound() {	290✔
UNCOV 238	Bound::Included(&n) => n.checked_add(1).vortex_expect("out of range"),	×
239	Bound::Excluded(&n) => n,	290✔
240	Bound::Unbounded => len,	×
241	};
242
243	if begin > end {	290✔
244	vortex_panic!(	×
245	"range start must not be greater than end: {:?} <= {:?}",	×
246	begin,
247	end
248	);
249	}	290✔
250	if end > len {	290✔
251	vortex_panic!("range end out of bounds: {:?} <= {:?}", end, len);	×
252	}	290✔
253
254	if end == begin {	290✔
255	// We prefer to return a new empty buffer instead of sharing this one and creating a
256	// strong reference just to hold an empty slice.
UNCOV 257	return Self::empty_aligned(alignment);	×
258	}	290✔
259
260	let begin_byte = begin * size_of::<T>();	290✔
261	let end_byte = end * size_of::<T>();	290✔
262
263	if !begin_byte.is_multiple_of(*alignment) {	290✔
UNCOV 264	vortex_panic!("range start must be aligned to {:?}", alignment);	×
265	}	290✔
266	if !end_byte.is_multiple_of(*alignment) {	290✔
267	vortex_panic!("range end must be aligned to {:?}", alignment);	×
268	}	290✔
269	if !alignment.is_aligned_to(Alignment::of::<T>()) {	290✔
270	vortex_panic!("Slice alignment must at least align to type T")	×
271	}	290✔
272
273	Self {	290✔
274	bytes: self.bytes.slice(begin_byte..end_byte),	290✔
275	length: end - begin,	290✔
276	alignment,	290✔
277	_marker: Default::default(),	290✔
278	}	290✔
279	}	290✔
280
281	/// Returns a slice of self that is equivalent to the given subset.
282	///
283	/// When processing the buffer you will often end up with &\[T\] that is a subset
284	/// of the underlying buffer. This function turns the slice into a slice of the buffer
285	/// it has been taken from.
286	///
287	/// # Panics:
288	/// Requires that the given sub slice is in fact contained within the Bytes buffer; otherwise this function will panic.
289	#[inline(always)]
UNCOV 290	pub fn slice_ref(&self, subset: &[T]) -> Self {	×
UNCOV 291	self.slice_ref_with_alignment(subset, Alignment::of::<T>())	×
UNCOV 292	}	×
293
294	/// Returns a slice of self that is equivalent to the given subset.
295	///
296	/// When processing the buffer you will often end up with &\[T\] that is a subset
297	/// of the underlying buffer. This function turns the slice into a slice of the buffer
298	/// it has been taken from.
299	///
300	/// # Panics:
301	/// Requires that the given sub slice is in fact contained within the Bytes buffer; otherwise this function will panic.
302	/// Also requires that the given alignment aligns to the type of slice and is smaller or equal to the buffers alignment
UNCOV 303	pub fn slice_ref_with_alignment(&self, subset: &[T], alignment: Alignment) -> Self {	×
UNCOV 304	if !alignment.is_aligned_to(Alignment::of::<T>()) {	×
305	vortex_panic!("slice_ref alignment must at least align to type T")	×
UNCOV 306	}	×
307
UNCOV 308	if !self.alignment.is_aligned_to(alignment) {	×
309	vortex_panic!("slice_ref subset alignment must at least align to the buffer alignment")	×
UNCOV 310	}	×
311
UNCOV 312	if subset.as_ptr().align_offset(*alignment) != 0 {	×
313	vortex_panic!("slice_ref subset must be aligned to {:?}", alignment);	×
UNCOV 314	}	×
315
UNCOV 316	let subset_u8 =	×
UNCOV 317	unsafe { std::slice::from_raw_parts(subset.as_ptr().cast(), size_of_val(subset)) };	×
318
UNCOV 319	Self {	×
UNCOV 320	bytes: self.bytes.slice_ref(subset_u8),	×
UNCOV 321	length: subset.len(),	×
UNCOV 322	alignment,	×
UNCOV 323	_marker: Default::default(),	×
UNCOV 324	}	×
UNCOV 325	}	×
326
327	/// Returns the underlying aligned buffer.
328	pub fn inner(&self) -> &Bytes {	×
329	debug_assert_eq!(	×
330	self.length * size_of::<T>(),	×
331	self.bytes.len(),	×
332	"Own length has to be the same as the underlying bytes length"	×
333	);
334	&self.bytes	×
335	}	×
336
337	/// Returns the underlying aligned buffer.
338	pub fn into_inner(self) -> Bytes {	284✔
339	debug_assert_eq!(	284✔
340	self.length * size_of::<T>(),	284✔
341	self.bytes.len(),	284✔
342	"Own length has to be the same as the underlying bytes length"	×
343	);
344	self.bytes	284✔
345	}	284✔
346
347	/// Return the ByteBuffer for this `Buffer<T>`.
348	pub fn into_byte_buffer(self) -> ByteBuffer {	372✔
349	ByteBuffer {	372✔
350	bytes: self.bytes,	372✔
351	length: self.length * size_of::<T>(),	372✔
352	alignment: self.alignment,	372✔
353	_marker: Default::default(),	372✔
354	}	372✔
355	}	372✔
356
357	/// Convert self into `BufferMut<T>`, copying if there are multiple strong references.
UNCOV 358	pub fn into_mut(self) -> BufferMut<T> {	×
UNCOV 359	self.try_into_mut()	×
UNCOV 360	.unwrap_or_else(\|buffer\| BufferMut::<T>::copy_from(&buffer))	×
UNCOV 361	}	×
362
363	/// Try to convert self into `BufferMut<T>` if there is only a single strong reference.
UNCOV 364	pub fn try_into_mut(self) -> Result<BufferMut<T>, Self> {	×
UNCOV 365	self.bytes	×
UNCOV 366	.try_into_mut()	×
UNCOV 367	.map(\|bytes\| BufferMut {	×
UNCOV 368	bytes,	×
UNCOV 369	length: self.length,	×
UNCOV 370	alignment: self.alignment,	×
UNCOV 371	_marker: Default::default(),	×
UNCOV 372	})	×
UNCOV 373	.map_err(\|bytes\| Self {	×
UNCOV 374	bytes,	×
UNCOV 375	length: self.length,	×
UNCOV 376	alignment: self.alignment,	×
UNCOV 377	_marker: Default::default(),	×
UNCOV 378	})	×
UNCOV 379	}	×
380
381	/// Returns whether a `Buffer<T>` is aligned to the given alignment.
382	pub fn is_aligned(&self, alignment: Alignment) -> bool {	4✔
383	self.bytes.as_ptr().align_offset(*alignment) == 0	4✔
384	}	4✔
385
386	/// Return a `Buffer<T>` with the given alignment. Where possible, this will be zero-copy.
387	pub fn aligned(mut self, alignment: Alignment) -> Self {	64✔
388	if self.as_ptr().align_offset(*alignment) == 0 {	64✔
389	self.alignment = alignment;	62✔
390	self	62✔
391	} else {
392	#[cfg(feature = "warn-copy")]
393	{
394	let bt = std::backtrace::Backtrace::capture();
395	log::warn!(
396	"Buffer is not aligned to requested alignment {alignment}, copying: {bt}"
397	)
398	}
399	Self::copy_from_aligned(self, alignment)	2✔
400	}
401	}	64✔
402
403	/// Return a `Buffer<T>` with the given alignment. Panics if the buffer is not aligned.
404	pub fn ensure_aligned(mut self, alignment: Alignment) -> Self {	×
405	if self.as_ptr().align_offset(*alignment) == 0 {	×
406	self.alignment = alignment;	×
407	self	×
408	} else {
409	vortex_panic!("Buffer is not aligned to requested alignment {}", alignment)	×
410	}
411	}	×
412	}
413
414	/// An iterator over Buffer elements.
415	///
416	/// This is an analog to the `std::slice::Iter` type.
417	pub struct Iter<'a, T> {
418	inner: std::slice::Iter<'a, T>,
419	}
420
421	impl<'a, T> Iterator for Iter<'a, T> {
422	type Item = &'a T;
423
UNCOV 424	fn next(&mut self) -> Option<Self::Item> {	×
UNCOV 425	self.inner.next()	×
UNCOV 426	}	×
427
UNCOV 428	fn size_hint(&self) -> (usize, Option<usize>) {	×
UNCOV 429	self.inner.size_hint()	×
UNCOV 430	}	×
431
432	fn count(self) -> usize {	×
433	self.inner.count()	×
434	}	×
435
436	fn last(self) -> Option<Self::Item> {	×
437	self.inner.last()	×
438	}	×
439
440	fn nth(&mut self, n: usize) -> Option<Self::Item> {	×
441	self.inner.nth(n)	×
442	}	×
443	}
444
445	impl<T> ExactSizeIterator for Iter<'_, T> {
446	fn len(&self) -> usize {	×
447	self.inner.len()	×
448	}	×
449	}
450
451	impl<T: Debug> Debug for Buffer<T> {
UNCOV 452	fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {	×
UNCOV 453	f.debug_struct(&format!("Buffer<{}>", type_name::<T>()))	×
UNCOV 454	.field("length", &self.length)	×
UNCOV 455	.field("alignment", &self.alignment)	×
UNCOV 456	.field("as_slice", &TruncatedDebug(self.as_slice()))	×
UNCOV 457	.finish()	×
UNCOV 458	}	×
459	}
460
461	impl<T> Deref for Buffer<T> {
462	type Target = [T];
463
464	fn deref(&self) -> &Self::Target {	22,290✔
465	self.as_slice()	22,290✔
466	}	22,290✔
467	}
468
469	impl<T> AsRef<[T]> for Buffer<T> {
470	fn as_ref(&self) -> &[T] {	2✔
471	self.as_slice()	2✔
472	}	2✔
473	}
474
475	impl<T> FromIterator<T> for Buffer<T> {
476	fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {	12✔
477	BufferMut::from_iter(iter).freeze()	12✔
478	}	12✔
479	}
480
481	/// Only for `Buffer<u8>` can we zero-copy from a `Vec<u8>` since we can use a 1-byte alignment.
482	impl From<Vec<u8>> for ByteBuffer {
483	fn from(value: Vec<u8>) -> Self {	26✔
484	Self::from(Bytes::from(value))	26✔
485	}	26✔
486	}
487
488	/// Only for `Buffer<u8>` can we zero-copy from a `Bytes` since we can use a 1-byte alignment.
489	impl From<Bytes> for ByteBuffer {
490	fn from(bytes: Bytes) -> Self {	26✔
491	let length = bytes.len();	26✔
492	Self {	26✔
493	bytes,	26✔
494	length,	26✔
495	alignment: Alignment::of::<u8>(),	26✔
496	_marker: Default::default(),	26✔
497	}	26✔
498	}	26✔
499	}
500
501	impl Buf for ByteBuffer {
UNCOV 502	fn remaining(&self) -> usize {	×
UNCOV 503	self.len()	×
UNCOV 504	}	×
505
UNCOV 506	fn chunk(&self) -> &[u8] {	×
UNCOV 507	self.as_slice()	×
UNCOV 508	}	×
509
UNCOV 510	fn advance(&mut self, cnt: usize) {	×
UNCOV 511	if !cnt.is_multiple_of(*self.alignment) {	×
512	vortex_panic!(	×
513	"Cannot advance buffer by {} items, resulting alignment is not {}",	×
514	cnt,
515	self.alignment
516	);
UNCOV 517	}	×
UNCOV 518	self.bytes.advance(cnt);	×
UNCOV 519	self.length -= cnt;	×
UNCOV 520	}	×
521	}
522
523	/// Owned iterator over a [`Buffer`].
524	pub struct BufferIterator<T> {
525	buffer: Buffer<T>,
526	index: usize,
527	}
528
529	impl<T: Copy> Iterator for BufferIterator<T> {
530	type Item = T;
531
532	fn next(&mut self) -> Option<Self::Item> {	19,736✔
533	(self.index < self.buffer.len()).then(move \|\| {	19,736✔
534	let value = self.buffer[self.index];	19,698✔
535	self.index += 1;	19,698✔
536	value	19,698✔
537	})	19,698✔
538	}	19,736✔
539
540	fn size_hint(&self) -> (usize, Option<usize>) {	4✔
541	let remaining = self.buffer.len() - self.index;	4✔
542	(remaining, Some(remaining))	4✔
543	}	4✔
544	}
545
546	impl<T: Copy> IntoIterator for Buffer<T> {
547	type Item = T;
548	type IntoIter = BufferIterator<T>;
549
550	fn into_iter(self) -> Self::IntoIter {	34✔
551	BufferIterator {	34✔
552	buffer: self,	34✔
553	index: 0,	34✔
554	}	34✔
555	}	34✔
556	}
557
558	impl<T> From<BufferMut<T>> for Buffer<T> {
559	fn from(value: BufferMut<T>) -> Self {	20✔
560	value.freeze()	20✔
561	}	20✔
562	}
563
564	#[cfg(test)]
565	mod test {
566	use bytes::Buf;
567
568	use crate::{Alignment, ByteBuffer, buffer};
569
570	#[test]
571	fn align() {
572	let buf = buffer![0u8, 1, 2];
573	let aligned = buf.aligned(Alignment::new(32));
574	assert_eq!(aligned.alignment(), Alignment::new(32));
575	assert_eq!(aligned.as_slice(), &[0, 1, 2]);
576	}
577
578	#[test]
579	fn slice() {
580	let buf = buffer![0, 1, 2, 3, 4];
581	assert_eq!(buf.slice(1..3).as_slice(), &[1, 2]);
582	assert_eq!(buf.slice(1..=3).as_slice(), &[1, 2, 3]);
583	}
584
585	#[test]
586	fn slice_unaligned() {
587	let buf = buffer![0i32, 1, 2, 3, 4].into_byte_buffer();
588	// With a regular slice, this would panic. See [`slice_bad_alignment`].
589	buf.slice_unaligned(1..2);
590	}
591
592	#[test]
593	#[should_panic]
594	fn slice_bad_alignment() {
595	let buf = buffer![0i32, 1, 2, 3, 4].into_byte_buffer();
596	// We should only be able to slice this buffer on 4-byte (i32) boundaries.
597	buf.slice(1..2);
598	}
599
600	#[test]
601	fn bytes_buf() {
602	let mut buf = ByteBuffer::copy_from("helloworld".as_bytes());
603	assert_eq!(buf.remaining(), 10);
604	assert_eq!(buf.chunk(), b"helloworld");
605
606	Buf::advance(&mut buf, 5);
607	assert_eq!(buf.remaining(), 5);
608	assert_eq!(buf.as_slice(), b"world");
609	assert_eq!(buf.chunk(), b"world");
610	}
611	}

vortex-data / vortex / 16935267080

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous