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

DLL_EXPORT friend 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.

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 – the major version number
minor – 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

DLL_EXPORT 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: 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

DLL_EXPORT 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

DLL_EXPORT 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

DLL_EXPORT 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

DLL_EXPORT 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

DLL_EXPORT 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

DLL_EXPORT 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

boost::filesystem::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

Gets object info.

Namespace `hdf5`¶

`hdf5::Path`¶

`hdf5::IteratorConfig`¶

`hdf5::ObjectHandle`¶

`hdf5::Version`¶

`hdf5::ObjectId`¶

Table of Contents

Previous topic

Next topic

Versions

Namespace hdf5¶

hdf5::Path¶

hdf5::IteratorConfig¶

hdf5::ObjectHandle¶

hdf5::Version¶

hdf5::ObjectId¶

Namespace `hdf5`¶

`hdf5::Path`¶

`hdf5::IteratorConfig`¶

`hdf5::ObjectHandle`¶

`hdf5::Version`¶

`hdf5::ObjectId`¶