File and Group

The following classes are all defined within namespace HIPP::IO::H5.

File

class File : public Group

File provides interfaces to manipulate (create, open, or retrieve metainfo from) HDF5 files.

Memory management: The file class is copyable and movable (both in construction and assignment). The copy, move and destruction are noexcept. The copy operation is shallow - the resulting object always refers to the same HDF5 resource as the source object. The move operation sets the move-from objects an empty state.

typedef Group parent_t

typedef _File _obj_raw_t

typedef std::shared_ptr<_obj_raw_t> _obj_ptr_t

Constructors: Class File “inherits” all constructors from its parent class.

File(const string &name, const string &flag = "ac", const Proplist &cporp = Proplist::vDFLT, const Proplist &aprop = Proplist::vDFLT)

Create a new file or open an existing file.

name: file name

flag: file access, must be one of the following

flag	Description
"w"	create and truncate, then open as R/W mode.
"x"	exclusively create (failed if existing), then open as R/W mode.
"ac" | "ca"	open existing file as R/W mode. Create it if not existing.
"r"	open existing file as R mode.
"a"	open existing file as R/W mode.

cprop, aprop: creation and access property lists. If to open existing one, cprop is ignored.

static File create(const string &name, const string &flag = "w", const Proplist &cprop = Proplist::vDFLT, const Proplist &aprop = Proplist::vDFLT)

Create a file.

flag specifies the access mode, must be “w” (truncate if existing) | “x” (fail if existing).

static Proplist create_proplist(const string &cls = "c")

Create a property list for file operation.

cls: The property class, must be be one from

cls	Description
"c" | "create"	file creation property list.
"a" | "access"	file access property list.
"m" | "mount"	file mount property list.

_obj_raw_t &obj_raw() noexcept

const _obj_raw_t &obj_raw() const noexcept

Return a reference to the intermediate-level HDF5 object.

Group

class Group : public NamedObj

Groups are named objects used to organized other objects in a HDF5 file. Class Group encapsulates the methods available on groups.

Memory management: The group class is copyable and movable (both in construction and assignment). The copy, move and destruction are noexcept. The copy operation is shallow - the resulting object always refers to the same HDF5 resource as the source object. The move operation sets the move-from objects an empty state.

typedef NamedObj parent_t

typedef _Group _obj_raw_t

typedef std::shared_ptr<_obj_raw_t> _obj_ptr_t

typedef _obj_raw_t::info_t info_t

Structured type that records group meta-info.

typedef _obj_raw_t::storage_type_t storage_type_t

static constexpr storage_type_t storeCOMPACT_T = _obj_raw_t::storeCOMPACT_T

static constexpr storage_type_t storeDENSE_T = _obj_raw_t::storeDENSE_T

static constexpr storage_type_t storeSYMBOL_TABLE_T = _obj_raw_t::storeSYMBOL_TABLE_T

Storage types of group.

typedef _Link::info_t link_info_t

Structured type that records link meta-info.

typedef _Link::type_t link_type_t;

static constexpr link_type_t tERROR = _Link::tERROR

static constexpr link_type_t tHARD = _Link::tHARD

static constexpr link_type_t tSOFT = _Link::tSOFT

static constexpr link_type_t tEXTERNAL = _Link::tEXTERNAL

static constexpr link_type_t tMAX = _Link::tMAX;

Type of links.

typedef _group_link_helper::iter_arg_t link_iter_arg_t

typedef _group_link_helper::iter_op_t link_iter_op_t

typedef NamedObj::info_t obj_info_t

Structured type that records object meta-info.

typedef NamedObj::info_field_t obj_info_field_t

typedef NamedObj::type_t obj_type_t

typedef _group_obj_helper::iter_arg_t obj_iter_arg_t

typedef _group_obj_helper::iter_op_t obj_iter_op_t

Constructors: Class Group “inherits” all constructors from its parent class.

void get_info(info_t &group_info) const

void get_info(const string &name, info_t &group_info, const Proplist &laprop = Proplist::vDFLT) const

void get_info(const string &group_name, hsize_t idx, info_t &group_info, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

info_t get_info() const

info_t get_info(const string &name, const Proplist &laprop = Proplist::vDFLT) const

info_t get_info(const string &group_name, hsize_t idx, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

Retrieve group meta info of the current object, of a sub object by name, or of the sub sub object indexed idx in a sub group group_name ( can be “.” to denote the group itself).

group_info: object into which the meta info is put.

idx_type, order: which type of index is used and in which order the object is visited in the index list.

The three overloads that return info_t are the same except the the group information is returned rather than filled into the argument.

void get_object_info(obj_info_t &info, info_field_t fields = NamedObj::infoALL) const

void get_object_info(const string &name, obj_info_t &info, info_field_t fields = NamedObj::infoALL, const Proplist &laprop = Proplist::vDFLT) const

void get_object_info(const string &group_name, hsize_t idx, obj_info_t &info, info_field_t fields = NamedObj::infoALL, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

obj_info_t get_object_info(info_field_t fields = NamedObj::infoALL) const

obj_info_t get_object_info(const string &name, info_field_t fields = NamedObj::infoALL, const Proplist &laprop = Proplist::vDFLT) const

obj_info_t get_object_info(const string &group_name, hsize_t idx, info_field_t fields = NamedObj::infoALL, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

Retrive the object meta info of the current object, of a sub object by name, or of a sub sub object indexed idx in the sub group group_name (can be “.” to denote the group itself).

info: object into which the meta info is put.

idx_type, order: which type of index is used and in which order the object is visited in the index list.

The three overloads that return obj_info_t are the same except the the object information is returned rather than filled into the argument.

void get_link_info(const string &name, link_info_t &info, const Proplist &laprop = Proplist::vDFLT) const

void get_link_info(const string &group_name, hsize_t idx, link_info_t &info, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

link_info_t get_link_info(const string &name, const Proplist &laprop = Proplist::vDFLT) const

link_info_t get_link_info(const string &group_name, hsize_t idx, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

void get_link_val(const string &name, vector<char> &buff, const Proplist &laprop = Proplist::vDFLT) const

void get_link_val(const string &group_name, hsize_t idx, vector<char> &buff, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

string get_link_name(const string &group_name, hsize_t idx, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

Retrive the link meta info of a sub object by name, or of a sub sub object indexed idx in the sub group group_name (can be “.” to denote the group itself).

info: object into which the meta info is put.

idx_type, order: which type of index is used and in which order the object is visited in the index list.

The two overloads that return link_info_t are the same except the the link information is returned rather than filled into the argument.

get_link_val() and get_link_name() return the link value and name, respectively.

buff: on return, link value is filled into it and its size is adjusted to fit.

bool link_exists(const string &name, const Proplist &laprop = Proplist::vDFLT) const

bool object_exists(const string &name, const Proplist &laprop = Proplist::vDFLT) const

bool object_exists_by_type(const string &name, obj_type_t obj_type, const Proplist &laprop = Proplist::vDFLT) const

bool group_exists(const string &name) const

bool dataset_exists(const string &name) const

Find whether or not certain item exists in the current group. If any of the intermediate steps in the name does not exists, or does not resolve to an object, or the final target link does not exits, return false.

(1): for link of any type.

(2): the same as (1) but also check that the target link resolves to an object of any type.

(3): the same as (2), but further require that the target match the object type given by obj_type.

(4,5): special cases of (3), and with default link access property list.

void create_hard_link(const string &name, const Group &src, const string &src_name, const Proplist &lcprop = Proplist::vDFLT, const Proplist &laprop = Proplist::vDFLT)

void create_soft_link(const string &name, const string &src_name, const Proplist &lcprop = Proplist::vDFLT, const Proplist &laprop = Proplist::vDFLT)

void create_external_link(const string &name, const string &src_file_name, const string &src_obj_name, const Proplist &lcprop = Proplist::vDFLT, const Proplist &laprop = Proplist::vDFLT)

Create a new link named name under the current group.

src, src_name: the linked location and name.

src_file_name, src_obj_name: the external file and linked object name.

void move_link(const string &name, Group &dst, const string &dst_name, const Proplist &lcprop = Proplist::vDFLT, const Proplist &laprop = Proplist::vDFLT)

void copy_link(const string &name, Group &dst, const string &dst_name, const Proplist &lcprop = Proplist::vDFLT, const Proplist &laprop = Proplist::vDFLT)

void delete_link(const string &name, const Proplist &laprop = Proplist::vDFLT)

void delete_link(const string &group_name, hsize_t idx, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT)

Link modification.

(1): move a linked named name under the current group to that named dst_name under another group dst.

(2): the same as (1), but do not remove the current link, i.e., the link gets copied.

(3,4): delete a link from the current group by name, or by index idx in the sub group named group_name.

herr_t link_iterate(hsize_t &idx, link_iter_op_t op, void *op_data = nullptr, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE) const

herr_t link_iterate(const string &group_name, hsize_t &idx, link_iter_op_t op, void *op_data = nullptr, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

herr_t link_visit(link_iter_op_t op, void *op_data = nullptr, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE) const

herr_t link_visit(const string &group_name, link_iter_op_t op, void *op_data = nullptr, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

herr_t object_visit(obj_iter_op_t op, void *op_data = nullptr, info_field_t fields = NamedObj::infoALL, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE) const

herr_t object_visit(const string &group_name, obj_iter_op_t op, void *op_data = nullptr, info_field_t fields = NamedObj::infoALL, index_t idx_type = idxNAME, iter_order_t order = iterNATIVE, const Proplist &laprop = Proplist::vDFLT) const

Iteration methods.

link_iterate(): iterate over the links in the current group, or the links in a sub group named group_name, starting at index idx. On exit, idx indicates the next position to iterate. The iterate is non-recursive.

link_visit(), object_visit(): similar but recursively visit all links and all objects, respectively.

The user-provided callback op may return

• 0: then the iteration continues, until success.

• positive: shortcut success, causing the method returns immediately with that returned value.

• negative: short failure, causing the iteration stops and throws an ErrH5 with that returned value as error number.

op_data: passed to op.

idx_type, order: which type of index is used and in which order the object is visited in the index list.

Group create_group(const string &name, const string &flag = "ac", const Proplist &lcprop = Proplist::vDFLT, const Proplist &gcprop = Proplist::vDFLT, const Proplist &gaprop = Proplist::vDFLT)

Create a group with link name name under the current group.

flag: determine what to do if the group named name already exists. Can be

flag	Description
"x"	failed and throw an ErrH5 exception.
"ac" | "ca"	open it anyway. In this case lcprop and gcprop are ignored.
"trunc" | "w"	(deprecated) the same as “ac”.
"excl"	(deprecated) the same as “x”.

Group open_group(const string &name, const Proplist &aprop = Proplist::vDFLT) const

Open an existing group with path name name.

DatasetManager datasets() noexcept

Returns a dataset manager of this group. Tha manager provides commonly used shortcuts for dataset creation and access.

Dataset create_dataset(const string &name, const Datatype &dtype, const Dataspace &dspace, const string &flag = "ac", const Proplist &lcprop = Proplist::vDFLT, const Proplist &dcprop = Proplist::vDFLT, const Proplist &daprop = Proplist::vDFLT)

template<typename T>
Dataset create_dataset(const string &name, const Dataspace &dspace, const string &flag = "ac", const Proplist &lcprop = Proplist::vDFLT, const Proplist &dcprop = Proplist::vDFLT, const Proplist &daprop = Proplist::vDFLT)

template<typename T>
Dataset create_dataset_scalar(const string &name, const string &flag = "ac")

Dataset create_dataset_str(const string &name, size_t n, const string &flag = "ac")

Dataset create_dataset_str(const string &name, size_t n_str, size_t n, const string &flag = "ac")

Create a dataset named name under the current group.

(1): The most general method that is the direct HDF5 C API counterpart.

(2): The datatype is inferred from T as if calling Datatype::from_type<T>().

Other methods are defined for special cases. All of them use the default property list Proplist::vDFLT.

(3): Create a scalar dataset whose datatype is inferred from T as if calling Datatype::from_type<T>().

(4-5): Create a dataset for fix-length ATOMIC STRING sized n, or a list of n_str such strings. n must include the space for the null-term.

flag: determine what to do if the dataset already exists. Can be

flag	Description
"x"	failed and throw an ErrH5 exception.
"ac" | "ca"	open it anyway. In this case lcprop and dcprop are ignored.
"trunc" | "w"	(deprecated) the same as “ac”.
"excl"	(deprecated) the same as “x”.

template<typename T>
Dataset create_dataset_for(const string &name, const T &buff, const string &flag = "ac")

template<typename T>
Dataset create_dataset_for_scalar(const string &name, const T &x, const string &flag = "ac")

Dataset create_dataset_for_str(const string &name, const string &s, const string &flag = "ac")

Dataset create_dataset_for_str(const string &name, const char *s, const string &flag = "ac")

Dataset create_dataset_for_str(const string &name, const vector<string> &ss, const string &flag = "ac")

template<size_t N_STR>
Dataset create_dataset_for_str(const string &name, const string (&ss)[N_STR], const string &flag = "ac")

template<size_t N_STR, size_t N>
Dataset create_dataset_for_str(const string &name, const char (&ss)[N_STR][N], const string &flag = "ac")

create_dataset_for(): create a dataset from the object to be written. The library infers the datatype and dataspace from the object.

(1): any non-string object, which can be any single object that is resolvable by ConstDatapacket. The returned dataset can be called with write(buff) to write the object into it. Examples of buff include

• single scalar value, e.g., int x;

• array-like object, e.g., std::array<int, 3> x, int x[3][4];

• vector of scalar values, e.g., std::vector<double> x;

• vector of array-like objects, e.g., std::vector< std::array<int, 3> > x.

(2): any object that can be resolved as a ATOMIC type, i.e., any valid type to Datatype::from_cvt(). The difference from (1) is that, array-like objects are treated as ATOMIC ARRAY datatype here. The returned dataset can be applied with write_scalar(x).

(3-7): string of list of strings. The returned attribute can therefore be written by write_str(s) or write_str(ss). The created dataset has fix-length ATOMIC STRING datatype.

Dataset open_dataset(const string &name, const Proplist &aprop = Proplist::vDFLT) const

Open an existing dataset of given path name name.

_obj_raw_t &obj_raw() noexcept

const _obj_raw_t &obj_raw() const noexcept

Return a reference to the intermediate-level HDF5 object.

class _group_link_helper::iter_arg_t

Group &group() noexcept

const string &name() const noexcept

const Group::link_info_t &info() const noexcept

void *op_data() const noexcept

Retrieve the root group, current link path, current link info and user-provided data in the iteration.

typedef std::function<herr_t(_group_link_helper::iter_arg_t&)> _group_link_helper::iter_op_t

class _group_obj_helper::iter_arg_t

Group &group() noexcept

const string &name() const noexcept

const info_t &info() const noexcept

void *op_data() const noexcept

Retrieve the root group, current object path, current object info and user-provided data in the iteration.

typedef std::function<herr_t(_group_obj_helper::iter_arg_t&)> _group_obj_helper::iter_op_t