Namespace `hdf5::node`¶

Classes¶

`Node`¶

class Node¶

Subclassed by hdf5::node::Dataset, hdf5::node::Group

Public Functions

Node(ObjectHandle &&handle, const Link &link)¶

constructor

Parameters

handle – rvalue reference to a handle instance
link – the path to the node

Node()¶

default constructor

In order to store objects in a container like a std::vector they must be default constructible. A default constructed object cannot be used for anything. Use the is_valid() function to check whether or not a Node instance refers to a valid HDF5 object or not.

See also

is_valid()

Node(const Node&)¶

copy constructor

We use the default implementation

Node &operator=(const Node &node)¶: copy assignment

virtual ~Node()¶

destructor

Must be virtual as we want to derive child classes from here.

NodeType type() const¶: return the node type

ObjectId id() const¶

get unique ID

Return the unique ID of an object. This identifier must not be confused with an HDF5 handle (called hid_t in the C-API. This ID identifies an object uniquely within a program context.

Returns: instance of ObjectId

bool is_valid() const¶

true if an object is valid

See also

Node()

void close()¶

close the node

Closes the node object and renders the node instance as invalid.

const Link &link() const¶

return link to object

This returns the link which was used to access the node.

Public Members

attribute::AttributeManager attributes¶: access to the attribute manager

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

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

`Link`¶

class Link¶

an HDF5 link

Class representing a link to an object within an HDF5 file. In order to store links in a container they have to be default constructable. A default constructed link has the type LinkType::Error. Instead of a node type only the handle to the parent is stored. Thus, the parent can also be a File which would identify the link as the link to the root group.

Public Functions

Link(const file::File &file, const Path &parent_path, const std::string &link_name)¶

Construct a new Link object.

Parameters

file – reference to the file object the link is locate in
parent_path – path to the parent group for the link
link_name – the name of the link

Link() = default¶

default constructor

Leaves a link of type LinkType::Error.

Path path() const¶

get path of the link

Return the actual path of the link in the file. This is basically the path of the parent group with the name of the link as a top element.

LinkTarget target(const property::LinkAccessList &lapl = property::LinkAccessList()) const¶

path to reference object

Return the path to the object which is reference by this link.

LinkType type(const property::LinkAccessList &lapl = property::LinkAccessList()) const¶: get type of link

Group parent() const¶

get reference to parent group

Return a const reference to the parent group of the link.

Node operator*() const¶

get the node that the link references

Return an instance to the node referenced by this particular link.

Pre: all intermediate links exist and the final link must be resolvable.

bool exists() const¶: returns true if the given link exists

bool is_resolvable() const¶: returns true if the object reference by the link exists

Friends

friend bool operator==(const Link &lhs, const Link &rhs)¶

equality operator for links

Two links are considered equal under the following conditions

they both share the same parent file
their parent paths are equal
their names are equal

Parameters

lhs – left hanside of the operator
rhs – right handside of the operator

Returns

true if the links are equal, false otherwise

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

std::ostream &hdf5::node::operator<<(std::ostream &stream, const Link &link)¶

`LinkTarget`¶

class LinkTarget¶

link target descriptor

This class describes the target a link references. It consists of two parts

the path to the object
the path to the file within which the object is stored

The latter one is required in order to handle external links where the object is not stored in the same file.

Public Functions

LinkTarget()¶: default constructor

explicit LinkTarget(const hdf5::Path &object_path)¶

constructor

Could be used mainly for internal hard or soft links. Its only argument is the path to the object within the file.

Parameters: object_path – path to object within the file

explicit LinkTarget(const hdf5::Path &object_path, const fs::path &file_path)¶

constructor

Could be used for external links.

Parameters

object_path – path to the object within the file
file_path – path to the file within which the object is stored

fs::path file_path() const¶

get file path

Return the path to the file where the link target is located.

hdf5::Path object_path() const¶

get object path

Return the object path to the link target within its file.

`Group`¶

class Group : public hdf5::node::Node ¶

Public Functions

Group()¶

default constructor

Does nothing else than calling the default constructor of Node and leaves in valid HDF5 object.

Group(const Group &group)¶: copy constructor

Group(const Node &node)¶

constructor

Construct an instance of Group from a generic Node class.

Throws: std::runtime_error – in case of a failure

Group(const Group &parent, const Path &path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::GroupCreationList &gcpl = property::GroupCreationList(), const property::GroupAccessList &gapl = property::GroupAccessList())¶

constructor

Parameters

parent – reference to the parent group of the new group
path – the path to the new group
lcpl – reference to the link creation property list
gcpl – reference to the group creation property list
gapl – reference to the group access property list

Group &operator=(const Group &group)¶: copy assignment operator

void flush() const¶

flush the group (since hdf5 1.10.0)

Throws: std::runtime_error – in case of a failure)

inline IteratorConfig &iterator_config() noexcept¶

get reference to the iterator configuration

Return a non-const reference to the iterator configuration for the group.

Returns: reference to iterator configuration

inline const IteratorConfig &iterator_config() const noexcept¶

get reference to the interator configuration

Return a const reference to the iterator configuration of the gruop.

Returns: reference to iterator configuration

bool exists(const std::string &name, const property::LinkAccessList &lapl = property::LinkAccessList()) const¶

checks existence of a node

The name must be a valid link and valid child name. This function checks whether a link of a particular name exists and can be resolved into an object.

Group create_group(const std::string &name, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::GroupCreationList &gcpl = property::GroupCreationList(), const property::GroupAccessList &gapl = property::GroupAccessList()) const¶: create a new group

Dataset create_dataset(const std::string &name, const datatype::Datatype &type, const dataspace::Dataspace &space, const property::DatasetCreationList &dcpl = property::DatasetCreationList(), const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::DatasetAccessList &dapl = property::DatasetAccessList()) const¶: create a new dataset

Node operator[](const Path &path) const¶

get node

Retrieves node from group at specified path. Path can be relative or absolute.

Parameters: path – path to node
Throws: std::runtime_error – in case of a failure
Returns: returns node if the link can be resolved

void create_link(const Path &link_path, const fs::path &target_file, const Path &target_path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

Create an external link.

Create an external link to an object stored in a different file. The target object is determined by the target file and an absolute path within this file. If link_path is a relative path the new link will be relative to the link_base group. Otherwise link_base is only used to determine the root group (and thus the file within which the link is placed).

Throws

std::runtime_error – in case of a failure

Parameters

link_path – absolute or relative path to the new link
target_file – the file where the link target is stored
target_path – absolute path to the object which we want to reference in the target file
lcpl – optional link creation property list
lapl – optional link access property list

Pre

target_path must be an absolute path

void create_link(const Path &link_path, const Path &target_path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

Create a soft link.

Create a soft link to an object stored in the same file. If link_path is a relative path the new link will be relative to the link_base group.

Throws

std::runtime_error – in case of a failure

Parameters

link_path – absolute or relative path to the new link
target_path – absolute path to the object which we want to reference in the target file
lcpl – optional link creation property list
lapl – optional link access property list

Pre

target_path must be an absolute path

void create_link(const Path &link_path, const Node &target, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

Create a soft or external link.

Create a link from link_path to target object. A soft link will be created if group and target_base reside in the same file. Otherwise an external link is created.

The target for the link is determined by target_base and target_path. If the latter one is a relative path the target location is assumed relative to target_base. If it is an absolute path, target_base is used to retrieve the root group of the specific file.

Parameters

link_path – path to the new link (either relative or absolute)
target – the target node
lcpl – optional link creation property list
lapl – optional link access property list

void copy_here(const Path &link_path, const Node &target, const property::ObjectCopyList &ocpl = property::ObjectCopyList(), const property::LinkCreationList &lcpl = property::LinkCreationList())¶

copy node object

Copy target object to a new link_path within this Group. If an object of same name already exists an exception will be thrown.

The copy operation should also work across file boundaries. In all cases the source object as well as the destination group must exist.

Parameters

link_path – the destination relative path under the this group
target – object to be copied
ocpl – optional object copy property list
lcpl – optional link creation property list

Throws

std::runtime_error – in case of a failure

void copy_here(const Node &target, const property::ObjectCopyList &ocpl = property::ObjectCopyList(), const property::LinkCreationList &lcpl = property::LinkCreationList())¶

copy node object

Copy target object to a new location under this Group using the original object’s name. If an object of same name already exists an exception will be thrown.

The copy operation should also work across file boundaries. In all cases the source object as well as the destination group must exist.

Parameters

target – object to be copied
ocpl – optional object copy property list
lcpl – optional link creation property list

Throws

std::runtime_error – in case of a failure

void move_here(const Path &link_path, const Node &target, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

move node object

Move target object to a new link_path under this Group. If an object of same name already exists an exception will be thrown.

See also

copy for the naming convention

Parameters

link_path – the destination relative path under the this group
target – object to be moved
lcpl – optional link creation property list
lapl – optional link access property list

Throws

std::runtime_error – in case of a failure

void move_here(const Node &target, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

move node object

Move target object to a new location under this Group using the original object’s name. If an object of same name already exists an exception will be thrown.

Parameters

target – object to be moved
lcpl – optional link creation property list
lapl – optional link access property list

Throws

std::runtime_error – in case of a failure

void remove(const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList())¶

remove node from group

Remove link at path within this Group.

See also

remove(const Node &base, const Path &object_path)

Throws

std::runtime_error – in case of a failure

Parameters

path – path of object to remove
lapl – optional link access property list

bool has_group(const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList()) const noexcept¶

reports if group has a link to a valid group at specified path

Parameters

path – path to group
lapl – optional link access property list

Returns

true if the group has a group, false otherwise

bool has_dataset(const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList()) const noexcept¶

reports if group has a link to a valid dataset at specified path

Parameters

path – path to dataset
lapl – optional link access property list

Returns

true if the group has a dataset, false otherwise

Group get_group(const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList()) const¶

get group

A convenience function for get_node. Returns a Group instance if the node referenced by path is a group, otherwise throws an exception. Use this function whenever you want to work with a Group temporarily.

For instance

Group root = file.root();
if(root.get_group("run_01/sensors").nodes.size()!=0)
{

}

See also

get_node

See also

get_dataset

Throws

std::runtime_error – in case of a failure

Parameters

path – path to group
lapl – optional link access property list

Returns

new Group instance

Dataset get_dataset(const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList()) const¶

get dataset

A convenience function for get_node. Returns a Dataset instance if the node referenced by path is a dataset, otherwise throws an exception. Use this function whenever you want to work with a Dataset temporarily.

For instance

Group root = file.root();
Dataspace space = root.get_dataset("run_01/sensors/temperature").dataspace();

See also

get_node

See also

get_dataset

Throws

std::runtime_error – in case of a failure

Parameters

path – path to dataset
lapl – optional link access property list

Returns

new Group instance

`GroupView`¶

class GroupView¶

base class for group views

This is the base class for all views on a group. Views provide an STL compliant read only interface to links and nodes stored below a group.

Subclassed by hdf5::node::LinkView, hdf5::node::NodeView

Public Functions

GroupView(Group &parent_group)¶

constructor

Parameters: parent_group – reference to the parent group

size_t size() const¶

get number of links

Return the number of links attached to a group.

Returns: number of link

inline const Group &group() const noexcept¶

return reference to the parent group

Returns a reference to the group this very view belongs to.

Returns: reference to group

`NodeView`¶

class NodeView : public hdf5::node::GroupView ¶

Public Functions

bool exists(const std::string &name, const property::LinkAccessList &lapl = property::LinkAccessList()) const¶

checks existence of a node

The name must be a valid child name (not a path). This function checks whether a link of a particular name can be resolved into an object.

Node operator[](const std::string &name) const¶

get object by name

Here the index is the name of the child node. A name can contain any character but the ‘.’, ‘..’ and ‘/’. Thus, unlike in the C-API we cannot access object relative to the group a view belongs to but only its direct children. This emphasizes the notion of an associative container which is connected with a gruop.

Throws: std::runtime_error – in case of a failure
Parameters: name – the name of the child to access
Returns: instance of Node

class NodeIterator : public hdf5::Iterator ¶

bidirectional NodeIterator

This iterator iterates over the direct children (nodes) of a group. It is a full random access iterator using the index access methods provided by the NodeView interface.

The interface follows the C++ specification for bidirectional constant iterators. See C++ reference on iterators for details.

Public Functions

NodeIterator() = delete¶

default constructor

Not requried, thus deleted.

Public Static Functions

static NodeIterator begin(const Group &group)¶

get iterator to first element

Static factory function returning an iterator to the first child of a group.

Parameters: group – reference to the group over which to iterate
Returns: instance of NodeIterator

static NodeIterator end(const Group &group)¶

get iterator to last+1 element

Static factory function returning an iterator to the last+1 child of the given group.

Parameters: group – reference to the group over which to iterate
Returns: instance of NodeIterator

class RecursiveNodeIterator¶

recursive node iterator

Iterator which recursively iterates over all subelements of a particular group. All relevant constructors are private. To construct an instance of this iterator use the two static factory functions begin() and end().

Group top = ...;
auto iter = RecursiveNodeIterator::begin(top);
auto end  = RecursiveNodeIterator::end(top);

while(iter != end)
{
  //do something here
  ++iter;
}
// or with STL

std::for_each(RecursiveNodeIterator::begin(top),
              RecursiveNodeIterator::end(top),
              [](const Node &node) { ...do something ... ; });

Unlike NodeIterator, RecursiveNodeIterator is a simple forward iterator.

Public Functions

RecursiveNodeIterator() = delete¶

default constructor

There is no default constructors -> would not make too much sense.

Node operator*() const¶

return current Node instance

Returns an instance of the actual node the iterator refers to.

Returns: instance of node::Node

Node *operator->()¶

return address of the actual Node instance

Returns the adress of the actual node in memory.

Returns: adress of current Node

RecursiveNodeIterator &operator++()¶

advance to next element

Advances to the next element in line.

RecursiveNodeIterator iter = ...;
while(...)
{
  ++iter;
}

Returns: reference to the udpated iterator

RecursiveNodeIterator operator++(int)¶

advance to next element

Advances to the next element in line but returns an iterator to the previous element.

RecursiveNodeIterator iter = ...;

while(...)
{
  Node n = *iter++; //give me the actual node and advance
  std::cout<<n.link().path()<<std::endl;
}

Returns: instance of RecursiveNodeIterator

Public Static Functions

static RecursiveNodeIterator begin(const Group &current_group)¶

create iterator to the first element

Static factory function returning an instance of RecursiveForwardIterator on the first element of the top group.

Parameters: current_group – the top level group where to start with recursive iteration
Returns: instance of RecursiveNodeIterator

static RecursiveNodeIterator end(const Group &current_group)¶

create iterator to the last+1 element

Static factory function returning an instance of RecursiveForwardIterator on the last+1 element of top group.

Parameters: current_group – the top level group at which to start the recursive iteration.
Returns: instance of RecursiveNodeIterator

`LinkView`¶

class LinkView : public hdf5::node::GroupView ¶

Public Functions

bool exists(const std::string &name, const property::LinkAccessList &lapl = property::LinkAccessList()) const¶

checks existence of a link

The name must be a valid link. This function checks whether a link of a particular name exists.

class LinkIterator : public hdf5::Iterator ¶

class RecursiveLinkIterator¶

recursive Link iterator

Iterator which recursively iterates over all Links of a particular group. All relevant constructors are private. To construct an instance of this iterator use the two static factory functions begin() and end().

Group top = ...;
auto iter = RecursiveLinkIterator::begin(top);
auto end  = RecursiveLinkIterator::end(top);

while(iter != end)
{
  //do something here
  ++iter;
}
// or with STL

std::for_each(RecursiveLinkIterator::begin(top),
              RecursiveLinkIterator::end(top),
              [](const Link &link) { ...do something ... ; });

Unlike LinkIterator, RecursiveLinkIterator is a simple forward iterator.

Public Functions

RecursiveLinkIterator() = delete¶

default constructor

There is no default constructors -> would not make too much sense.

Public Static Functions

static RecursiveLinkIterator begin(const Group &current_group)¶

create iterator to the first element

Static factory function returning an instance of RecursiveLinkIterator on the first element of the top group.

Parameters: current_group – the top level group where to start with recursive iteration
Returns: instance of RecursiveLinkIterator

static RecursiveLinkIterator end(const Group &current_group)¶

create iterator to the last+1 element

Static factory function returning an instance of RecursiveLinkIterator on the last+1 element of top group.

Parameters: current_group – the top level group at which to start the recursive iteration.
Returns: instance of RecursiveLinkIterator

`Dataset`¶

class Dataset : public hdf5::node::Node ¶

Subclassed by hdf5::node::ChunkedDataset, hdf5::node::VirtualDataset

Public Functions

Dataset() = default¶

default constructor

Use default implementation here. We need this for some STL containers. After default construction the dataset is in an invalid state.

See also

is_valid()

Dataset(const Node &node)¶

construct

Construct a dataset from a node instance.

Throws: std::runtime_error – in case that the node is not a dataset
Parameters: node – reference to the original node from which to construct the dataset.

Dataset(const Group &base, const Path &path, const datatype::Datatype &type, const dataspace::Dataspace &space = dataspace::Scalar(), const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::DatasetCreationList &dcpl = property::DatasetCreationList(), const property::DatasetAccessList &dapl = property::DatasetAccessList())¶

constructor

Throws

std::runtime_error – in case of a failure

Parameters

base – the base object for the dataset creation
path – the path to the new dataset
type – optional reference to a datatype
space – optional reference to a dataspace (default is a scalar one)
lcpl – optional reference to a link creation property list
dcpl – optional reference to a dataset creation property list
dapl – optional reference to a dataset access property list

dataspace::Dataspace dataspace() const¶

get dataspace of dataset

Return a new instance of the dataspace describing the dataset.

Throws: std::runtime_error – in case of a failure
Returns: new dataspace instance

property::DatasetCreationList creation_list() const¶

get the dataset creation property list used for creation

Returns an instance of a dataset creation property list with the values used for the creation of the dataset.

Throws: std::runtime_error – in case of a failure
Returns: instance of DatasetCreationList

property::DatasetAccessList access_list() const¶

get the dataset access property list for the instance

Returns an instance of the dataset access property list for the dataset.

Throws: std::runtime_error – in case of a failure
Returns: instance of DatasetAccessList

datatype::Datatype datatype() const¶

get datatype of dataset

Return an instance of the datatype describing the elements stored in the file.

Throws: std::runtime_error – in case of a failure
Returns: new instance of datatype

void extent(const Dimensions &dims) const¶

set extent of the dataset

Allows to change the extent (number of elements along each dimensions) of a dataset. It is important to note that in such a case a previously requested dataspace though remaining a valid object does no longer describe the datasets layout correctly. The number of elements can be increased or decreased within the limits of the dataspace originally used to create the dataset.

Deprecated:: this method is deprecated - use resize instead

Throws: std::runtime_error – in case of a failure
Parameters: dims – vector with new number of elements along each dimension

void resize(const Dimensions &dims) const¶

resize the dataset

Allows to change the shape (number of elements along each dimensions) of a dataset. It is important to note that in such a case a previously requested dataspace though remaining a valid object does no longer describe the datasets layout correctly. The number of elements can be increased or decreased within the limits of the dataspace originally used to create the dataset.

Throws: std::runtime_error – in case of a failure
Parameters: dims – vector with new number of elements along each dimension

void refresh() const¶

refresh the dataset (since hdf5 1.10.0)

Throws: std::runtime_error – in case of a failure

template<typename T> void write(const T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, const dataspace::Dataspace &file_space, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

write data to the dataset

This template function a very simple wrapper around the original HDF5 C-API function. The major difference is that a type trait is used to obtain a pointer to the data passed as the first argument. This template is provided for maximum flexibility as it allows virtually to do everything which could be done with the C-API.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – type from which to write data

Parameters

data – const reference to the data source
mem_type – reference to the memory data type
mem_space – reference to the memory data space
file_space – reference to the dataspace in the file
dtpl – data transfer property list

template<typename T> void write(const T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

write data to the dataset

This function allows specification of the memory dataspace and dataspace and optionally the dataset transfer property list.

template<typename T> void read(T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, const dataspace::Dataspace &file_space, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

read data from the dataset

This template function a very simple wrapper around the original HDF5 C-API function. The major difference is that a type trait is used to obtain a pointer to the data passed as the first argument. This template is provided for maximum flexibility as it allows virtually to do everything which could be done with the C-API.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – type from which to write data

Parameters

data – const reference to the data source
mem_type – reference to the memory data type
mem_space – reference to the memory data space
file_space – reference to the dataspace in the file
dtpl – data transfer property list

template<typename T> void write(const T &data, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get())¶

write entire dataset

Write the entire dataset from an instance of T.

Throws

std::runtime_error – in caes of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T
dtpl – reference to a dataset transfer property list

template<typename T> void write_reshape(const T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

write entire dataset

Write the entire dataset from an instance of T. It reshapes the mem_space if its rank does not match to the selection rank

Throws

std::runtime_error – in caes of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T
mem_type – reference to the memory data type
mem_space – reference to the memory data space
dtpl – reference to a dataset transfer property list

void write(const char *data, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get())¶

write entire dataset

Write the entire dataset from an instance of const char *

Throws

std::runtime_error – in caes of a failure

Parameters

data – pointer to the source instance of const char *
dtpl – reference to a dataset transfer property list

template<typename T> void write_chunk(const T &data, std::vector<hsize_t> offset, std::uint32_t filter_mask = 0, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get())¶

write dataset chunk

Write a dataset chunk from an instance of T.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T
offset – logical position of the first element of the chunk in the dataset’s dataspace
filter_mask – mask of which filters are used with the chunk
dtpl – reference to a dataset transfer property list

template<typename T> void write_chunk(const T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, std::vector<hsize_t> &offset, std::uint32_t filter_mask = 0, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

write dataset chunk

Write a dataset chunk from an instance of T.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T
mem_type – reference to the memory data type
mem_space – reference to the memory data space
offset – logical position of the first element of the chunk in the dataset’s dataspace
filter_mask – mask of which filters are used with the chunk
dtpl – reference to a dataset transfer property list

template<typename T> std::uint32_t read_chunk(T &data, std::vector<hsize_t> offset, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

read dataset chunk (since hdf5 1.10.2)

Read a chunk from a dataset to an instance of T.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T
offset – logical position of the first element of the chunk in the dataset’s dataspace
dtpl – reference to a dataset transfer property list

Returns

filter_mask mask of which filters are used with the chunk

template<typename T> std::uint32_t read_chunk(T &data, const datatype::Datatype &mem_type, std::vector<hsize_t> &offset, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

read dataset chunk

Read a chunk from a dataset to an instance of T.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T
mem_type – reference to the memory data type
offset – logical position of the first element of the chunk in the dataset’s dataspace
dtpl – reference to a dataset transfer property list

Returns

filter_mask mask of which filters are used with the chunk

hsize_t chunk_storage_size(std::vector<hsize_t> offset) const¶

read dataset chunk

Read a chunk storage size from a dataset to an instance of T.

Throws: std::runtime_error – in case of a failure
Parameters: offset – logical position of the first element of the chunk in the dataset’s dataspace
Returns: the size in bytes for the chunk.

template<typename T> void read(T &data, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get())¶

read entire dataset

Read the entire data from a dataset to an instance of T.

Throws

std::runtime_error – in case of a failre

Template Parameters

T – destination type

Parameters

data – reference to the destination
dtpl – reference to a dataset transfer property list

template<typename T> void write(const T &data, const dataspace::Selection &selection, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get())¶

write data to a selection

Write data from an instance of T to a selection of the dataset.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – type of the source

Parameters

data – reference to the source
selection – reference to the selection
dtpl – reference to a dataset transfer property list

template<typename T> void write_reshape(const T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, const dataspace::Selection &selection, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

write data to a selection

Write data from an instance of T to a selection of the dataset. It reshapes the mem_space if its rank does not match to the selection rank

Throws

std::runtime_error – in case of a failure

Template Parameters

T – type of the source

Parameters

data – reference to the source
mem_type – reference to the memory data type
mem_space – reference to the memory data space
selection – reference to the selection
dtpl – reference to a dataset transfer property list

template<typename T> void read(T &data, const dataspace::Selection &selection, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get())¶

reading data from a selection

Reading data to an instance of T from a selection of a dataset. It reshapes the mem_space if its rank does not match to the selection rank

Throws

std::runtime_error – in case of a failure

Template Parameters

T – type of the destination object

Parameters

data – reference to the destination object
selection – reference to the selection
dtpl – reference to a dataset transfer property list

template<typename T> void read_reshape(T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space, const dataspace::Selection &selection, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

reading data from a selection

Reading data to an instance of T from a selection of a dataset. This template method tries to deduce the memory type and memory space for the target type (where to write the data to) automatically using the appropriate type traits.

Throws

std::runtime_error – in case of a failure

Template Parameters

T – type of the destination object

Parameters

data – reference to the destination object
mem_type – reference to the memory data type
mem_space – reference to the memory data space
selection – reference to the selection
dtpl – reference to a dataset transfer property list

template<typename T> void read(T &data, const datatype::Datatype &memory_type, const dataspace::Dataspace &memory_space, const dataspace::Selection &file_selection, const property::DatasetTransferList &dtpl = property::DatasetTransferList::get()) const¶

reading data from a dataset

Throws

std::runtime_error – in case of a failure

Parameters

data – reference to the target to which to read the data
memory_type – reference to the memory data type of the target
memory_space – reference to the memory data space of the target
file_selection – reference to the selection for the file dataspace
dtpl – optional reference to a dataset transfer property list

filter::ExternalFilters filters() const¶

get the dataset external filters for the instance

Returns an instance of the dataset external filters for the dataset.

Throws: std::runtime_error – in case of a failure
Returns: instance of ExternalFilters

`ChunkedDataset`¶

class ChunkedDataset : public hdf5::node::Dataset ¶

dataset with chunked layout

This class provides an convenient interface to a chunked dataset. As a matter of fact the only thing added here is a convenient constructor where the chunk shape can be passed as an additional argument.

Public Functions

ChunkedDataset() = default¶

default constructor

Required for STL compliance. We can use the compiler provided default implementation here.

ChunkedDataset(const ChunkedDataset&) = default¶

copy constructor

Required for STL compliance. We can use the compiler provided default implementation here.

ChunkedDataset(const Group &base, const Path &path, const datatype::Datatype &type, const dataspace::Simple &space, const Dimensions &chunk_shape, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::DatasetCreationList &dcpl = property::DatasetCreationList(), const property::DatasetAccessList &dapl = property::DatasetAccessList())¶

constructor

As for all dataset constructors, references to the required property list can be passed as optional arguments. There are two things worth noting here

the dataspace for a chunked dataset must be a simple dataspace
independent of the configuration of an eventually user provided dataset creation property list, the layout of the dataset will be chunked with the provided chunk shape.

The user provided dataset creation property list will not be changed.

Throws

std::runtime_error – in case of a failure

Parameters

base – the base object for the dataset creation
path – the path to the new dataset
type – optional reference to a datatype
space – optional reference to a dataspace
chunk_shape – reference to the chunk shape
lcpl – optional reference to a link creation property list
dcpl – optional reference to a dataset creation property list
dapl – optional reference to a dataset access property list

`VirtualDataset`¶

class VirtualDataset : public hdf5::node::Dataset ¶

virtual dataset class

This class provides a special constructor which only takes arguments required to construct a virtual dataset.

Public Functions

VirtualDataset() = default¶

default constructor

This constructor is required for compatibility with STL containers. We can use the compiler provided version.

VirtualDataset(const VirtualDataset&) = default¶

copy constructor

This constructor is required for compatibility with STL containers. We can use the compiler provided version here.

VirtualDataset(const Group &base, const Path &path, const datatype::Datatype &type, const dataspace::Dataspace &space, const property::VirtualDataMaps &vds_maps, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::DatasetCreationList &dcpl = property::DatasetCreationList(), const property::DatasetAccessList &dapl = property::DatasetAccessList())¶: constructor

Functions¶

`copy()`¶

void hdf5::node::copy(const Node &source, const Group &destination, const property::ObjectCopyList &ocpl = property::ObjectCopyList(), const property::LinkCreationList &lcpl = property::LinkCreationList())¶

copy node object

Copy source object to a new location under destination Group using the original object’s name. For instance, if we have

source path /detector/data
destination path /recorded/detectors

then the copy will appear as /recorded/detectors/data. If an object of same name already exists an exception will be thrown.

The copy operation should also work across file boundaries. In all cases the source object as well as the destination group must exist.

Parameters

source – object to be copied
destination – the destination group where the new copy will be stored
ocpl – optional object copy property list
lcpl – optional link creation property list

Throws

std::runtime_error – in case of a failure

`move()`¶

void hdf5::node::move(const Node &source, const Group &base, const Path &relative_path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

move node object

Move source object to a new relative_path under base Group. If an object of same name already exists an exception will be thrown. In all cases the source object as well as the destination group must exist.

Parameters

source – object to be moved
base – the destination base group where the object will be moved
relative_path – the destination relative path under the base group
lcpl – optional link creation property list
lapl – optional link access property list

Throws

std::runtime_error – in case of a failure

void hdf5::node::move(const Node &source, const Group &destination, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

move node object

Move source object to a new location under destination Group using the original object’s name. For instance, if we have

source path /detector/data
destination path /recorded/detectors

then the moved object will appear as /recorded/detectors/data. If an object of same name already exists an exception will be thrown. In all cases the source object as well as the destination group must exist.

Parameters

source – object to be moved
destination – the new group where the object should be located
lcpl – optional link creation property list
lapl – optional link access property list

Throws

std::runtime_error – in case of a failure

`remove()`¶

void hdf5::node::remove(const Node &object, const property::LinkAccessList &lapl = property::LinkAccessList())¶

remove node from group

Removes link to object from parent Group via which it was accessed.

See also

remove(const Node &base, const Path &object_path)

Throws

std::runtime_error – in case of a failure

Parameters

object – the object which to remove
lapl – optional link access property list

Pre

object must be a valid HDF5 object instance

void hdf5::node::remove(const Group &base, const Path &object_path, const property::LinkAccessList &lapl = property::LinkAccessList())¶

remove node from group

Removes link at object_path within the base Group. If there are more references (links) to this particular object, they remain active. Additionally: removing an object entirely from an HDF5 file means removing all links to this object and thus rendering it inaccessible. No storage space in the file will be cleared. In order to reduce the size of the file h5repack must be used which will simply not copy objects which cannot be referenced.

Throws

std::runtime_error – in case of a failure

Parameters

base – group relative to which the link or object resides
object_path – path relative to base determining the link or object to remove
lapl – optional link access property list

`link()`¶

void hdf5::node::link(const Node &target, const Group &link_base, const Path &link_path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

Create a soft or external link.

Create a link from link_path under link_base to object at target_path under target_base. A soft link will be created if link_base and target_base reside in the same file. Otherwise an external link is created.

The target for the link is determined by target_base and target_path. If the latter one is a relative path the target location is assumed relative to target_base. If it is an absolute path, target_base is used to retrieve the root group of the specific file.

Parameters

target – the target node (could also be path here?)
link_base – the base group for the link location
link_path – path to the new link (either relative or absolute)
lcpl – optional link creation property list
lapl – optional link access property list

void hdf5::node::link(const Path &target_path, const Group &link_base, const Path &link_path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

Create a soft link.

Create a link from link_path under link_base to object at target_path. The object at target_path need not already exist at this time.

If the target_path is a relative path the target location is assumed relative to link_base. If absolute, the path is assumed to be on the same file as link_base.

Parameters

target_path – the target node (could also be path here?)
link_base – the base group for the link location
link_path – path to the new link (either relative or absolute)
lcpl – optional link creation property list
lapl – optional link access property list

void hdf5::node::link(const fs::path &target_file, const Path &target_path, const Group &link_base, const Path &link_path, const property::LinkCreationList &lcpl = property::LinkCreationList(), const property::LinkAccessList &lapl = property::LinkAccessList())¶

Create an external link.

Create an external link to an object stored in a different file. The target object is determined by the target file and an absolute path within this file. The location of the link is given by a base group and a relative or absolute path. If link_path is a relative path the new link will be relative to link_base. Otherwise link_base is only used to determine the root group (and thus the file within which the link is placed).

Throws

std::runtime_error – in case of a failure

Parameters

target_file – the file where the link target is stored
target_path – absolute path to the object which we want to reference in the target file
link_base – base group for the link
link_path – absolute or relative path to the new link
lcpl – optional link creation property list
lapl – optional link access property list

Pre

target_path must be an absolute path

Pre

link_base must be a valid HDF5 object

`get_node()`¶

Node hdf5::node::get_node(const Group &base, const Path &node_path, const property::LinkAccessList &lapl = property::LinkAccessList())¶

get node

Get a node from a base group.

Throws

std::runtime_error – in case of a failure

Parameters

base – reference to the base group
node_path – reference to the path of the node
lapl – optional link access property list

Returns

new node instance

`get_real_base()`¶

Group hdf5::node::get_real_base(const Group &base, const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList())¶

get real base of path

Helper function to facilitate a number of convenience functions in the wrapper. Gets the most proximate parent Group of path. If path is absolute, base will only be used to obtain the root node of the file. If the parent node does not exist or is not a Group, an exception will be thrown.

Throws

std::runtime_error – in case of a failure

Parameters

base – base group for link
path – path of desired node
lapl – optional link access property list

Returns

most recent parent Group of path

`get_group()`¶

Group hdf5::node::get_group(const Group &base, const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList())¶

get group

A convenience function for get_node. Returns a Group instance if the node referenced by path is a group, otherwise throws an exception. Use this function whenever you want to work with a Group temporarily.

For instance

Group root = file.root();
if(get_group(root,"run_01/sensors").nodes.size()!=0)
{

}

See also

get_node

See also

get_dataset

Throws

std::runtime_error – in case of a failure

Parameters

base – base group
path – path to group
lapl – optional link access property list

Returns

new Group instance

`get_dataset()`¶

Dataset hdf5::node::get_dataset(const Group &base, const Path &path, const property::LinkAccessList &lapl = property::LinkAccessList())¶

get dataset

A convenience function for get_node. Returns a Dataset instance if the node referenced by path is a dataset, otherwise throws an exception. Use this function whenever you want to work with a Dataset temporarily.

For instance

Group root = file.root();
Dataspace space = get_dataset(root,"run_01/sensors/temperature").dataspace();

See also

get_node

See also

get_dataset

Throws

std::runtime_error – in case of a failure

Parameters

base – base group
path – path to dataset
lapl – optional link access property list

Returns

new Group instance

`is_group()`¶

bool hdf5::node::is_group(const Node &node)¶

predicate function returning true if node is a group

This predicate function is used to filter group nodes. A typical application would be for instance

std::vector<Group> groups;
std::copy_if(root.nodes.begin(),root.nodes.end(),std::back_inserter(groups),is_group);

or whenever you want to partition a vector

std::vector<Node> nodes;
std::copy(root.nodes.begin(),root.nodes.end(),std::back_inserter(nodes));
auto first_dset = std::partition_by(nodes.begin(),nodes.end(),is_group);

Throws: std::runtime_error – in case of a failure
Parameters: node – reference to the node
Returns: true if the node is a group, false otherwise

`is_dataset()`¶

bool hdf5::node::is_dataset(const Node &node)¶

predicate function returning true if a node is a dataset

This predicate function is used to filter dataset nodes. A typical application would be for instance

std::vector<Dataset> datasets;
std::copy_if(root.nodes.begin(),root.nodes.end(),std::back_inserter(datasets),is_dataset);

or whenever you want to partition a vector

std::vector<Nodes> nodes;
std::copy(root.nodes.begin(),root.nodes.end(),std::back_inserter(nodes));
auto first_group = std::partition_by(nodes.begin(),nodes.end(),is_dataset);

Throws: std::runtime_error – in case of a failure
Parameters: node – reference to the node
Returns: true if the node is a dataset, false otherwise

`resize_by()`¶

void hdf5::node::resize_by(const Dataset &dataset, size_t dimension_index, ssize_t delta)¶

resize a dataset by a particular offset

Resizes a dataset along the dimension determined by dimension_index by delta elements. As delta is a signed integer one can either enlarge or shrink the dataset.

Parameters

dataset – reference to the dataset to resize
dimension_index – the index of the dimension to resize
delta – the number of elements about which the dataset should be resized

Throws

std::runtime_error – in case of any failure

Enumerations¶

`NodeType`¶

enum class hdf5::node::NodeType : std::underlying_type<H5O_type_t>::type¶

enumeration for node type

Values:

enumerator Unknown¶

enumerator Group¶

enumerator Dataset¶

enumerator Datatype¶

std::ostream &hdf5::node::operator<<(std::ostream &stream, const NodeType &type)¶

output stream operator for the NodeType enumeration

This operator writes a text representation of the node type to the output stream.

Parameters

stream – reference to the output stream
type – the actual type to write to the stream

Returns

modified output stream

`LinkType`¶

enum class hdf5::node::LinkType : std::underlying_type<H5L_type_t>::type¶

link type enumeration

Enumeration type to distinguish the various link types in HDF5.

Values:

enumerator Hard¶

enumerator Soft¶

enumerator External¶

enumerator Error¶

std::ostream &hdf5::node::operator<<(std::ostream &stream, const LinkType &type)¶

output stream operator for the link type enumeration

This operator writes a textual representation of the link type to the output stream.

Parameters

stream – refernce to the output stream
type – reference to the link type

Returns

modified output stream

Namespace `hdf5::node`¶

Classes¶

`Node`¶

`Link`¶

`LinkTarget`¶

`Group`¶

`GroupView`¶

`NodeView`¶

`LinkView`¶

`Dataset`¶

`ChunkedDataset`¶

`VirtualDataset`¶

Functions¶

`copy()`¶

`move()`¶

`remove()`¶

`link()`¶

`get_node()`¶

`get_real_base()`¶

`get_group()`¶

`get_dataset()`¶

`is_group()`¶

`is_dataset()`¶

`resize_by()`¶

Enumerations¶

`NodeType`¶

`LinkType`¶

Table of Contents

Previous topic

Next topic

Versions

Namespace hdf5::node¶

Classes¶

Node¶

Link¶

LinkTarget¶

Group¶

GroupView¶

NodeView¶

LinkView¶

Dataset¶

ChunkedDataset¶

VirtualDataset¶

Functions¶

copy()¶

move()¶

remove()¶

link()¶

get_node()¶

get_real_base()¶

get_group()¶

get_dataset()¶

is_group()¶

is_dataset()¶

resize_by()¶

Enumerations¶

NodeType¶

LinkType¶

Namespace `hdf5::node`¶

`Node`¶

`Link`¶

`LinkTarget`¶

`Group`¶

`GroupView`¶

`NodeView`¶

`LinkView`¶

`Dataset`¶

`ChunkedDataset`¶

`VirtualDataset`¶

`copy()`¶

`move()`¶

`remove()`¶

`link()`¶

`get_node()`¶

`get_real_base()`¶

`get_group()`¶

`get_dataset()`¶

`is_group()`¶

`is_dataset()`¶

`resize_by()`¶

`NodeType`¶

`LinkType`¶