A handle to an HDF5 file object. More...

#include <file.hpp>

Public Types
using	native_handle_type = hdf5::precursor::file
	Type of the underlying HDF5 low-level handle.

Public Member Functions
	file ()=default
	Initializes the handle with its null state.

	file (const std::string &path, create_mode mode)
	Creates a new HDF5 file using the given path and creation mode. More...

	file (const std::string &path, open_mode mode)
	Opens a pre-existing HDF5 file using the given path and open mode. More...

group	create_group (const std::string &name)
	Creates a new HDF5 group within the root group. More...

dataset	create_dataset (const std::string &name, const type &datatype, const std::vector< hsize_t > &dims, const dataset_options &options={})
	Creates a new HDF5 dataset within the root group. More...

template<typename T >
dataset	create_dataset (const std::string &name, const std::vector< hsize_t > &dims, const dataset_options &options={})
	Creates a new HDF5 dataset within the root group. More...

scalar_dataset	create_scalar_dataset (const std::string &name, const type &datatype)
	Creates a new HDF5 scalar dataset within the root group. More...

template<typename T >
scalar_dataset	create_scalar_dataset (const std::string &name)
	Creates a new HDF5 scalar dataset within the root group. More...

template<typename T >
scalar_dataset	create_scalar_dataset (const std::string &name, const T &value)
	Creates a new HDF5 scalar dataset within the root group and initializes it with a given value. More...

object	operator[] (const std::string &name) const
	Accessor function for the root group. More...

void	remove (const std::string &name) const
	Removes the specified object from the root group. More...

group	require_group (const std::string &name)
	Returns the requested group, if it already exists, otherwise a new group is created. More...

dataset	require_dataset (const std::string &name, const type &datatype, const std::vector< hsize_t > &dims, const dataset_options &options={})
	Returns the requested dataset, if it already exists, otherwise a new dataset is created. More...

template<typename T >
dataset	require_dataset (const std::string &name, const std::vector< hsize_t > &dims, const dataset_options &options={})
	Returns the requested dataset, if it already exists, otherwise a new dataset is created. More...

scalar_dataset	require_scalar_dataset (const std::string &name, const type &datatype)
	Returns the requested scalar dataset, if it already exists, otherwise a new scalar dataset is created. More...

template<typename T >
scalar_dataset	require_scalar_dataset (const std::string &name)
	Returns the requested scalar dataset, if it already exists, otherwise the scalar dataset is created. More...

template<typename T >
scalar_dataset	require_scalar_dataset (const std::string &name, const T &value)
	Returns the requested scalar dataset, if it already exists, otherwise a new scalar dataset is created. More...

void	iterate_links (const std::function< void(const link &)> &op) const
	Iterates over every link within the root group. More...

void	visit_links (const std::function< void(const link &)> &visitor) const
	Visits every link, which is reachable from the root group. More...

void	visit_objects (const std::function< void(const object &)> &visitor) const
	Visits every object, which is reachable from the root group (including the root group) More...

object_reference	ref () const
	A HDF5 object reference to the root group.

const native_handle_type &	native_handle () const
	The underlying HDF5 low-level handle.

	operator bool () const
	Tests the validity of the handle.

attribute_repository< group >	attributes () const
	The attributes, which are attached to the root group.

Detailed Description

A handle to an HDF5 file object.

It can be used to access all properties of an HDF5 file. In addition it implements the same interface as group to cover the symmetry between a file (or more precise it's root group) and any other group.

Member Enumeration Documentation

enum echelon::hdf5::file::create_mode

strong

Enum containing possible creation modes for a file handle.

Enumerator
truncate	Truncate any pre-existing file.
exclusive	Raise an error, if the file already exists.

enum echelon::hdf5::file::open_mode

strong

Enum containing possible open modes for a file handle.

Enumerator
read_only	Open the file in the read-only mode.
read_write	Open the file in the read-write mode.

Constructor & Destructor Documentation

echelon::hdf5::file::file	(	const std::string &	path,
		create_mode	mode
	)

Creates a new HDF5 file using the given path and creation mode.

Parameters

path	path of the new HDF5 file
mode	creation mode, which is used during the file creation.

echelon::hdf5::file::file	(	const std::string &	path,
		open_mode	mode
	)

Opens a pre-existing HDF5 file using the given path and open mode.

Parameters

path	path of the pre-existing HDF5 file
mode	open mode, which is used to open the file

Member Function Documentation

dataset echelon::hdf5::file::create_dataset	(	const std::string &	name,
		const type &	datatype,
		const std::vector< hsize_t > &	dims,
		const dataset_options &	options = `{}`
	)

Creates a new HDF5 dataset within the root group.

Parameters

name name of the new dataset

datatype value type of the new dataset

dims shape of the new dataset

options

additional dataset creation options

keyword	semantic
_compression_level	level of the deflate compression (0 - 9)
_chunk_shape	shape of a dataset chunk

Returns: a handle to the new dataset

template<typename T >

dataset echelon::hdf5::file::create_dataset	(	const std::string &	name,
		const std::vector< hsize_t > &	dims,
		const dataset_options &	options = `{}`
	)

inline

Creates a new HDF5 dataset within the root group.

Parameters

name name of the new dataset

dims shape of the new dataset

options

additional dataset creation options

keyword	semantic
_compression_level	level of the deflate compression (0 - 9)
_chunk_shape	shape of a dataset chunk

Template Parameters

T	C++ type, which should be used to determine the dataset's value type

Returns: a handle to the new dataset

group echelon::hdf5::file::create_group ( const std::string & name )

Creates a new HDF5 group within the root group.

Parameters

name	name of the new group

Returns: a handle to the new group

scalar_dataset echelon::hdf5::file::create_scalar_dataset	(	const std::string &	name,
		const type &	datatype
	)

Creates a new HDF5 scalar dataset within the root group.

Parameters

name	name of the new dataset
datatype	value type of the new dataset

Returns: a handle to the new scalar dataset

template<typename T >

scalar_dataset echelon::hdf5::file::create_scalar_dataset ( const std::string & name )

inline

Creates a new HDF5 scalar dataset within the root group.

Parameters

name	name of the new dataset

Template Parameters

T	C++ type, which should be used to determine the dataset's value type

Returns: a handle to the new scalar dataset

template<typename T >

scalar_dataset echelon::hdf5::file::create_scalar_dataset	(	const std::string &	name,
		const T &	value
	)

inline

Creates a new HDF5 scalar dataset within the root group and initializes it with a given value.

Parameters

name	name of the new dataset
value	value, which should be used to intialize the dataset

Template Parameters

T	C++ type, which should be used to determine the dataset's value type

Returns: a handle to the new scalar dataset

void echelon::hdf5::file::iterate_links ( const std::function< void(const link &)> & op ) const

Iterates over every link within the root group.

Parameters

op	function, which is applied to every link

object echelon::hdf5::file::operator[] ( const std::string & name ) const

Accessor function for the root group.

Parameters

name	name of the requested object

Returns: a handle to the requested object

void echelon::hdf5::file::remove ( const std::string & name ) const

Removes the specified object from the root group.

Parameters

name	name of the removed object

dataset echelon::hdf5::file::require_dataset	(	const std::string &	name,
		const type &	datatype,
		const std::vector< hsize_t > &	dims,
		const dataset_options &	options = `{}`
	)

Returns the requested dataset, if it already exists, otherwise a new dataset is created.

The new dataset is created using the given parameters.

This method allows the user to make a contract with the library, that an object with certain properties exists after the method has terminated.

If the dataset already exists and its shape or datatype differ from their requested value and an exception is thrown, since the contract can't be fulfilled.

Parameters

name name of the requested dataset

datatype value type of the new dataset

dims shape of the new dataset

options

additional dataset creation options

keyword	semantic
_compression_level	level of the deflate compression (0 - 9)
_chunk_shape	shape of a dataset chunk

Exceptions

broken_contract_exception is thrown, if the contract can't be fulfilled.

Returns: the requested dataset, if it is already existing, or a new dataset otherwise

template<typename T >

dataset echelon::hdf5::file::require_dataset	(	const std::string &	name,
		const std::vector< hsize_t > &	dims,
		const dataset_options &	options = `{}`
	)

inline

Returns the requested dataset, if it already exists, otherwise a new dataset is created.

The new dataset is created using the given parameters.

This method allows the user to make a contract with the library, that an object with certain properties exists after the method has terminated.

If the dataset already exists and its shape or datatype differ from their requested value and an exception is thrown, since the contract can't be fulfilled.

Parameters

name name of the requested dataset

dims shape of the new dataset

options

additional dataset creation options

keyword	semantic
_compression_level	level of the deflate compression (0 - 9)
_chunk_shape	shape of a dataset chunk

Template Parameters

T	C++ type, which should be used to determine the dataset's value type

Exceptions

broken_contract_exception is thrown, if the contract can't be fulfilled.

Returns: the requested dataset, if it is already existing, or a new dataset otherwise

group echelon::hdf5::file::require_group ( const std::string & name )

Returns the requested group, if it already exists, otherwise a new group is created.

Parameters

name	name of the requested group

Returns: the requested group, if it is already existing, or a new group otherwise

scalar_dataset echelon::hdf5::file::require_scalar_dataset	(	const std::string &	name,
		const type &	datatype
	)

Returns the requested scalar dataset, if it already exists, otherwise a new scalar dataset is created.

The new dataset is created using the given parameters.

This method allows the user to make a contract with the library, that an object with certain properties exists after the method has terminated.

If the scalar dataset already exists and its datatype differs from its requested value and an exception is thrown, since the contract can't be fulfilled.

Parameters

name	name of the requested dataset
datatype	value type of the new dataset

Exceptions

broken_contract_exception is thrown, if the contract can't be fulfilled.

Returns: the requested scalar dataset, if it is already existing, or a new scalar dataset otherwise

template<typename T >

scalar_dataset echelon::hdf5::file::require_scalar_dataset ( const std::string & name )

inline

Returns the requested scalar dataset, if it already exists, otherwise the scalar dataset is created.

The new dataset is created using the given parameters.

This method allows the user to make a contract with the library, that an object with certain properties exists after the method has terminated.

If the scalar dataset already exists and its datatype differs from its requested value and an exception is thrown, since the contract can't be fulfilled.

Parameters

name	name of the requested dataset

Template Parameters

T	C++ type, which should be used to determine the dataset's value type

Exceptions

broken_contract_exception is thrown, if the contract can't be fulfilled.

Returns: the requested scalar dataset, if it is already existing, or a new scalar dataset otherwise

template<typename T >

scalar_dataset echelon::hdf5::file::require_scalar_dataset	(	const std::string &	name,
		const T &	value
	)

inline

Returns the requested scalar dataset, if it already exists, otherwise a new scalar dataset is created.

The new dataset is created using the given parameters and is initialized with the given value.

This method allows the user to make a contract with the library, that an object with certain properties exists after the method has terminated.

If the scalar dataset already exists and its datatype differs from its requested value and an exception is thrown, since the contract can't be fulfilled.

Parameters

name	name of the requested dataset
value	value, which should be used to intialize the dataset

Template Parameters

T	C++ type, which should be used to determine the dataset's value type

Exceptions

broken_contract_exception is thrown, if the contract can't be fulfilled.

Returns: the requested scalar dataset, if it is already existing, or a new scalar dataset otherwise

void echelon::hdf5::file::visit_links ( const std::function< void(const link &)> & visitor ) const

Visits every link, which is reachable from the root group.

Parameters

visitor visitor, which is applied to every visited link

void echelon::hdf5::file::visit_objects ( const std::function< void(const object &)> & visitor ) const

Visits every object, which is reachable from the root group (including the root group)

Parameters

visitor visitor, which is applied to every visited object

The documentation for this class was generated from the following files:

hdf5/file.hpp
hdf5/file.cpp

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation