Struct DataArray 

pub struct DataArray {
    pub data: Bytes,
    pub dtype: BinaryDataArrayType,
    pub compression: BinaryCompressionType,
    pub name: ArrayType,
    pub params: Option<Box<ParamList>>,
    pub unit: Unit,
    /* private fields */
}

Represents a data array that holds a byte buffer that may be compressed, base64 encoded, or raw little endian bytes, and provides views of those bytes as a small range of supported types.

This type is modeled after the <binaryDataArray> element in mzML.

Note

This type tries to walk a fine line between convenience and performance and as such is easy to misuse. All operations that view the byte buffer as arbitrary data need that data to be decoded and decompressed in order to borrow it. If the byte buffer is not already stored decoded, the operation will copy and decode the buffer in its entirety before performing any other operation, so repeated method calls may incur excessive overhead. If this is happening, please use DataArray::decode_and_store to store the decoded representation explicitly.

Normally, SpectrumSource-implementing file readers will eagerly decode all arrays as soon as they are ready. If they are operating in lazy mode, the buffers will need to be decoded explicitly, again using DataArray::decode_and_store or operations should make as much use of the copied arrays as possible instead.

Fields

data: Bytes

The raw data of the array, stored in a variety of states controlled by [Self::Compression], as native bytes

dtype: BinaryDataArrayType

The kind of data stored in the array, as in bit-width primitive types

compression: BinaryCompressionType

How Self::data is encoded and compressed.

name: ArrayType

The what the data stored in the array was measuring, e.g. an m/z array

params: Option<Box<ParamList>>

Additional metadata parameters

unit: Unit

The Unit for the data measurements

Implementations

impl<'transient, 'lifespan: 'transient> DataArray

pub fn new() -> DataArray

pub fn from_name(name: &ArrayType) -> DataArray

pub fn from_name_and_type( name: &ArrayType, dtype: BinaryDataArrayType, ) -> DataArray

pub fn from_name_type_size( name: &ArrayType, dtype: BinaryDataArrayType, size: usize, ) -> DataArray

pub fn slice( &self, start: usize, end: usize, ) -> Result<DataArray, ArrayRetrievalError>

pub fn slice_buffer( &self, start: usize, end: usize, ) -> Result<Cow<'_, [u8]>, ArrayRetrievalError>

pub fn wrap( name: &ArrayType, dtype: BinaryDataArrayType, data: Bytes, ) -> DataArray

This method assumes the data are already in native byte order

pub fn update_buffer<T: Pod + ToBytes>( &mut self, data_buffer: &[T], ) -> Result<usize, ArrayRetrievalError>

Directly set the data buffer from a slice of a Pod type, copying it.

This will return an error if std::mem::size_of::<T>() is not equal to the size of DataArray::dtype.

pub fn push<T: Pod>(&mut self, value: T) -> Result<(), ArrayRetrievalError>

Add the value of a Pod implementing type T to the array, converting it to native byte representation.

This will return an error if std::mem::size_of::<T>() is not equal to the size of DataArray::dtype.

pub fn extend<T: Pod>( &mut self, values: &[T], ) -> Result<(), ArrayRetrievalError>

Add the values from a slice of a Pod implementing type T to the array, converting the slice a slice of T in its native byte representation.

This will return an error if std::mem::size_of::<T>() is not equal to the size of DataArray::dtype.

pub fn extend_raw(&mut self, values: &[u8]) -> Result<(), ArrayRetrievalError>

Add the values from a buffer of bytes to the array directly.

This will return an error if values.len() is not a multiple of the size of DataArray::dtype.

pub fn extend_iter<T: Pod>( &mut self, iter: impl IntoIterator<Item = T>, ) -> Result<(), ArrayRetrievalError>

Add the values from an iterator over Pod type T.

This is more efficient than repeated calls to DataArray::push or collecting to a Vec and then using DataArray::extend, but equivalent to either.

This will return an error if std::mem::size_of::<T>() is not equal to the size of DataArray::dtype.

pub fn encode_bytestring(&self, compression: BinaryCompressionType) -> Bytes

Encode the data buffer to a byte array using the requested BinaryCompressionType to compress it and then base64 encode it.

pub fn decode_and_store( &mut self, ) -> Result<BinaryCompressionType, ArrayRetrievalError>

Decode the compressed data, if needed, and store that buffer in self.data. After decoding self.compression will always be BinaryCompressionType::Decoded.

The return value is the content of self.compression after decoding.

This may fail if the decoding fails for any reason.

pub fn decode( &'lifespan self, ) -> Result<Cow<'lifespan, [u8]>, ArrayRetrievalError>

Decompress and base64-decode encoded bytes, and return the data.

If the data were already decoded, the existing bytes are returned. Otherwise one or more buffers may be allocated to hold the decompressed and decoded bytes.

pub fn decode_mut( &'transient mut self, ) -> Result<&'transient mut Bytes, ArrayRetrievalError>

pub fn clear(&mut self)

pub fn store_compressed( &mut self, compression: BinaryCompressionType, ) -> Result<(), ArrayRetrievalError>

The reverse of DataArray::decode_and_store, this method compresses self.data to the desired compression method and stores that buffer as self.data.

pub fn store_as( &mut self, dtype: BinaryDataArrayType, ) -> Result<usize, ArrayRetrievalError>

Recode the stored data as the requested binary data type.

pub const fn is_ion_mobility(&self) -> bool

Test if the the array describes an ion mobility quantity.

See also

ArrayType::is_ion_mobility

pub fn raw_len(&self) -> usize

The size of the raw byte buffer

pub fn data_processing_reference(&self) -> Option<&str>

Get the identifier referencing a DataProcessing

pub fn set_data_processing_reference( &mut self, data_processing_reference: Option<Box<str>>, )

Set the identifier referencing a DataProcessing

impl DataArray

DataArray implements several compression codecs, some of which require additional dependencies.

pub fn compress_zlib(bytestring: &[u8]) -> Bytes

pub fn decompress_zlib(bytestring: &[u8]) -> Bytes

Trait Implementations

impl<'transient, 'lifespan: 'transient> ByteArrayView<'transient, 'lifespan> for DataArray

fn view(&'lifespan self) -> Result<Cow<'lifespan, [u8]>, ArrayRetrievalError>

fn dtype(&self) -> BinaryDataArrayType

The real data type encoded in bytes

fn data_len(&'lifespan self) -> Result<usize, ArrayRetrievalError>

The size of encoded array in terms of # of elements of the BinaryDataArrayType given by ByteArrayView::dtype

fn unit(&self) -> Unit

The unit of measurement each data point is in

fn data_processing_reference(&self) -> Option<&str>

Get the identifier referencing a DataProcessing

fn name(&self) -> &ArrayType

The kind of array this is

fn coerce_from<T: Pod>( buffer: Cow<'transient, [u8]>, ) -> Result<Cow<'transient, [T]>, ArrayRetrievalError>

fn coerce<T: Pod>( &'lifespan self, ) -> Result<Cow<'transient, [T]>, ArrayRetrievalError>

fn convert<S: Num + Clone + AsPrimitive<D> + Pod, D: Num + Clone + Copy + 'static>( &'lifespan self, ) -> Result<Cow<'transient, [D]>, ArrayRetrievalError>

Decode the array, then copy it to a new array, converting each element from type D to to type S

fn to_f32( &'lifespan self, ) -> Result<Cow<'transient, [f32]>, ArrayRetrievalError>

fn to_f64( &'lifespan self, ) -> Result<Cow<'transient, [f64]>, ArrayRetrievalError>

fn to_i32( &'lifespan self, ) -> Result<Cow<'transient, [i32]>, ArrayRetrievalError>

fn to_i64( &'lifespan self, ) -> Result<Cow<'transient, [i64]>, ArrayRetrievalError>

fn iter_type<T: Pod>( &'lifespan self, ) -> Result<DataSliceIter<'lifespan, T>, ArrayRetrievalError>

fn iter_u8( &'lifespan self, ) -> Result<DataSliceIter<'lifespan, u8>, ArrayRetrievalError>

fn iter_f32( &'lifespan self, ) -> Result<DataSliceIter<'lifespan, f32>, ArrayRetrievalError>

fn iter_f64( &'lifespan self, ) -> Result<DataSliceIter<'lifespan, f64>, ArrayRetrievalError>

fn iter_i32( &'lifespan self, ) -> Result<DataSliceIter<'lifespan, i32>, ArrayRetrievalError>

fn iter_i64( &'lifespan self, ) -> Result<DataSliceIter<'lifespan, i64>, ArrayRetrievalError>

impl<'transient, 'lifespan: 'transient> ByteArrayViewMut<'transient, 'lifespan> for DataArray

fn view_mut( &'transient mut self, ) -> Result<&'transient mut Bytes, ArrayRetrievalError>

Get a mutable view of the bytes backing this data array.

fn unit_mut(&mut self) -> &mut Unit

Specify the unit of the data array

fn set_data_processing_reference( &mut self, data_processing_reference: Option<Box<str>>, )

Set the identifier referencing a DataProcessing

fn coerce_from_mut<T: Clone + Sized>( buffer: &mut [u8], ) -> Result<&'transient mut [T], ArrayRetrievalError>

fn coerce_mut<T: Clone + Sized>( &'lifespan mut self, ) -> Result<&'transient mut [T], ArrayRetrievalError>

impl Clone for DataArray

fn clone(&self) -> DataArray

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for DataArray

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

Formats the value using the given formatter.

impl Default for DataArray

fn default() -> DataArray

Returns the “default value” for a type.

impl ParamDescribed for DataArray

fn params(&self) -> &[Param]

Obtain an immutable slice over the encapsulated Param list

fn params_mut(&mut self) -> &mut ParamList

Obtain an mutable slice over the encapsulated Param list

fn add_param(&mut self, param: Param)

Add a new Param to the entity

fn extend_params(&mut self, it: impl IntoIterator<Item = Param>)

Add all parameters from an iterator of Param to the entity

fn remove_param(&mut self, index: usize) -> Param

Remove the ith Param from the entity.

fn get_param_by_name(&self, name: &str) -> Option<&Param>

Find the first Param whose name matches name

fn get_param_by_curie(&self, curie: &CURIE) -> Option<&Param>

Find the first Param whose CURIE matches curie

fn get_param_by_accession(&self, accession: &str) -> Option<&Param>

Find the first Param whose Param::accession matches accession

fn iter_params(&self) -> Iter<'_, Param>

Iterate over the encapsulated parameter list

fn iter_params_mut(&mut self) -> IterMut<'_, Param>

Iterate mutably over the encapsulated parameter list