Namespace hdf5

hdf5::Path

class hdf5::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.

Unnamed Group

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_iterator end() 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

Unnamed Group

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

const_reverse_iterator rend() 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

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.

Path(const Path &p) = default

copy constructor

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.

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

Friends

friend bool operator==(const Path &lhs, const Path &rhs)

checks two paths for equality

Two paths are considered equal if each of their elements is

hdf5::IteratorConfig

class hdf5::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 hdf5::IterationOrder

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

enum hdf5::IterationIndex

iteration index

Values:

enumerator NAME

using the name as index

enumerator CREATION_ORDER

using creation time as index

hdf5::ObjectHandle

class hdf5::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 Functions

explicit ObjectHandle(hid_t id, Policy policy = Policy::WITH_WARD)

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",H5P_DEFAULT));
...

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

hdf5::Version

class hdf5::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

Version(const Version&) = default

copy constructor

We can use the compiler provided default implementation here as all members are trivially copyable.

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

Related

std::ostream &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.

See also

Version::to_string

Parameters

• stream – the stream where to write the version

• version – reference to the Version to write

Returns

modified version of std::ostream

bool operator==(const Version &lhs, const Version &rhs)

checks two version for equality

Two version are considered equal if all of their parts are equal.

Parameters

• lhs – reference to the left hand side version

• rhs – reference to the right hand side version

Returns

true if versions are equal, false otherwise

bool operator!=(const Version &lhs, const Version &rhs)

checks if two versions are not equal

Parameters

• lhs – reference to the left hand side version

• rhs – reference to the right hand side version

Returns

true if versions are not equal, false otherwise

bool operator<(const Version &lhs, const Version &rhs)

checks if the left version is strictly small than the right

Parameters

• lhs – reference to the left hand side version

• rhs – reference to the right hand side version

bool operator>=(const Version &lhs, const Version &rhs)

checks if the left version is bigger or equal than the right

Parameters

• lhs – reference to the left hand side version

• rhs – reference to the right hand side version

bool operator>(const Version &lhs, const Version &rhs)

checks if the left version is strictly bigger than the right

Parameters

• lhs – reference to the left hand side version

• rhs – reference to the right hand side version

Version 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

hdf5::ObjectId

class hdf5::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

ObjectId(const ObjectId &id) = default

copy constructor

We need this for compliance with STL containers. As all memebers of this class support copy construction and assignment we can safely use the default implementation, provided by the compiler, here.

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.