Crate zarrs_ffi

zarrs_ffi

C/C++ bindings for the zarrs crate, a Rust library for the Zarr storage format for multidimensional arrays and metadata.

zarrs_ffi is a single header library: zarrs.h (docs).

Currently zarrs_ffi only supports a small subset of the zarrs API.

A changelog can be found here.

Example

#include "zarrs.h"

void main() {
  // Open a filesystem store pointing to a zarr hierarchy
  ZarrsStorage storage = nullptr;
  zarrs_assert(zarrsCreateStorageFilesystem("/path/to/hierarchy.zarr", &storage));

  // Open an array in the hierarchy
  ZarrsArray array = nullptr;
  zarrsOpenArrayRW(storage, "/array", metadata, &array);

  // Get the array dimensionality
  size_t dimensionality;
  zarrs_assert(zarrsArrayGetDimensionality(array, &dimensionality));
  assert(dimensionality == 2);

  // Retrieve the decoded bytes of the chunk at [0, 0]
  size_t indices[] = {0, 0};
  size_t chunk_size;
  zarrs_assert(zarrsArrayGetChunkSize(array, 2, indices, &chunk_size));
  std::unique_ptr<uint8_t[]> chunk_bytes(new uint8_t[chunk_size]);
  zarrs_assert(zarrsArrayRetrieveChunk(array, 2, indices, chunk_size, chunk_bytes.get()));
}

See a more comprehensive example in the examples directory.

CMake Quickstart

1. Install the Rust compiler (and cargo).
2. Put Findzarrs.cmake in your CMAKE_MODULE_PATH
3. find_package(zarrs <version> REQUIRED COMPONENTS zarrs/bz2)
   • Replace <version> with the latest release: (e.g., 0.9 or 0.9.1)
   • zarrs is retrieved from GitHub using FetchContent and built using corrosion
   • Components are optional zarrs codecs
4. the zarrs_ffi library is available as the zarrs::zarrs or zarrs::zarrs-static target

A complete CMake example can be found in examples/cmake_project.

Manual Build

Basic Build

Building generates a header, and a platform-dependent static and dynamic library.

cargo build --release --features cbindgen # -> zarrs.h and target/release/[lib]zarrs_ffi{.a,.so,.dll,.dylib}

zarrs.h is only re-generated if the cbindgen feature is enabled.

Enabling SIMD intrinsics

Encoding and decoding performance may be improved with avx2/sse2 enabled (if supported). Compile with either of:

• RUSTFLAGS="-C target-cpu=native"
• RUSTFLAGS="-C target-feature=+avx2,+sse2"

Enabling non-default zarrs codecs

Non-default zarrs codecs (see zarrs crate features) can be enabled with the all_codecs feature. Alternatively, individual codecs can be enabled by passing them as feature flags. For example:

cargo build --release --features cbindgen --features zarrs/zstd,zarrs/bitround,zarrs/zfp,zarrs/bz2,zarrs/pcodec,zarrs/gdeflate

Licence

zarrs_ffi is licensed under either of

• the Apache License, Version 2.0 LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0 or
• the MIT license LICENSE-MIT or http://opensource.org/licenses/MIT, at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Modules

array_read

array_read_write

array_sharded

array_write

data_type

Enums

ZarrsDataType

A zarrs data type.

ZarrsResult

Functions

zarrsArrayGetAttributesString^⚠

Get the array attributes as a JSON string.

zarrsArrayGetChunkGridShape^⚠

Return the number of chunks in the chunk grid.

zarrsArrayGetChunkOrigin^⚠

Get the origin of a chunk.

zarrsArrayGetChunkShape^⚠

Get the shape of a chunk.

zarrsArrayGetChunkSize^⚠

Get the size of a chunk in bytes.

zarrsArrayGetChunksInSubset^⚠

Return the chunks indicating the chunks intersecting array_subset.

zarrsArrayGetDataType^⚠

Returns the data type of the array.

zarrsArrayGetDimensionality^⚠

Returns the dimensionality of the array.

zarrsArrayGetInnerChunkGridShape^⚠

Get the shape of the inner chunk grid of a sharded array.

zarrsArrayGetInnerChunkShape^⚠

Get the inner chunk shape for a sharded array.

zarrsArrayGetMetadataString^⚠

Get the array metadata as a JSON string.

zarrsArrayGetShape^⚠

Returns the shape of the array.

zarrsArrayGetSubsetSize^⚠

Get the size of a subset in bytes.

zarrsArrayRetrieveChunk^⚠

Retrieve a chunk from an array.

zarrsArrayRetrieveInnerChunk^⚠

Retrieve an inner chunk from a sharded array (or outer chunk for an unsharded array).

zarrsArrayRetrieveSubset^⚠

Retrieve a subset from an array.

zarrsArrayRetrieveSubsetSharded^⚠

Retrieve a subset from an array (with a shard index cache).

zarrsArraySetAttributes^⚠

Set the array attributes from a JSON string.

zarrsArrayStoreChunk^⚠

Store a chunk.

zarrsArrayStoreMetadata^⚠

Store array metadata.

zarrsArrayStoreSubset^⚠

Store an array subset.

zarrsCreateArrayRW^⚠

Create a handle to a new array (read/write capability).

zarrsCreateShardIndexCache^⚠

Create a handle to a new shard index cache.

zarrsCreateStorageFilesystem^⚠

Create a storage handle to a filesystem store.

zarrsDestroyArray^⚠

Destroy array.

zarrsDestroyShardIndexCache^⚠

Destroy a shard index cache.

zarrsDestroyStorage^⚠

Destroy storage.

zarrsFreeString^⚠

Free a string created by zarrs.

zarrsLastError

Get the last error string.

zarrsOpenArrayRW^⚠

Create a handle to an existing array (read/write capability).

zarrsVersion

Get the zarrs version.

zarrsVersionMajor

Get the zarrs major version.

zarrsVersionMinor

Get the zarrs minor version.

zarrsVersionPatch

Get the zarrs patch version.

Type Aliases

ZarrsArray

An opaque handle to a zarr array.

ZarrsShardIndexCache

An opaque handle to a zarrs ArrayShardedReadableExtCache.

ZarrsStorage

An opaque handle to a zarr store or storage transformer.