pub struct GenericStringArray<O: OffsetSizeTrait> { /* private fields */ }Expand description
A column of variable-length UTF-8 strings.
Use the StringArray and LargeStringArray aliases rather than naming
the offset parameter directly.
Implementations§
Source§impl<O: OffsetSizeTrait> GenericStringArray<O>
impl<O: OffsetSizeTrait> GenericStringArray<O>
Sourcepub fn try_new(
offsets: ScalarBuffer<O>,
values: Buffer,
validity: Option<Bitmap>,
) -> Result<Self>
pub fn try_new( offsets: ScalarBuffer<O>, values: Buffer, validity: Option<Bitmap>, ) -> Result<Self>
Builds an array from its three buffers, validating offsets and UTF-8.
This is the constructor for untrusted bytes.
§Errors
- The offset errors listed on
crate::array::validate_offsets. DataError::InvalidUtf8andDataError::OffsetNotCharBoundary.DataError::ValidityLengthMismatchwhen the bitmap length is wrong.
Sourcepub unsafe fn new_unchecked(
offsets: ScalarBuffer<O>,
values: Buffer,
validity: Option<Bitmap>,
) -> Self
pub unsafe fn new_unchecked( offsets: ScalarBuffer<O>, values: Buffer, validity: Option<Bitmap>, ) -> Self
Builds an array from its three buffers without validating.
§Safety
This constructor is unsafe by contract, not by memory model: the
accessors stay memory-safe whatever the bytes say, returning None for
a slot that is not valid UTF-8. Skipping validation turns a decode
error into a silent None, so only use it on the trusted zero-copy
path — bytes this crate produced, or bytes a caller has already
validated.
Callers must guarantee the offsets satisfy
crate::array::validate_offsets and that every slot they carve out is
valid UTF-8.
Sourcepub fn from_values<V: AsRef<str>>(values: impl IntoIterator<Item = V>) -> Self
pub fn from_values<V: AsRef<str>>(values: impl IntoIterator<Item = V>) -> Self
Builds an array with no nulls.
use astrs_data::array::{Array, StringArray};
let names = StringArray::from_values(["lidar", "camera"]);
assert_eq!(names.len(), 2);
assert_eq!(names.get(1), Some("camera"));Sourcepub fn from_opt_iter<V: AsRef<str>>(
values: impl IntoIterator<Item = Option<V>>,
) -> Self
pub fn from_opt_iter<V: AsRef<str>>( values: impl IntoIterator<Item = Option<V>>, ) -> Self
Builds an array from optional strings.
Sourcepub fn value_offsets(&self) -> &[O]
pub fn value_offsets(&self) -> &[O]
The offset buffer, len + 1 entries.
Sourcepub const fn offsets_buffer(&self) -> &ScalarBuffer<O>
pub const fn offsets_buffer(&self) -> &ScalarBuffer<O>
The offset buffer as a shareable typed window.
See GenericBinaryArray::offsets_buffer: the IPC encoder clones this
window instead of copying the offsets out of a slice.
use astrs_data::array::StringArray;
let array = StringArray::from_values(["ab", "c"]);
assert_eq!(array.offsets_buffer().as_slice(), &[0, 2, 3]);Sourcepub const fn value_data(&self) -> &Buffer
pub const fn value_data(&self) -> &Buffer
The flat value region every slot points into.
Sourcepub fn value_bytes(&self, index: usize) -> Option<&[u8]>
pub fn value_bytes(&self, index: usize) -> Option<&[u8]>
The raw slot bytes at index, ignoring validity and skipping the UTF-8
check.
The cheapest accessor: no validation at all.
Sourcepub fn value(&self, index: usize) -> Option<&str>
pub fn value(&self, index: usize) -> Option<&str>
The raw slot text at index, ignoring validity.
Returns None when index is out of range (or, on the
Self::new_unchecked path only, when the slot is not valid UTF-8).
Sourcepub fn get(&self, index: usize) -> Option<&str>
pub fn get(&self, index: usize) -> Option<&str>
The logical value at index: None when the slot is null or out of
range.
Sourcepub fn value_length(&self, index: usize) -> Option<usize>
pub fn value_length(&self, index: usize) -> Option<usize>
Byte length of slot index — not the character count.
Sourcepub fn total_value_bytes(&self) -> usize
pub fn total_value_bytes(&self) -> usize
Total bytes the values occupy, across the whole array.
Sourcepub fn slice(&self, offset: usize, len: usize) -> Self
pub fn slice(&self, offset: usize, len: usize) -> Self
A zero-copy sub-range, clamped to the array (the crate-wide slicing convention).
Slicing preserves the UTF-8 invariant: it narrows the offset buffer without changing any offset, and every retained offset was already checked to be a character boundary.
Sourcepub fn try_slice(&self, offset: usize, len: usize) -> Result<Self>
pub fn try_slice(&self, offset: usize, len: usize) -> Result<Self>
Checked GenericStringArray::slice.
§Errors
DataError::SliceOutOfBounds when the window leaves the array.
Sourcepub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self>
pub fn with_validity(&self, validity: Option<Bitmap>) -> Result<Self>
Returns a copy with a different validity bitmap.
§Errors
DataError::ValidityLengthMismatch when the bitmap length is wrong.
Sourcepub fn into_binary(self) -> GenericBinaryArray<O>
pub fn into_binary(self) -> GenericBinaryArray<O>
Reinterprets the column as bytes, dropping the UTF-8 guarantee.
Free: the two types share a representation.
Sourcepub const fn as_binary(&self) -> &GenericBinaryArray<O>
pub const fn as_binary(&self) -> &GenericBinaryArray<O>
The byte view of this column.
Trait Implementations§
Source§impl<O: OffsetSizeTrait> Array for GenericStringArray<O>
impl<O: OffsetSizeTrait> Array for GenericStringArray<O>
Source§fn as_any(&self) -> &dyn Any
fn as_any(&self) -> &dyn Any
ArrayExt::downcast.Source§fn validity(&self) -> Option<&Bitmap>
fn validity(&self) -> Option<&Bitmap>
None when every slot is valid. Read moreSource§fn buffer_memory_size(&self) -> usize
fn buffer_memory_size(&self) -> usize
Source§fn null_count(&self) -> usize
fn null_count(&self) -> usize
Source§impl<'a, O: OffsetSizeTrait> ArrayAccessor for &'a GenericStringArray<O>
impl<'a, O: OffsetSizeTrait> ArrayAccessor for &'a GenericStringArray<O>
Source§impl<O: Clone + OffsetSizeTrait> Clone for GenericStringArray<O>
impl<O: Clone + OffsetSizeTrait> Clone for GenericStringArray<O>
Source§impl<O: OffsetSizeTrait> Debug for GenericStringArray<O>
impl<O: OffsetSizeTrait> Debug for GenericStringArray<O>
impl<O: OffsetSizeTrait> Eq for GenericStringArray<O>
Source§impl<O: OffsetSizeTrait, V: AsRef<str>> FromIterator<Option<V>> for GenericStringArray<O>
impl<O: OffsetSizeTrait, V: AsRef<str>> FromIterator<Option<V>> for GenericStringArray<O>
Source§impl<'a, O: OffsetSizeTrait> IntoIterator for &'a GenericStringArray<O>
impl<'a, O: OffsetSizeTrait> IntoIterator for &'a GenericStringArray<O>
Source§impl<O: OffsetSizeTrait> PartialEq for GenericStringArray<O>
impl<O: OffsetSizeTrait> PartialEq for GenericStringArray<O>
Source§impl<O: OffsetSizeTrait> TryFrom<GenericBinaryArray<O>> for GenericStringArray<O>
impl<O: OffsetSizeTrait> TryFrom<GenericBinaryArray<O>> for GenericStringArray<O>
Auto Trait Implementations§
impl<O> !Freeze for GenericStringArray<O>
impl<O> RefUnwindSafe for GenericStringArray<O>where
GenericBinaryArray<O>: RefUnwindSafe,
impl<O> Send for GenericStringArray<O>where
GenericBinaryArray<O>: Send,
impl<O> Sync for GenericStringArray<O>where
GenericBinaryArray<O>: Sync,
impl<O> Unpin for GenericStringArray<O>where
GenericBinaryArray<O>: Unpin,
impl<O> UnsafeUnpin for GenericStringArray<O>where
GenericBinaryArray<O>: UnsafeUnpin,
impl<O> UnwindSafe for GenericStringArray<O>where
GenericBinaryArray<O>: UnwindSafe,
Blanket Implementations§
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<A> IntoArrayRef for Awhere
A: Array,
impl<A> IntoArrayRef for Awhere
A: Array,
Source§fn into_array_ref(self) -> ArrayRef
fn into_array_ref(self) -> ArrayRef
self into a shared, dynamically typed column.