v2.hpp File Reference

#include <cstdint>
#include <cstdlib>
#include <limits>
#include <optional>
#include <string>
#include <vector>
#include "libzarr/detail/common.hpp"
#include "libzarr/metadata.hpp"
#include "libzarr/store.hpp"
#include "libzarr/types.hpp"

Go to the source code of this file.

Classes
struct	zarr::v2::ParsedDType
	A parsed v2 dtype string: the element type plus its stored byte order. More...

Functions
std::string	zarr::v2::meta_key (const std::string &path, const char *suffix)
	Store key of a metadata document for the node at path ("" = root).
ParsedDType	zarr::v2::parse_data_type (const std::string &text, const std::string &ctx)
std::string	zarr::v2::emit_data_type (DataType dt, bool big_endian)
std::optional< Bytes >	zarr::v2::parse_fill (const json &v, DataType dt, const std::string &ctx)
ArrayMeta	zarr::v2::parse_array_meta (const json &j, const std::string &ctx)
json	zarr::v2::emit_array_meta (const ArrayMeta &meta)
json	zarr::v2::emit_group_meta ()
	The (only) content of a v2 group document.
void	zarr::v2::check_group_meta (const json &j, const std::string &ctx)
	Validates a .zgroup document.
std::string	zarr::v2::chunk_key (const std::vector< std::uint64_t > &index, char separator)
void	zarr::v2::write_meta_key (Store &store, const std::string &key, const json &value)
void	zarr::v2::erase_meta_key (Store &store, const std::string &key)
	Removes a metadata document, keeping .zmetadata in sync (see write_meta_key).
void	zarr::v2::consolidate (Store &store)
std::optional< json >	zarr::v2::read_consolidated (Store &store)
	Loads the consolidated metadata map if present and well-formed.

Variables
constexpr const char *	zarr::v2::kArraySuffix = ".zarray"
	v2 array metadata document name.
constexpr const char *	zarr::v2::kGroupSuffix = ".zgroup"
	v2 group metadata document name.
constexpr const char *	zarr::v2::kAttrsSuffix = ".zattrs"
	v2 attributes document name.
constexpr const char *	zarr::v2::kConsolidatedKey = ".zmetadata"
	v2 consolidated-metadata document (store root).

Detailed Description

Zarr v2 metadata: parsing (tolerant) and emission (canonical), chunk keys, and consolidated metadata (.zmetadata). Parsing lowers v2 forms into the normalized ArrayMeta: compressor -> a bytes->bytes codec, order:"F" -> a transpose codec, dtype byte order -> the "bytes" codec's endian.

Function Documentation

chunk_key()

std::string zarr::v2::chunk_key ( const std::vector< std::uint64_t > &  index, char  separator  )

inline

v2 chunk key relative to the array: indices joined by the separator; rank-0 arrays use the fixed key "0".

consolidate()

void zarr::v2::consolidate ( Store &  store )

inline

Builds (or rebuilds) .zmetadata from every v2 metadata document in the store, in zarr-python's consolidated format 1.

emit_array_meta()

json zarr::v2::emit_array_meta ( const ArrayMeta &  meta )

inline

Emits canonical .zarray JSON. Deterministic: sorted keys, stable forms; dimension_separator appears only when '/' (matching common practice).

emit_data_type()

std::string zarr::v2::emit_data_type ( DataType  dt, bool  big_endian  )

inline

Emits the canonical v2 dtype string. big_endian is preserved from an opened array (we never create big-endian arrays, but re-emitting an opened one must not lie about its chunk bytes).

parse_array_meta()

ArrayMeta zarr::v2::parse_array_meta ( const json &  j, const std::string &  ctx  )

inline

Parses a .zarray document into normalized ArrayMeta (without attributes, which live in .zattrs). Unknown members are ignored: v2 predates v3's must-understand rule and extra keys are common in the wild.

parse_data_type()

ParsedDType zarr::v2::parse_data_type ( const std::string &  text, const std::string &  ctx  )

inline

Parses a v2 dtype string ([<>|][biufV]<size>). Read-supported kinds only; everything else fails with a precise error naming the dtype.

parse_fill()

std::optional< Bytes > zarr::v2::parse_fill ( const json &  v, DataType  dt, const std::string &  ctx  )

inline

Parses a v2 fill_value, dtype-directed. Tolerant per our READ policy; each tolerance cites its origin.

write_meta_key()

void zarr::v2::write_meta_key ( Store &  store, const std::string &  key, const json &  value  )

inline

Writes a metadata document and, when a consolidated .zmetadata exists at the store root, keeps it in sync (decision: consolidated metadata is maintained by default so it can never go stale through libzarr writes).