Namespace `hdf5`¶

Classes¶

`ObjectHandle`¶

class ObjectHandle¶

Wrapper for hid_t object identifiers.

Objects in HDf5 are referenced using an handle of type hid_t. Though the name of the type and the API reference of the HDF5 C-API suggest this value is an ID it should be rather considered a handle which is used to reference a particular object.

The aim of this class is to encapsulate an HDF5 handler and control the reference counting for that handler for copy and move construction and assignment.

copy construction and assignment increments the reference count of an handler
move construction and assignment leaves the reference count unchanged
closing an object decrements the reference count
in addition, the reference count is decreased if the destructor of an instance of ObjectHandle is called

From that point of view ObjectHandle could also be considered as a guard object for a handle which ensures that an object gets closed once it looses scope.

The class also comprises a set of static member functions which provide operations on the handler.

Public Types

enum class Type¶

type of the object handle

Values:

enumerator Uninitialized¶

enumerator BadObject¶

enumerator File¶

enumerator Group¶

enumerator Datatype¶

enumerator Dataspace¶

enumerator Dataset¶

enumerator Attribute¶

enumerator PropertyList¶

enumerator VirtualFileLayer¶

enumerator PropertyListClass¶

enumerator ErrorClass¶

enumerator ErrorMessage¶

enumerator ErrorStack¶

enum class Policy¶

type of the ward policy

Values:

enumerator WithWard¶

enumerator WithoutWard¶

Public Functions

explicit ObjectHandle(hid_t id, Policy policy = Policy::WithWard)¶

construct from HDF5 ID

This constructor can be used to construct an instance of h5object from an HDF5 ID. h5object takes full control over the constructed object. Thus the constructor has move semantics and does not allow to use const & or & to the hid_t argument. A typical usage example would look like this

.....
hdf5::ObjectHandle handle(H5Gopen(fid,"data",hdf5::property::kDefault));
...

An exception is thrown if the ID passed is negative.

Throws

std::runtime_error – if the passed id is invalid (<0)

Parameters

id – HDF5 object ID.
policy – with or w/o ward policy.

explicit ObjectHandle() noexcept¶

default constructor

The default constructor does not throw. However, after default construction the object will be in an invalid state.

ObjectHandle(const ObjectHandle &o)¶

copy constructor

Copies the ID of the o and increments its reference counter if the object is valid.

Throws: std::runtime_error – in case of errors
Parameters: o – object which to cpy

ObjectHandle(ObjectHandle &&o) noexcept¶

move constructor

Copies the ID of the original object and sets the ID of the original object to 0. As this is a move process the reference counter of the ID will not be incremented.

Parameters: o – object to move

~ObjectHandle() noexcept¶: destructor

ObjectHandle &operator=(const ObjectHandle &o)¶

copy assignment operator

Just like for the copy constructor the reference counter for the original ID is incremented.

Throws: std::runtime_error – in case of errors
Parameters: o – object to assign
Returns: refence to object

ObjectHandle &operator=(ObjectHandle &&o) noexcept¶

move assignment operator

Like the move constructor this operator has no influence on the value of the IDs reference counter.

Throws: std::runtime_error – in case of errors
Parameters: o – object form which to move data
Returns: reference to object

inline explicit operator hid_t() const¶: conversion operator

void close()¶

close the object

This will decrement the reference counter of the ID held by this object or close it if the reference counter approaches 0. The close method runs an object introspection by means of the HDF5 library and calls the appropriate close function.

Throws: std::runtime_error – if the close operation fails

bool is_valid() const¶

check validity

This method returns true of the object refers to a valid HDF5 object. In other words this means that the object is valid and available. For a file object this would mean that the file is open.

Throws: std::runtime_error – if object status retrieval fails
Returns: true if valid HDF5 object

ObjectHandle::Type get_type() const¶

get nexus object type

Throws: std::runtime_error – if the type is unknown
Returns: object type

int get_reference_count() const¶

return reference counter value

Throws: std::runtime_error – if retrieval of the reference count fails
Returns: the actual reference count

bool hdf5::operator==(const ObjectHandle &lhs, const ObjectHandle &rhs)¶

equality operator

Two instances of ObjectHandle are considered equal when their internal representation have equal value. This is not a sufficient criteria for object equality!

bool hdf5::operator!=(const ObjectHandle &lhs, const ObjectHandle &rhs)¶

not equal to operator

Simply the inverse of the == operator.

std::ostream &hdf5::operator<<(std::ostream &stream, const ObjectHandle::Type &type)¶: output operator for Types

`Path`¶

class Path¶

path to a node object

Every object within an HDF5 file can be addressed via a path. Such a path is a list of link names separated by a slash /. While HDF5s C-API uses a simple string to represent a path, the C++ wrapper provides a class for this purpose.

Though an HDF5 path look quit similar to an Unix filesystem path there is one major difference: .. has no special meaning. On a Unix filesystem .. would reference to the directory above the current one. In HDF5 .. simply means nothing. It would be even allowed to use .. as a name for a group, dataset or committed datatype.

Public Functions

Path()¶

default constructor

After default construction is list of path elements is empty and the absolute path flag is set to false.

Path(const std::string &str)¶

constructor

Construct a path from a string. We use an explicit constructor here to avoid accidental conversions.

Path(const_iterator first_element, const_iterator last_element)¶: constructor from iterators

Warning

Should not be used, as there is no automatic sanitation. May not conform to hdf5 requirements for node names.

size_t size() const noexcept¶

return number of path elements

Returns the number of elements in the path. In the case that the path references the root group this method will return 0.

const_iterator begin() const¶

get forward iterators

Get the iterators to the beginning or the end+1 element of the path in forward direction.

Path p("/run/sensors/temperature");
std::for_each(p.begin(),p.end(),
              [](const std::string &name) { std::cout<<name<<" "; });
//output: run sensors temperature

const_reverse_iterator rbegin() const¶

get reverse iterator

rbegin() and rend() return the pair of reverse iterators for the path.

Path p("/run/sensors/temperature");
std::for_each(p.rbegin(),p.rend(),
              [](const std::string &name) { std::cout<<name<<" "; });
//output: temperature sensors run

Returns: instance of a const reverse iterator

bool absolute() const noexcept¶

returns true if a path is absolute

A path is considered absolute if its first element references the root node. This is indicated by a leading / of the path string.

hdf5::Path p("/log/data");
if(p.absolute())
{
   std::cout<<"got absolute path"<<std::endl;
}

Returns: true if path is absolute, false otherwise

void absolute(bool value) noexcept¶

set a path to be absolute

Use this flag to set or unset the absolut flag.

Path p("data/modules");
std::cout<<p<<std::endl; // output: data/modules
p.absolute(true);
std::cout<<p<<std::endl; // output: /data/modules
p.absolute(false);
std::cout<<p<<std::endl; // output: data/modules

Parameters: value – boolean value deciding whether a path is absolute or not

bool is_root() const¶

true if the path refers to the root group

A path is considered to reference the root group if the list of elements is empty but the absolute path flag is set.

You can construct a root path with

Path root_path("/");

or

Path root_path();
root_path.absolute(true);

though the former idiom shoud be prefered.

Returns: true if the path references the root group, false otherwise

bool is_name() const¶

true if the path is a valid child name

A path is considered to be a valid child name if list of elements equals one and the absolute path flag is not set.

Returns: true if the path is a valid child name, otherwise false

std::string name() const¶

get object name from a path

The object name is the last element of a path. If the path references the root group the return value is “.”.

Path p("/run/sensors/temperature");
std::cout<<p.name()<<std::endl; //output: temperature

Returns: last element of the path

Path parent() const¶

get parent path

This is basically the path with the last component stripped of. In the case that the path references the root group the parent is the root group again.

Path p("/run/sensors/temperature");
std::cout<<p.parent()<<std::endl; //output: /run/sensors

but

Path root_group("/");
std::cout<<root_group.parent()<<std::endl; //output: /

Returns: new Path instance referencing the parent path of this instance

void append(const Path &p)¶

append a path to this instance

Adding path p to this instance. Basically this

hdf5::Path base_path("/entry/instrument");
hdf5::Path detector_transforms("detector/transformations");
hdf5::Path p = base_path.append(detector_transforms);
std::cout<<p<<std::endl;
//output: /entry/instrument/detector/transformations

Path hdf5::operator+(const Path &lhs, const Path &rhs)¶

bool hdf5::operator==(const Path &lhs, const Path &rhs)¶

checks two paths for equality

Two paths are considered equal if each of their elements is

bool hdf5::operator!=(const Path &lhs, const Path &rhs)¶

std::ostream &hdf5::operator<<(std::ostream &stream, const Path &path)¶

Path hdf5::common_base(const Path &lhs, const Path &rhs)¶: checks two paths for equality base

`IteratorConfig`¶

class IteratorConfig¶

iterator configuration

This class encapsulates the iteration configuration for nodes, attributes and links.

Public Functions

IteratorConfig()¶: default constructor

IteratorConfig(const IteratorConfig&) = default¶

copy constructor

We use the compiler provided default implementation here.

IterationOrder order() const noexcept¶: get the current iteration order

void order(IterationOrder o) noexcept¶: set the iteration order

IterationIndex index() const noexcept¶: get the current iteration index

void index(IterationIndex i) noexcept¶: set the current iteration index

enum class hdf5::IterationOrder : std::underlying_type<H5_iter_order_t>::type¶

iteration order

This enumeration is used to control how an iterator traverses an iterable with a particular index.

Values:

enumerator Increasing¶: iteration in increasing index order

enumerator Decreasing¶: iteration in decreasing index order

enumerator Native¶: iteration in native index order

std::ostream &hdf5::operator<<(std::ostream &stream, const IterationOrder &order)¶: ouput stream for iteration order enumeration

enum class hdf5::IterationIndex : std::underlying_type<H5_index_t>::type¶

iteration index

Values:

enumerator Name¶: using the name as index

enumerator CreationOrder¶: using creation time as index

std::ostream &hdf5::operator<<(std::ostream &stream, const IterationIndex &index)¶

`Version`¶

class Version¶

a 3 number version class

Describes a version number.

Public Types

using NumberType = unsigned long¶: the number type used to represent version numbers

Public Functions

Version() noexcept¶

default constructor

Set all three version numbers to 0

Version(NumberType major_number, NumberType minor_number, NumberType patch) noexcept¶

constructor

Parameters

major_number – the major version number
minor_number – the minor version number
patch – the patch version number

NumberType major_number() const noexcept¶: return the major version number

NumberType minor_number() const noexcept¶: return the minor version number

NumberType patch_number() const noexcept¶: return the patch version number

Public Static Functions

static std::string to_string(const Version &version)¶

convert a Version to a string

The result is a string with the format MAJOR.MINOR.PATCH.

Parameters: version – reference to a instance of Version
Returns: a new instance of std::string

std::ostream &hdf5::operator<<(std::ostream &stream, const Version &version)¶

output stream operator

Writes an instance of Version to a std::ostream. The output format is the same as for Version::to_string.

`ObjectId`¶

class ObjectId¶

Unique ID of an HDF5 object.

Such an ID is constructed from an ObjectHandle instance. However, no reference to that handle is stored in the class. An instance of ObjectId allows the unique identification of an HDF5 object within the context of a program. The ID is currently formed from the

address of an object within the file it is stored
the HDF5 file number of the objects parent file

Optinally we also provide the name of the the object is stored in.

Public Functions

inline ObjectId()¶

default constructor

We need the default constructor for compliance with STL containers as we may want to store IDs in one.

ObjectId(const ObjectHandle &handle)¶

constructor

Construct an ID from a handler instance. If the handler is default constructed and thus invalid a default constructed Id instance will be returned.

Parameters: handle – reference to an object handler

bool operator==(const ObjectId &other) const¶: Equality operator for IDs.

bool operator!=(const ObjectId &other) const¶: Inequality operator for IDs.

bool operator<(const ObjectId &other) const¶: Allows sorting of IDs.

unsigned long file_number() const noexcept¶

Get the HDF5 file number.

Return the HDF5 file number of the file the object referenced by this ID belongs to. If the ID is default constructed this method returns 0.

Returns: file number of the parent file

haddr_t object_address() const noexcept¶

Get object address.

Return the address of the referenced object within its file. If the ID instance is default constructed this method returns 0.

Returns: object address within its file

fs::path file_name() const noexcept¶

Get file name.

Return the name fo the file the object referenced by this ID is stored in. An empty path is returned in the case of a default constructed ID.

Returns: path to the objects parent file

Public Static Functions

static std::string get_file_name(const ObjectHandle &handle)¶

get the name of the file

Obtains the name of the file where the object is stored in.

static H5O_info_t_ get_info(const ObjectHandle &handle)¶

get object info

H5O_info_t

Gets object info.

For HDF5 version 1.12.0 and higher, this explicitly returns a H5O_info1_t structure. For versions <= 1.10.5 it returns H5O_info_t.

std::ostream &hdf5::operator<<(std::ostream &os, const ObjectId &p)¶: stream output operator for ObjectId class

`Context`¶

class Context¶

`IOWriteBuffer`¶

class IOWriteBuffer¶

`IOReadBuffer`¶

class IOReadBuffer¶

`FixedLengthStringBuffer`¶

template<typename CharT> class FixedLengthStringBuffer : public std::vector<CharT>¶

`Iterator`¶

class Iterator¶

Subclassed by hdf5::attribute::AttributeIterator, hdf5::node::LinkIterator, hdf5::node::NodeIterator

Public Functions

Iterator()¶: default constructor

Iterator &operator++()¶: increment iterator position

inline ssize_t index() const¶: get state of the iterator

Iterator hdf5::operator+(const Iterator &a, ssize_t b)¶

Iterator hdf5::operator+(ssize_t a, const Iterator &b)¶

Iterator hdf5::operator-(const Iterator &a, ssize_t b)¶

ssize_t hdf5::operator-(const Iterator &a, const Iterator &b)¶

`ArrayAdapter`¶

template<typename T> class ArrayAdapter¶

adapter for C-style arrays

In order to work read or write data from and to C-style arrays a special adapter is required. A native C-array does not carry all the information required to construct a dataspace for HDF5 IO. It lacks the size information. A dataspace and a datatype trait exist for this adapter template.

double *data = new double[100];

The ArrayAdapter<T> template does not hold ownership of the array it references. So all resource management has to be done by the calling instance.

Template Parameters: T – data type of the pointer

Public Functions

inline ArrayAdapter()¶: default constructor

inline ArrayAdapter(T *data, size_t size)¶

constructor

Parameters

data – pointer to the data data to which to read or write data
size – number of elements referenced by the pointer

ArrayAdapter(const ArrayAdapter<T> &adapter)¶: copy constructor

ArrayAdapter(ArrayAdapter<T> &&adapter)¶: move constructor

ArrayAdapter<T> &operator=(const ArrayAdapter<T> &adapter)¶: copy assignment

ArrayAdapter<T> &operator=(ArrayAdapter<T> &&adapter)¶: move assignment

Functions¶

`current_library_version()`¶

Version hdf5::current_library_version()¶

returns the current version of the HDF5 library

Throws: std::runtime_error – in case of a failure
Returns: instance of Version with the current HDF5 version

Namespace `hdf5`¶

Classes¶

`ObjectHandle`¶

`Path`¶

`IteratorConfig`¶

`Version`¶

`ObjectId`¶

`Context`¶

`IOWriteBuffer`¶

`IOReadBuffer`¶

`FixedLengthStringBuffer`¶

`Iterator`¶

`ArrayAdapter`¶

Functions¶

`current_library_version()`¶

Table of Contents

Previous topic

Next topic

Versions

Namespace hdf5¶

Classes¶

ObjectHandle¶

Path¶

IteratorConfig¶

Version¶

ObjectId¶

Context¶

IOWriteBuffer¶

IOReadBuffer¶

FixedLengthStringBuffer¶

Iterator¶

ArrayAdapter¶

Functions¶

current_library_version()¶

Namespace `hdf5`¶

`ObjectHandle`¶

`Path`¶

`IteratorConfig`¶

`Version`¶

`ObjectId`¶

`Context`¶

`IOWriteBuffer`¶

`IOReadBuffer`¶

`FixedLengthStringBuffer`¶

`Iterator`¶

`ArrayAdapter`¶

`current_library_version()`¶