Struct Buf 

pub struct Buf<T: Element + ?Sized, const DIM: usize> { /* private fields */ }

A shared, typed, N-dimensional array of values, in column-major order, a scalar for DIM == 0. Its dimensions are fixed once it is built. Octets are a Buf<u8, 1>, cast to other packed types with Self::cast, and turned into strings with Buf::from_spans.

Cloning a buffer only counts one more reference to its storage, and so does slicing it, which is what allows the buffer of a received message to be handed out in pieces without copying any of it. A packed scalar is held in place and has no storage.

Implementations

impl<T: Element + ?Sized, const DIM: usize> Buf<T, DIM>

pub const fn new() -> Self

A buffer of no values, all its dimensions being zero, which allocates nothing: every empty buffer shares the same static storage.

pub fn dim(&self) -> [usize; DIM]

The dimensions of this buffer, the first one varying the fastest.

pub fn len(&self) -> usize

The number of values of this buffer, 1 for a scalar.

pub fn is_empty(&self) -> bool

pub fn raw_index(&self, pos: [usize; DIM]) -> Option<usize>

The index among the values of this buffer of the value at that position, one coordinate per dimension, in column-major order: the first coordinate is the one varying the fastest. Absent if a coordinate is out of its dimension.

pub fn get(&self, pos: [usize; DIM]) -> Option<T::Ref<'_>>

The value at that position, one coordinate per dimension, [x] for one and [x, y] for two, [] giving the value of a scalar. Absent if a coordinate is out of its dimension.

pub fn get_scalar(&self, pos: [usize; DIM]) -> Option<Buf<T, 0>>

The value at that position as a scalar of its own, see Self::get: copied in place for a packed type, sharing the storage for a string. Absent if a coordinate is out of its dimension.

pub fn get_raw(&self, index: usize) -> Option<T::Ref<'_>>

The value at that index among the values of this buffer, in column-major order, see Self::raw_index. Absent if the index is out of the length.

pub fn iter(&self) -> impl ExactSizeIterator<Item = T::Ref<'_>> + '_

The values of this buffer, in column-major order.

pub fn slice<R: RangeBounds<usize>>(&self, range: R) -> Self

The part of this buffer within that range of its last dimension, which is the slowest varying one, so that the part shares the same storage: a range of values for one dimension, a range of rows for two.

Panics

If the range is out of the last dimension, like slice indexing.

pub fn split_to(&mut self, at: usize) -> Self

Take the part of this buffer before at along its last dimension out as a buffer of its own, this one keeping the part from at on, both sharing the storage: how a message is framed out of the octets that arrived, the ones behind it being the front of the next ones.

Panics

If at is past the last dimension.

pub fn split_off(&mut self, at: usize) -> Self

Take the part of this buffer from at on along its last dimension out as a buffer of its own, this one keeping the part before at, both sharing the storage.

Panics

If at is past the last dimension.

pub fn reshape<const D: usize>(self, dim: [usize; D]) -> Option<Buf<T, D>>

The same values with other dimensions, as long as they are as many: typically values decoded in one dimension and given the two dimensions they actually have. A scalar is one value, so it is reshaped to and from any dimensions of one value, being copied in or out of place for a packed type, see Buf.

pub fn into_scalar(self) -> Option<Buf<T, 0>>

The single value of this buffer as a scalar, absent if it does not hold exactly one: typically a scalar decoded as one dimension of one, see Self::reshape.

pub fn is_unique(&self) -> bool

Whether this buffer is the only reference to its storage, which a buffer held in place always is.

impl<T: Element + ?Sized> Buf<T, 1>

pub fn truncate(&mut self, len: usize)

Keep only the first values, no more than that many.

impl<T: Element + ?Sized> Buf<T, 0>

pub fn value(&self) -> T::Ref<'_>

The value of this scalar.

impl<T: PackedElement, const DIM: usize> Buf<T, DIM>

pub fn from_slice(values: &[T], dim: [usize; DIM]) -> Option<Self>

A buffer of these values, with those dimensions, copied into a new storage unless it is a scalar, which is held in place. Absent if the values are not as many as the dimensions say.

pub fn zeroed(dim: [usize; DIM]) -> Self

A buffer of zeroes with those dimensions, see BufMut::zeroed.

pub fn as_ptr(&self) -> *const T

Where the values of this buffer start.

pub fn as_slice(&self) -> &[T]

The values of this buffer, in column-major order.

pub fn as_bytes(&self) -> &[u8]

The octets of the values of this buffer, what a backend encodes them from.

pub fn cast<U: PackedElement, const D: usize>( self, dim: [usize; D], ) -> Result<Buf<U, D>, Self>

The octets of this buffer as packed values of another type, with those dimensions, sharing its storage if they are aligned for that type, and copied otherwise, or held in place for a scalar. The buffer is given back if it does not hold as many octets as the dimensions say, or holds an invalid value.

This is how a backend decodes an array out of the message it received, in native byte order, typically out of a slice of it.

pub fn into_bytes(self) -> Buf<u8, 1>

The octets of the values of this buffer, a new buffer for a scalar held in place.

pub fn get_mut(&mut self) -> Option<&mut BufMut<T, DIM>>

This buffer as a writable one, for as long as it is borrowed, absent if its storage is shared, like Arc::get_mut.

pub fn make_mut(&mut self) -> &mut BufMut<T, DIM>

This buffer as a writable one, for as long as it is borrowed, which first copies its values into a storage of their own if its storage is shared: only these values are copied, not the whole storage.

pub fn try_into_mut(self) -> Result<BufMut<T, DIM>, Self>

This buffer as one that is statically the only reference to its storage, given back if its storage is shared, which the empty storage never is.

pub fn into_mut(self) -> BufMut<T, DIM>

This buffer as one that is statically the only reference to its storage, which copies its values into a storage of their own if its storage is shared, see Self::make_mut.

pub fn slice_ref(&self, subset: &[T]) -> Self

The part of this buffer that these values are, sharing its storage, see Self::slice: what values taken out of Self::as_slice turn back into, such as the octets a decoder that only handles slices has read.

Panics

If the values are not within this buffer, or are not a range of its last dimension: any range of values for one dimension, but only whole rows for two.

impl<const DIM: usize> Buf<str, DIM>

pub fn from_spans<I>( bytes: Buf<u8, 1>, spans: I, dim: [usize; DIM], ) -> Result<Self, Buf<u8, 1>>

where I: IntoIterator<Item = Range<u32>>,

The strings at these spans of these octets, relative to them, with those dimensions, sharing their storage. The octets are given back if the spans are not as many as the dimensions say, are out of the octets, or are not valid UTF-8.

This is how a backend decodes strings out of the message it received, the spans being typically given as it reads them.

pub unsafe fn from_spans_unchecked<I>( bytes: Buf<u8, 1>, spans: I, dim: [usize; DIM], ) -> Self

where I: IntoIterator<Item = Range<u32>>,

The unchecked form of Self::from_spans, for a backend that already validated the strings: only their number is checked.

Safety

The spans must be within the octets, and valid UTF-8 there.

Panics

If the spans are not as many as the dimensions say, or if their table cannot be allocated.

impl Buf<str, 1>

pub fn from_strs<I>(values: I) -> Option<Self>

where I: IntoIterator, I::Item: AsRef<str>,

A buffer of copies of these strings, as many as there are. Absent if several of them do not fit spans of 32 bits.

A single string is copied into a storage of its own, its span taking no table, so it allocates nothing more, and nothing at all when it is empty.

Trait Implementations

impl<T: TangoElement + ?Sized, const N: usize> AttrData for Buf<T, N>

const DATA_KIND: AttrDataKind = T::ATTR_KIND

const DATA_FORMAT: AttrDataFormat

impl<T: Element + ?Sized, const DIM: usize> Clone for Buf<T, DIM>

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: TangoElement + ?Sized, const N: usize> CommandData for Buf<T, N>

const DATA_KIND: CommandDataKind

impl<T: Element + ?Sized, const DIM: usize> Debug for Buf<T, DIM>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Its dimensions and values, row by row, see Element::fmt_row.

impl<T: Element + ?Sized, const DIM: usize> Default for Buf<T, DIM>

fn default() -> Self

An empty buffer, see Self::new.

impl<T: Element + ?Sized, const DIM: usize> Drop for Buf<T, DIM>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<T: Element + ?Sized, const DIM: usize> Eq for Buf<T, DIM>

where for<'a> T::Ref<'a>: Eq,

impl<S: AsRef<str>> From<&[S]> for Buf<str, 1>

fn from(values: &[S]) -> Self

Converts to this type from the input type.

impl<T: PackedElement> From<&[T]> for Buf<T, 1>

fn from(values: &[T]) -> Self

Converts to this type from the input type.

impl From<&str> for Buf<str, 0>

fn from(value: &str) -> Self

A scalar of a copy of that string, which is its only allocation, none if it is empty.

impl<T: PackedElement> From<Box<[T]>> for Buf<T, 1>

fn from(values: Box<[T]>) -> Self

Converts to this type from the input type.

impl<T: TangoElement + ?Sized> From<Buf<T, 0>> for Value

fn from(data: Scalar<T>) -> Self

Converts to this type from the input type.

impl<T: TangoElement + ?Sized> From<Buf<T, 1>> for Value

fn from(data: Spectrum<T>) -> Self

Converts to this type from the input type.

impl<T: TangoElement + ?Sized> From<Buf<T, 2>> for Value

fn from(data: Image<T>) -> Self

Converts to this type from the input type.

impl<T: PackedElement, const DIM: usize> From<BufMut<T, DIM>> for Buf<T, DIM>

fn from(buf: BufMut<T, DIM>) -> Self

Converts to this type from the input type.

impl From<Cow<'_, str>> for Buf<str, 0>

fn from(value: Cow<'_, str>) -> Self

A scalar of a copy of that string.

impl From<String> for Buf<str, 0>

fn from(value: String) -> Self

A scalar of a copy of that string.

impl<T: PackedElement> From<T> for Buf<T, 0>

fn from(value: T) -> Self

A scalar of that value, held in place.

impl<T: PackedElement> From<Vec<T>> for Buf<T, 1>

fn from(values: Vec<T>) -> Self

Converts to this type from the input type.

impl<T: PackedElement, const N: usize> From<[T; N]> for Buf<T, 1>

fn from(values: [T; N]) -> Self

Converts to this type from the input type.

impl<T: PackedElement> LowerHex for Buf<T, 1>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

The octets of the values as hexadecimal, in the order they are stored, each value’s grouped and separated by a space, octets being a single run that BufMut::from_hex parses back.

impl<T: Element + ?Sized, const DIM: usize> PartialEq for Buf<T, DIM>

where for<'a> T::Ref<'a>: PartialEq,

fn eq(&self, other: &Self) -> bool

Two buffers are equal if they have the same dimensions and values, wherever these are.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl<T: Element + ?Sized, const DIM: usize> Send for Buf<T, DIM>

impl<T: Element + ?Sized, const DIM: usize> Sync for Buf<T, DIM>

impl<T: PackedElement> UpperHex for Buf<T, 1>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

The octets of the values as hexadecimal, in the order they are stored, each value’s grouped and separated by a space, octets being a single run that BufMut::from_hex parses back.