Expand description
§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
- Install the Rust compiler (and cargo).
- Put Findzarrs.cmake in your
CMAKE_MODULE_PATH
find_package(zarrs <version> REQUIRED COMPONENTS zarrs/bz2)
- Replace
<version>
with the latest release:(e.g.,
0.9
or0.9.0
) - zarrs is retrieved from
GitHub
using FetchContent and built using corrosion - Components are optional zarrs codecs
- Replace
- the
zarrs_ffi
library is available as thezarrs::zarrs
orzarrs::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§
Enums§
- A zarrs data type.
Functions§
- Get the array attributes as a JSON string.
- Return the number of chunks in the chunk grid.
- Get the origin of a chunk.
- Get the shape of a chunk.
- Get the size of a chunk in bytes.
- Return the chunks indicating the chunks intersecting
array_subset
. - Returns the data type of the array.
- Returns the dimensionality of the array.
- Get the shape of the inner chunk grid of a sharded array.
- Get the inner chunk shape for a sharded array.
- Get the array metadata as a JSON string.
- Returns the shape of the array.
- Get the size of a subset in bytes.
- Retrieve a chunk from an array.
- Retrieve an inner chunk from a sharded array (or outer chunk for an unsharded array).
- Retrieve a subset from an array.
- Retrieve a subset from an array (with a shard index cache).
- Set the array attributes from a JSON string.
- Store a chunk.
- Store array metadata.
- Store an array subset.
- Create a handle to a new array (read/write capability).
- Create a handle to a new shard index cache.
- Create a storage handle to a filesystem store.
- Destroy array.
- Destroy a shard index cache.
- Destroy storage.
- Free a string created by zarrs.
- Get the last error string.
- Create a handle to an existing array (read/write capability).
- Get the zarrs version.
- Get the zarrs major version.
- Get the zarrs minor version.
- Get the zarrs patch version.
Type Aliases§
- An opaque handle to a zarr array.
- An opaque handle to a zarrs
ArrayShardedReadableExtCache
. - An opaque handle to a zarr store or storage transformer.