Struct zarrs::array::Array

pub struct Array<TStorage: ?Sized> { /* private fields */ }

A Zarr array.

See https://zarr-specs.readthedocs.io/en/latest/v3/core/v3.0.html#array-metadata.

The shape and attributes of an array are mutable and can be updated after construction. Array metadata must be written explicitly to the store with store_metadata, which can be done before or after chunks are written.

Concurrency

A Single Array Instance (Internal Synchronisation)

Arrays support parallel reading and writing, with the level of concurrency dependent on the underlying store. A store must guarantee the following for operations which retrieve or store data from a chunk (or any store value):

• a store may support multiple concurrent readers of a chunk, and
• a store must permit only one writer of a chunk at any one time (with no concurrent readers).

A chunk is locked for writing within the Array::store_chunk_subset function (which may be called from any of the store_array_subset and store_chunk_subset variants). This is necessary because this function may internally decode a chunk and later update it. The chunk must not be updated by another thread until this operation has completed.

For optimum write performance, an array should be written chunk-by-chunk. If a chunk is written more than once, its element values depend on whichever operation wrote to the chunk last.

Array elements can alternatively be written using the store_array_subset/store_chunk_subset methods, although this is less efficient. Provided that the array subsets are non-overlapping, all elements are guaranteed to hold the values written. If any array subsets overlap (which ideally should be avoided!), the value of an element in the overlap region depends on whichever operation wrote to its associated chunk last. Consider the case of parallel writing of the following subsets to a 1x6 array and a 1x3 chunk size (do not do this, it is just an example):

   |subset0| < stores element values of 0
[ A B C | D E F ] < fill value of 9
     |subset1| < stores element values of 1
     |ss2| < stores element values of 2

Depending on the order in which the chunks were updated within each subset, the array elements could take on the following values:

[ A B C | D E F ]
  9 0 0   0 1 9
      1   1
      2

Multiple Array Instances (External Synchronisation)

The internal synchronisation guarantees provided by an Array and its underlying store are not applicable if there are multiple array instances referencing the same data. An Array should only be created once and shared between multiple threads where possible.

This is not applicable if an array is being written from multiple independent processes (e.g. a distributed program on a cluster). For example, without internal synchronisation it is possible that elements B and E in the above example could end up with the fill value, despite them explicitly being set to 0 and 1 respectively.

A distributed program with multiple Array instances should do chunk-by-chunk writing. If a chunk needs to be updated, then external synchronisation is necessary to ensure that only one process updates it at any one time.

Implementations

impl<TStorage: ?Sized + AsyncReadableStorageTraits> Array<TStorage>

pub async fn async_new( storage: Arc<TStorage>, path: &str ) -> Result<Self, ArrayCreateError>

Available on crate feature async only.

Create an array in storage at path. The metadata is read from the store.

Errors

Returns ArrayCreateError if there is a storage error or any metadata is invalid.

pub async fn async_retrieve_chunk( &self, chunk_indices: &[u64] ) -> Result<Box<[u8]>, ArrayError>

Available on crate feature async only.

Read and decode the chunk at chunk_indices into its bytes.

Errors

Returns an ArrayError if

• chunk_indices are invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Panics if the number of elements in the chunk exceeds usize::MAX.

pub async fn async_retrieve_chunk_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64] ) -> Result<Box<[T]>, ArrayError>

Available on crate feature async only.

Read and decode the chunk at chunk_indices into a vector of its elements.

Errors

Returns an ArrayError if

• the size of T does not match the data type size,
• the decoded bytes cannot be transmuted,
• chunk_indices are invalid,
• there is a codec decoding error, or
• an underlying store error.

pub async fn async_retrieve_chunk_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64] ) -> Result<ArrayD<T>, ArrayError>

Available on crate features async and ndarray only.

Read and decode the chunk at chunk_indices into an ndarray.

Errors

Returns an ArrayError if:

• the size of T does not match the data type size,
• the decoded bytes cannot be transmuted,
• the chunk indices are invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if a chunk dimension is larger than usize::MAX.

pub async fn async_retrieve_array_subset( &self, array_subset: &ArraySubset ) -> Result<Box<[u8]>, ArrayError>

Available on crate feature async only.

Read and decode the array_subset of array into its bytes.

Out-of-bounds elements will have the fill value. If parallel is true, chunks intersecting the array subset are retrieved in parallel.

Errors

Returns an ArrayError if:

• the array_subset dimensionality does not match the chunk grid dimensionality,
• there is a codec decoding error, or
• an underlying store error.

Panics

Panics if attempting to reference a byte beyond usize::MAX.

pub async fn async_par_retrieve_array_subset( &self, array_subset: &ArraySubset ) -> Result<Box<[u8]>, ArrayError>

Available on crate feature async only.

Parallel version of Array::retrieve_array_subset.

pub async fn async_retrieve_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<Box<[T]>, ArrayError>

Available on crate feature async only.

Read and decode the array_subset of array into a vector of its elements.

Errors

Returns an ArrayError if:

• the size of T does not match the data type size,
• the decoded bytes cannot be transmuted,
• an array subset is invalid or out of bounds of the array,
• there is a codec decoding error, or
• an underlying store error.

pub async fn async_par_retrieve_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<Box<[T]>, ArrayError>

Available on crate feature async only.

Parallel version of Array::retrieve_array_subset_elements.

pub async fn async_retrieve_array_subset_ndarray<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<ArrayD<T>, ArrayError>

Available on crate features async and ndarray only.

Read and decode the array_subset of array into an ndarray.

Errors

Returns an ArrayError if:

• an array subset is invalid or out of bounds of the array,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if any dimension in chunk_subset is usize::MAX or larger.

pub async fn async_par_retrieve_array_subset_ndarray<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<ArrayD<T>, ArrayError>

Available on crate features async and ndarray only.

Parallel version of Array::retrieve_array_subset_ndarray.

pub async fn async_retrieve_chunk_subset( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset ) -> Result<Box<[u8]>, ArrayError>

Available on crate feature async only.

Read and decode the chunk_subset of the chunk at chunk_indices into its bytes.

Errors

Returns an ArrayError if:

• the chunk indices are invalid,
• the chunk subset is invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if the number of elements in chunk_subset is usize::MAX or larger.

pub async fn async_retrieve_chunk_subset_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset ) -> Result<Box<[T]>, ArrayError>

Available on crate feature async only.

Read and decode the chunk_subset of the chunk at chunk_indices into its elements.

Errors

Returns an ArrayError if:

• the chunk indices are invalid,
• the chunk subset is invalid,
• there is a codec decoding error, or
• an underlying store error.

pub async fn async_retrieve_chunk_subset_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset ) -> Result<ArrayD<T>, ArrayError>

Available on crate features async and ndarray only.

Read and decode the chunk_subset of the chunk at chunk_indices into an ndarray.

Errors

Returns an ArrayError if:

• the chunk indices are invalid,
• the chunk subset is invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if the number of elements in chunk_subset is usize::MAX or larger.

pub async fn async_partial_decoder_opt<'a>( &'a self, chunk_indices: &[u64], parallel: bool ) -> Result<Box<dyn AsyncArrayPartialDecoderTraits + 'a>, ArrayError>

Available on crate feature async only.

Initialises a partial decoder for the chunk at chunk_indices with optional parallelism.

Errors

Returns an ArrayError if initialisation of the partial decoder fails.

pub async fn async_partial_decoder<'a>( &'a self, chunk_indices: &[u64] ) -> Result<Box<dyn AsyncArrayPartialDecoderTraits + 'a>, ArrayError>

Available on crate feature async only.

Initialises a partial decoder for the chunk at chunk_indices.

Errors

Returns an ArrayError if initialisation of the partial decoder fails.

pub async fn async_par_partial_decoder<'a>( &'a self, chunk_indices: &[u64] ) -> Result<Box<dyn AsyncArrayPartialDecoderTraits + 'a>, ArrayError>

Available on crate feature async only.

Initialises a partial decoder for the chunk at chunk_indices using multithreading if applicable.

Errors

Returns an ArrayError if initialisation of the partial decoder fails.

impl<TStorage: ?Sized + AsyncWritableStorageTraits> Array<TStorage>

pub async fn async_store_metadata(&self) -> Result<(), StorageError>

Available on crate feature async only.

Store metadata.

Errors

Returns StorageError if there is an underlying store error.

pub async fn async_store_chunk( &self, chunk_indices: &[u64], chunk_bytes: Vec<u8> ) -> Result<(), ArrayError>

Available on crate feature async only.

Encode chunk_bytes and store at chunk_indices.

A chunk composed entirely of the fill value will not be written to the store.

Errors

Returns an ArrayError if

• chunk_indices are invalid,
• the length of chunk_bytes is not equal to the expected length (the product of the number of elements in the chunk and the data type size in bytes),
• there is a codec encoding error, or
• an underlying store error.

pub async fn async_store_chunk_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_elements: Vec<T> ) -> Result<(), ArrayError>

Available on crate feature async only.

Encode chunk_elements and store at chunk_indices.

A chunk composed entirely of the fill value will not be written to the store.

Errors

Returns an ArrayError if

• the size of T does not match the data type size, or
• a store_chunk error condition is met.

pub async fn async_store_chunk_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate features async and ndarray only.

Encode chunk_array and store at chunk_indices.

Errors

Returns an ArrayError if

• the size of T does not match the size of the data type,
• a store_chunk_elements error condition is met.

pub async fn async_erase_chunk( &self, chunk_indices: &[u64] ) -> Result<bool, StorageError>

Available on crate feature async only.

Erase the chunk at chunk_indices.

Returns true if the chunk was erased, or false if it did not exist.

Errors

Returns a StorageError if there is an underlying store error.

impl<TStorage: ?Sized + AsyncReadableStorageTraits + AsyncWritableStorageTraits> Array<TStorage>

pub async fn async_store_array_subset( &self, array_subset: &ArraySubset, subset_bytes: Vec<u8> ) -> Result<(), ArrayError>

Available on crate feature async only.

Encode subset_bytes and store in array_subset.

If parallel is true, chunks intersecting the array subset are retrieved in parallel. Prefer to use store_chunk since this will decode and encode each chunk intersecting array_subset.

Errors

Returns an ArrayError if

• the dimensionality of array_subset does not match the chunk grid dimensionality
• the length of subset_bytes does not match the expected length governed by the shape of the array subset and the data type size,
• there is a codec encoding error, or
• an underlying store error.

pub async fn async_par_store_array_subset( &self, array_subset: &ArraySubset, subset_bytes: Vec<u8> ) -> Result<(), ArrayError>

Available on crate feature async only.

Parallel version of Array::store_array_subset.

pub async fn async_store_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset, subset_elements: Vec<T> ) -> Result<(), ArrayError>

Available on crate feature async only.

Encode subset_elements and store in array_subset.

Prefer to use store_chunk since this will decode and encode each chunk intersecting array_subset.

Errors

Returns an ArrayError if

• the size of T does not match the data type size, or
• a store_array_subset error condition is met.

pub async fn async_par_store_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset, subset_elements: Vec<T> ) -> Result<(), ArrayError>

Available on crate feature async only.

Parallel version of Array::store_array_subset_elements.

pub async fn async_store_array_subset_ndarray<T: TriviallyTransmutable>( &self, subset_start: &[u64], subset_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate features async and ndarray only.

Encode subset_array and store in the array subset starting at subset_start.

Errors

Returns an ArrayError if a store_array_subset_elements error condition is met.

pub async fn async_par_store_array_subset_ndarray<T: TriviallyTransmutable>( &self, subset_start: &[u64], subset_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate features async and ndarray only.

Parallel version of Array::store_array_subset_ndarray.

pub async fn async_store_chunk_subset( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset, chunk_subset_bytes: Vec<u8> ) -> Result<(), ArrayError>

Available on crate feature async only.

Encode chunk_subset_bytes and store in chunk_subset of the chunk at chunk_indices.

Prefer to use store_chunk since this function may decode the chunk before updating it and reencoding it.

Errors

Returns an ArrayError if

• chunk_subset is invalid or out of bounds of the chunk,
• there is a codec encoding error, or
• an underlying store error.

Panics

Panics if attempting to reference a byte beyond usize::MAX.

pub async fn async_store_chunk_subset_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset, chunk_subset_elements: Vec<T> ) -> Result<(), ArrayError>

Available on crate feature async only.

Encode chunk_subset_elements and store in chunk_subset of the chunk at chunk_indices.

Prefer to use store_chunk since this will decode the chunk before updating it and reencoding it.

Errors

Returns an ArrayError if

• the size of T does not match the data type size, or
• a store_chunk_subset error condition is met.

pub async fn async_store_chunk_subset_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset_start: &[u64], chunk_subset_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate features async and ndarray only.

Encode chunk_subset_array and store in chunk_subset of the chunk in the subset starting at chunk_subset_start.

Prefer to use store_chunk since this will decode the chunk before updating it and reencoding it.

Errors

Returns an ArrayError if a store_chunk_subset_elements error condition is met.

impl<TStorage: ?Sized + ReadableStorageTraits> Array<TStorage>

pub fn new(storage: Arc<TStorage>, path: &str) -> Result<Self, ArrayCreateError>

Create an array in storage at path. The metadata is read from the store.

Errors

Returns ArrayCreateError if there is a storage error or any metadata is invalid.

pub fn retrieve_chunk( &self, chunk_indices: &[u64] ) -> Result<Box<[u8]>, ArrayError>

Read and decode the chunk at chunk_indices into its bytes.

Errors

Returns an ArrayError if

• chunk_indices are invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Panics if the number of elements in the chunk exceeds usize::MAX.

pub fn retrieve_chunk_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64] ) -> Result<Box<[T]>, ArrayError>

Read and decode the chunk at chunk_indices into a vector of its elements.

Errors

Returns an ArrayError if

• the size of T does not match the data type size,
• the decoded bytes cannot be transmuted,
• chunk_indices are invalid,
• there is a codec decoding error, or
• an underlying store error.

pub fn retrieve_chunk_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64] ) -> Result<ArrayD<T>, ArrayError>

Available on crate feature ndarray only.

Read and decode the chunk at chunk_indices into an ndarray.

Errors

Returns an ArrayError if:

• the size of T does not match the data type size,
• the decoded bytes cannot be transmuted,
• the chunk indices are invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if a chunk dimension is larger than usize::MAX.

pub fn retrieve_array_subset( &self, array_subset: &ArraySubset ) -> Result<Box<[u8]>, ArrayError>

Read and decode the array_subset of array into its bytes.

Out-of-bounds elements will have the fill value. If parallel is true, chunks intersecting the array subset are retrieved in parallel.

Errors

Returns an ArrayError if:

• the array_subset dimensionality does not match the chunk grid dimensionality,
• there is a codec decoding error, or
• an underlying store error.

Panics

Panics if attempting to reference a byte beyond usize::MAX.

pub fn par_retrieve_array_subset( &self, array_subset: &ArraySubset ) -> Result<Box<[u8]>, ArrayError>

Parallel version of Array::retrieve_array_subset.

pub fn retrieve_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<Box<[T]>, ArrayError>

Read and decode the array_subset of array into a vector of its elements.

Errors

Returns an ArrayError if:

• the size of T does not match the data type size,
• the decoded bytes cannot be transmuted,
• an array subset is invalid or out of bounds of the array,
• there is a codec decoding error, or
• an underlying store error.

pub fn par_retrieve_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<Box<[T]>, ArrayError>

Parallel version of Array::retrieve_array_subset_elements.

pub fn retrieve_array_subset_ndarray<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<ArrayD<T>, ArrayError>

Available on crate feature ndarray only.

Read and decode the array_subset of array into an ndarray.

Errors

Returns an ArrayError if:

• an array subset is invalid or out of bounds of the array,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if any dimension in chunk_subset is usize::MAX or larger.

pub fn par_retrieve_array_subset_ndarray<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset ) -> Result<ArrayD<T>, ArrayError>

Available on crate feature ndarray only.

Parallel version of Array::retrieve_array_subset_ndarray.

pub fn retrieve_chunk_subset( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset ) -> Result<Box<[u8]>, ArrayError>

Read and decode the chunk_subset of the chunk at chunk_indices into its bytes.

Errors

Returns an ArrayError if:

• the chunk indices are invalid,
• the chunk subset is invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if the number of elements in chunk_subset is usize::MAX or larger.

pub fn retrieve_chunk_subset_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset ) -> Result<Box<[T]>, ArrayError>

Read and decode the chunk_subset of the chunk at chunk_indices into its elements.

Errors

Returns an ArrayError if:

• the chunk indices are invalid,
• the chunk subset is invalid,
• there is a codec decoding error, or
• an underlying store error.

pub fn retrieve_chunk_subset_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset ) -> Result<ArrayD<T>, ArrayError>

Available on crate feature ndarray only.

Read and decode the chunk_subset of the chunk at chunk_indices into an ndarray.

Errors

Returns an ArrayError if:

• the chunk indices are invalid,
• the chunk subset is invalid,
• there is a codec decoding error, or
• an underlying store error.

Panics

Will panic if the number of elements in chunk_subset is usize::MAX or larger.

pub fn partial_decoder_opt<'a>( &'a self, chunk_indices: &[u64], parallel: bool ) -> Result<Box<dyn ArrayPartialDecoderTraits + 'a>, ArrayError>

Initialises a partial decoder for the chunk at chunk_indices with optional parallelism.

Errors

Returns an ArrayError if initialisation of the partial decoder fails.

pub fn partial_decoder<'a>( &'a self, chunk_indices: &[u64] ) -> Result<Box<dyn ArrayPartialDecoderTraits + 'a>, ArrayError>

Initialises a partial decoder for the chunk at chunk_indices.

Errors

Returns an ArrayError if initialisation of the partial decoder fails.

pub fn par_partial_decoder<'a>( &'a self, chunk_indices: &[u64] ) -> Result<Box<dyn ArrayPartialDecoderTraits + 'a>, ArrayError>

Initialises a partial decoder for the chunk at chunk_indices using multithreading if applicable.

Errors

Returns an ArrayError if initialisation of the partial decoder fails.

impl<TStorage: ?Sized + WritableStorageTraits> Array<TStorage>

pub fn store_metadata(&self) -> Result<(), StorageError>

Store metadata.

Errors

Returns StorageError if there is an underlying store error.

pub fn store_chunk( &self, chunk_indices: &[u64], chunk_bytes: Vec<u8> ) -> Result<(), ArrayError>

Encode chunk_bytes and store at chunk_indices.

A chunk composed entirely of the fill value will not be written to the store.

Errors

Returns an ArrayError if

• chunk_indices are invalid,
• the length of chunk_bytes is not equal to the expected length (the product of the number of elements in the chunk and the data type size in bytes),
• there is a codec encoding error, or
• an underlying store error.

pub fn store_chunk_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_elements: Vec<T> ) -> Result<(), ArrayError>

Encode chunk_elements and store at chunk_indices.

A chunk composed entirely of the fill value will not be written to the store.

Errors

Returns an ArrayError if

• the size of T does not match the data type size, or
• a store_chunk error condition is met.

pub fn store_chunk_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate feature ndarray only.

Encode chunk_array and store at chunk_indices.

Errors

Returns an ArrayError if

• the size of T does not match the size of the data type,
• a store_chunk_elements error condition is met.

pub fn erase_chunk(&self, chunk_indices: &[u64]) -> Result<bool, StorageError>

Erase the chunk at chunk_indices.

Returns true if the chunk was erased, or false if it did not exist.

Errors

Returns a StorageError if there is an underlying store error.

impl<TStorage: ?Sized + ReadableStorageTraits + WritableStorageTraits> Array<TStorage>

pub fn store_array_subset( &self, array_subset: &ArraySubset, subset_bytes: Vec<u8> ) -> Result<(), ArrayError>

Encode subset_bytes and store in array_subset.

If parallel is true, chunks intersecting the array subset are retrieved in parallel. Prefer to use store_chunk since this will decode and encode each chunk intersecting array_subset.

Errors

Returns an ArrayError if

• the dimensionality of array_subset does not match the chunk grid dimensionality
• the length of subset_bytes does not match the expected length governed by the shape of the array subset and the data type size,
• there is a codec encoding error, or
• an underlying store error.

pub fn par_store_array_subset( &self, array_subset: &ArraySubset, subset_bytes: Vec<u8> ) -> Result<(), ArrayError>

Parallel version of Array::store_array_subset.

pub fn store_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset, subset_elements: Vec<T> ) -> Result<(), ArrayError>

Encode subset_elements and store in array_subset.

Prefer to use store_chunk since this will decode and encode each chunk intersecting array_subset.

Errors

Returns an ArrayError if

• the size of T does not match the data type size, or
• a store_array_subset error condition is met.

pub fn par_store_array_subset_elements<T: TriviallyTransmutable>( &self, array_subset: &ArraySubset, subset_elements: Vec<T> ) -> Result<(), ArrayError>

Parallel version of Array::store_array_subset_elements.

pub fn store_array_subset_ndarray<T: TriviallyTransmutable>( &self, subset_start: &[u64], subset_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate feature ndarray only.

Encode subset_array and store in the array subset starting at subset_start.

Errors

Returns an ArrayError if a store_array_subset_elements error condition is met.

pub fn par_store_array_subset_ndarray<T: TriviallyTransmutable>( &self, subset_start: &[u64], subset_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate feature ndarray only.

Parallel version of Array::store_array_subset_ndarray.

pub fn store_chunk_subset( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset, chunk_subset_bytes: Vec<u8> ) -> Result<(), ArrayError>

Encode chunk_subset_bytes and store in chunk_subset of the chunk at chunk_indices.

Prefer to use store_chunk since this function may decode the chunk before updating it and reencoding it.

Errors

Returns an ArrayError if

• chunk_subset is invalid or out of bounds of the chunk,
• there is a codec encoding error, or
• an underlying store error.

Panics

Panics if attempting to reference a byte beyond usize::MAX.

pub fn store_chunk_subset_elements<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset: &ArraySubset, chunk_subset_elements: Vec<T> ) -> Result<(), ArrayError>

Encode chunk_subset_elements and store in chunk_subset of the chunk at chunk_indices.

Prefer to use store_chunk since this will decode the chunk before updating it and reencoding it.

Errors

Returns an ArrayError if

• the size of T does not match the data type size, or
• a store_chunk_subset error condition is met.

pub fn store_chunk_subset_ndarray<T: TriviallyTransmutable>( &self, chunk_indices: &[u64], chunk_subset_start: &[u64], chunk_subset_array: &ArrayViewD<'_, T> ) -> Result<(), ArrayError>

Available on crate feature ndarray only.

Encode chunk_subset_array and store in chunk_subset of the chunk in the subset starting at chunk_subset_start.

Prefer to use store_chunk since this will decode the chunk before updating it and reencoding it.

Errors

Returns an ArrayError if a store_chunk_subset_elements error condition is met.

impl<TStorage: ?Sized> Array<TStorage>

pub fn new_with_metadata( storage: Arc<TStorage>, path: &str, metadata: ArrayMetadata ) -> Result<Self, ArrayCreateError>

Create an array in storage at path with metadata. This does not write to the store, use store_metadata to write metadata to storage.

Errors

Returns ArrayCreateError if:

• any metadata is invalid or,
• a plugin (e.g. data type/chunk grid/chunk key encoding/codec/storage transformer) is invalid.

pub fn set_shape(&mut self, shape: ArrayShape)

Set the shape of the array.

pub fn attributes_mut(&mut self) -> &mut Map<String, Value>

Mutably borrow the array attributes.

pub const fn path(&self) -> &NodePath

Get the node path.

pub const fn data_type(&self) -> &DataType

Get the data type.

pub const fn fill_value(&self) -> &FillValue

Get the fill value.

pub fn shape(&self) -> &[u64]

Get the array shape.

pub const fn codecs(&self) -> &CodecChain

Get the codecs.

pub const fn chunk_grid(&self) -> &ChunkGrid

Get the chunk grid.

pub const fn chunk_key_encoding(&self) -> &ChunkKeyEncoding

Get the chunk key encoding.

pub const fn storage_transformers(&self) -> &StorageTransformerChain

Get the storage transformers.

pub const fn dimension_names(&self) -> &Option<Vec<DimensionName>>

Get the dimension names.

pub const fn attributes(&self) -> &Map<String, Value>

Get the attributes.

pub const fn additional_fields(&self) -> &AdditionalFields

Get the additional fields.

pub const fn parallel_codecs(&self) -> bool

Returns true if codecs can use multiple threads for encoding and decoding (where supported).

pub fn set_parallel_codecs(&mut self, parallel_codecs: bool)

Enable or disable multithreaded codec encoding/decoding. Enabled by default.

It may be advantageous to turn this off if parallelisation is external to avoid thrashing.

pub fn set_include_zarrs_metadata(&mut self, include_zarrs_metadata: bool)

Enable or disable the inclusion of zarrs metadata in the array attributes. Enabled by default.

Zarrs metadata includes the zarrs version and some parameters.

pub fn metadata(&self) -> ArrayMetadata

Create ArrayMetadata.

pub fn builder(&self) -> ArrayBuilder

Create an array builder matching the parameters of this array

pub fn chunk_grid_shape(&self) -> Option<Vec<u64>>

Return the shape of the chunk grid (i.e., the number of chunks).

pub fn chunk_shape(&self, chunk_indices: &[u64]) -> Result<Vec<u64>, ArrayError>

Return the shape of the chunk at chunk_indices.

Errors

Returns ArrayError::InvalidChunkGridIndicesError if the chunk_indices are incompatible with the chunk grid.

pub fn chunk_subset( &self, chunk_indices: &[u64] ) -> Result<ArraySubset, ArrayError>

Return the array subset of the chunk at chunk_indices.

Errors

Returns ArrayError::InvalidChunkGridIndicesError if the chunk_indices are incompatible with the chunk grid.

pub fn chunk_subset_bounded( &self, chunk_indices: &[u64] ) -> Result<ArraySubset, ArrayError>

Return the array subset of the chunk at chunk_indices bounded by the array shape.

Errors

Returns ArrayError::InvalidChunkGridIndicesError if the chunk_indices are incompatible with the chunk grid.

pub fn chunk_array_representation( &self, chunk_indices: &[u64] ) -> Result<ArrayRepresentation, ArrayError>

Get the chunk array representation at chunk_index.

Errors

Returns ArrayError::InvalidChunkGridIndicesError if the chunk_indices are incompatible with the chunk grid.

pub fn chunks_in_array_subset( &self, array_subset: &ArraySubset ) -> Result<Option<ArraySubset>, IncompatibleDimensionalityError>

Return an array subset indicating the chunks intersecting array_subset.

Returns None if the intersecting chunks cannot be determined.

Errors

Returns IncompatibleDimensionalityError if the array subset has an incorrect dimensionality.

Trait Implementations

impl<TStorage: Debug + ?Sized> Debug for Array<TStorage>

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

Formats the value using the given formatter.