1pub mod aligned;
30pub mod bitmap;
31pub mod scalar;
32
33use std::fmt;
34use std::sync::Arc;
35
36pub use crate::buffer::aligned::{ALIGNMENT, AlignedBuf, pad_to_alignment, padding_for};
37pub use crate::buffer::bitmap::{
38 Bitmap, BitmapBuilder, BitmapIter, count_set_bits, get_bit, set_bit,
39};
40pub use crate::buffer::scalar::ScalarBuffer;
41
42use crate::datatype::ArrowNativeType;
43use crate::error::{DataError, Result};
44
45#[derive(Clone)]
64pub struct Buffer {
65 data: Arc<AlignedBuf>,
67 offset: usize,
69 len: usize,
71}
72
73impl Buffer {
74 #[must_use]
76 pub fn new() -> Self {
77 Self::from(AlignedBuf::new())
78 }
79
80 #[must_use]
88 pub fn from_slice(bytes: &[u8]) -> Self {
89 Self::from(AlignedBuf::from_slice(bytes))
90 }
91
92 #[must_use]
94 pub fn zeroed(len: usize) -> Self {
95 Self::from(AlignedBuf::zeroed(len))
96 }
97
98 #[must_use]
110 pub fn from_scalars<T: ArrowNativeType>(values: &[T]) -> Self {
111 Self::from_slice(scalar::as_bytes(values))
112 }
113
114 #[must_use]
116 pub fn from_arc(data: Arc<AlignedBuf>) -> Self {
117 let len = data.len();
118 Self {
119 data,
120 offset: 0,
121 len,
122 }
123 }
124
125 #[inline]
127 #[must_use]
128 pub const fn len(&self) -> usize {
129 self.len
130 }
131
132 #[inline]
134 #[must_use]
135 pub const fn is_empty(&self) -> bool {
136 self.len == 0
137 }
138
139 #[inline]
141 #[must_use]
142 pub const fn offset(&self) -> usize {
143 self.offset
144 }
145
146 #[inline]
151 #[must_use]
152 pub fn backing_len(&self) -> usize {
153 self.data.len()
154 }
155
156 #[inline]
158 #[must_use]
159 pub fn as_slice(&self) -> &[u8] {
160 let all = self.data.as_slice();
161 let end = self.offset.saturating_add(self.len);
162 debug_assert!(end <= all.len(), "window invariant");
163 match all.get(self.offset..end) {
164 Some(window) => window,
165 None => &[],
168 }
169 }
170
171 #[inline]
173 #[must_use]
174 pub fn as_ptr(&self) -> *const u8 {
175 self.data.as_ptr().wrapping_add(self.offset)
176 }
177
178 #[must_use]
188 pub fn address_alignment(&self) -> usize {
189 let addr = self.as_ptr() as usize;
190 if addr == 0 {
191 return ALIGNMENT;
192 }
193 1usize << addr.trailing_zeros().min(usize::BITS - 1)
194 }
195
196 #[inline]
198 #[must_use]
199 pub fn is_aligned_to(&self, align: usize) -> bool {
200 align == 0 || (self.as_ptr() as usize).is_multiple_of(align)
201 }
202
203 #[must_use]
209 pub fn slice(&self, offset: usize, len: usize) -> Self {
210 let offset = offset.min(self.len);
211 let len = len.min(self.len - offset);
212 Self {
213 data: Arc::clone(&self.data),
214 offset: self.offset + offset,
215 len,
216 }
217 }
218
219 pub fn try_slice(&self, offset: usize, len: usize) -> Result<Self> {
232 if offset.saturating_add(len) > self.len {
233 return Err(DataError::SliceOutOfBounds {
234 offset,
235 len,
236 available: self.len,
237 });
238 }
239 Ok(self.slice(offset, len))
240 }
241
242 #[must_use]
244 pub fn share_count(&self) -> usize {
245 Arc::strong_count(&self.data)
246 }
247
248 pub fn typed<T: ArrowNativeType>(&self) -> Result<ScalarBuffer<T>> {
253 ScalarBuffer::try_new(self.clone())
254 }
255
256 pub fn into_aligned(self) -> core::result::Result<AlignedBuf, Self> {
277 let Self { data, offset, len } = self;
278 if offset != 0 || len != data.len() {
279 return Err(Self { data, offset, len });
280 }
281 Arc::try_unwrap(data).map_err(|data| Self { data, offset, len })
282 }
283
284 #[must_use]
300 pub fn realigned(&self) -> Self {
301 if self.is_aligned_to(ALIGNMENT) {
302 return self.clone();
303 }
304 Self::from_slice(self.as_slice())
305 }
306}
307
308impl Default for Buffer {
309 #[inline]
310 fn default() -> Self {
311 Self::new()
312 }
313}
314
315impl From<AlignedBuf> for Buffer {
316 #[inline]
317 fn from(buf: AlignedBuf) -> Self {
318 Self::from_arc(Arc::new(buf))
319 }
320}
321
322impl From<&[u8]> for Buffer {
323 #[inline]
324 fn from(bytes: &[u8]) -> Self {
325 Self::from_slice(bytes)
326 }
327}
328
329impl From<Vec<u8>> for Buffer {
330 #[inline]
331 fn from(bytes: Vec<u8>) -> Self {
332 Self::from_slice(&bytes)
333 }
334}
335
336impl AsRef<[u8]> for Buffer {
337 #[inline]
338 fn as_ref(&self) -> &[u8] {
339 self.as_slice()
340 }
341}
342
343impl std::ops::Deref for Buffer {
344 type Target = [u8];
345
346 #[inline]
347 fn deref(&self) -> &[u8] {
348 self.as_slice()
349 }
350}
351
352impl PartialEq for Buffer {
353 #[inline]
356 fn eq(&self, other: &Self) -> bool {
357 self.as_slice() == other.as_slice()
358 }
359}
360
361impl Eq for Buffer {}
362
363impl std::hash::Hash for Buffer {
364 fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
365 self.as_slice().hash(state);
366 }
367}
368
369impl fmt::Debug for Buffer {
370 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
371 const PREVIEW: usize = 16;
372 let bytes = self.as_slice();
373 f.debug_struct("Buffer")
374 .field("len", &self.len)
375 .field("offset", &self.offset)
376 .field("shared", &self.share_count())
377 .field("head", &&bytes[..bytes.len().min(PREVIEW)])
378 .finish_non_exhaustive()
379 }
380}
381
382impl FromIterator<u8> for Buffer {
383 fn from_iter<I: IntoIterator<Item = u8>>(iter: I) -> Self {
384 Self::from(AlignedBuf::from_iter(iter))
385 }
386}
387
388#[cfg(test)]
389mod tests {
390 #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
391
392 use super::*;
393
394 const fn assert_send_sync<T: Send + Sync>() {}
395
396 #[test]
397 fn buffer_is_send_and_sync() {
398 assert_send_sync::<Buffer>();
399 }
400
401 #[test]
402 fn empty_buffer() {
403 let buffer = Buffer::new();
404 assert!(buffer.is_empty());
405 assert_eq!(buffer.len(), 0);
406 assert_eq!(buffer.as_slice(), &[] as &[u8]);
407 assert_eq!(buffer, Buffer::default());
408 }
409
410 #[test]
411 fn slicing_is_zero_copy() {
412 let buffer = Buffer::from_slice(&[0, 1, 2, 3, 4, 5, 6, 7]);
413 let base = buffer.as_ptr();
414 let mid = buffer.slice(2, 4);
415 assert_eq!(mid.as_slice(), &[2, 3, 4, 5]);
416 assert_eq!(mid.as_ptr(), base.wrapping_add(2));
417 assert_eq!(mid.offset(), 2);
418 assert_eq!(mid.backing_len(), 8);
419 assert_eq!(buffer.share_count(), 2);
420 }
421
422 #[test]
423 fn nested_slices_compose() {
424 let buffer = Buffer::from_slice(&(0u8..20).collect::<Vec<_>>());
425 let a = buffer.slice(5, 10);
426 let b = a.slice(2, 3);
427 assert_eq!(b.as_slice(), &[7, 8, 9]);
428 assert_eq!(b.offset(), 7);
429 }
430
431 #[test]
432 fn slices_clamp_instead_of_panicking() {
433 let buffer = Buffer::from_slice(&[1, 2, 3]);
434 assert_eq!(buffer.slice(0, 99).as_slice(), &[1, 2, 3]);
435 assert_eq!(buffer.slice(2, 99).as_slice(), &[3]);
436 assert!(buffer.slice(99, 1).is_empty());
437 assert!(buffer.slice(usize::MAX, usize::MAX).is_empty());
438 }
439
440 #[test]
441 fn try_slice_reports_out_of_range() {
442 let buffer = Buffer::from_slice(&[1, 2, 3]);
443 assert_eq!(buffer.try_slice(0, 3).unwrap().as_slice(), &[1, 2, 3]);
444 assert_eq!(buffer.try_slice(3, 0).unwrap().len(), 0);
445 assert_eq!(
446 buffer.try_slice(1, 3).unwrap_err(),
447 DataError::SliceOutOfBounds {
448 offset: 1,
449 len: 3,
450 available: 3
451 }
452 );
453 assert!(buffer.try_slice(usize::MAX, usize::MAX).is_err());
454 }
455
456 #[test]
457 fn alignment_reporting() {
458 let buffer = Buffer::from_slice(&[0; 256]);
459 assert!(buffer.is_aligned_to(ALIGNMENT));
460 assert!(buffer.address_alignment() >= ALIGNMENT);
461 let odd = buffer.slice(1, 8);
462 assert!(!odd.is_aligned_to(ALIGNMENT));
463 assert_eq!(odd.address_alignment(), 1);
464 assert!(buffer.slice(64, 8).is_aligned_to(ALIGNMENT));
465 assert!(buffer.is_aligned_to(0));
466 }
467
468 #[test]
469 fn realigned_copies_only_when_needed() {
470 let buffer = Buffer::from_slice(&[7u8; 128]);
471 let same = buffer.realigned();
472 assert_eq!(same.as_ptr(), buffer.as_ptr(), "already aligned: no copy");
473
474 let odd = buffer.slice(3, 10);
475 let fixed = odd.realigned();
476 assert!(fixed.is_aligned_to(ALIGNMENT));
477 assert_ne!(fixed.as_ptr(), odd.as_ptr());
478 assert_eq!(fixed.as_slice(), odd.as_slice());
479 }
480
481 #[test]
482 fn into_aligned_recovers_sole_ownership() {
483 let buffer = Buffer::from_slice(b"recover");
484 let owned = buffer.into_aligned().expect("sole owner");
485 assert_eq!(owned.as_slice(), b"recover");
486
487 let shared = Buffer::from_slice(b"shared");
488 let keep = shared.clone();
489 let err = shared.into_aligned().expect_err("two handles");
490 assert_eq!(err.as_slice(), b"shared");
491 drop(keep);
492
493 let windowed = Buffer::from_slice(b"window").slice(1, 3);
494 assert!(windowed.into_aligned().is_err(), "partial window");
495 }
496
497 #[test]
498 fn equality_is_by_content() {
499 let a = Buffer::from_slice(&[1, 2, 3]);
500 let b = Buffer::from_slice(&[0, 1, 2, 3]).slice(1, 3);
501 assert_eq!(a, b);
502 assert_ne!(a, Buffer::from_slice(&[1, 2]));
503 }
504
505 #[test]
506 fn conversions_and_collect() {
507 assert_eq!(Buffer::from(vec![1u8, 2]).as_slice(), &[1, 2]);
508 assert_eq!(Buffer::from(&b"hi"[..]).as_slice(), b"hi");
509 let collected: Buffer = (0u8..4).collect();
510 assert_eq!(collected.as_slice(), &[0, 1, 2, 3]);
511 assert_eq!(Buffer::zeroed(3).as_slice(), &[0, 0, 0]);
512 assert_eq!(&*Buffer::from_slice(b"deref"), b"deref");
513 }
514
515 #[test]
516 fn from_scalars_packs_native_bytes() {
517 let buffer = Buffer::from_scalars(&[1u16, 0x0201]);
518 assert_eq!(buffer.len(), 4);
519 let typed = buffer.typed::<u16>().unwrap();
520 assert_eq!(typed.as_slice(), &[1, 0x0201]);
521 }
522
523 #[test]
524 fn debug_shows_sharing() {
525 let buffer = Buffer::from_slice(&[1, 2, 3]);
526 let rendered = format!("{buffer:?}");
527 assert!(rendered.contains("len: 3"), "{rendered}");
528 assert!(rendered.contains("shared: 1"), "{rendered}");
529 }
530
531 #[test]
532 fn from_arc_shares_without_copying() {
533 let arc = Arc::new(AlignedBuf::from_slice(b"arc"));
534 let a = Buffer::from_arc(Arc::clone(&arc));
535 let b = Buffer::from_arc(arc);
536 assert_eq!(a.as_ptr(), b.as_ptr());
537 assert_eq!(a.as_slice(), b"arc");
538 }
539}