A handle to a file object. More...

#include <file.hpp>

Public Types
using	native_handle_type = hdf5::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 file using the given path and creation mode. More...

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

group	create_group (const std::string &name)
	Creates a new 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=dataset_options())
	Creates a new dataset within the root group. More...

dataset	create_dataset (const std::string &name, const type &datatype, const std::vector< hsize_t > &dims, const std::vector< hsize_t > &max_dims, const dataset_options &options=dataset_options())
	Creates a new 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=dataset_options())
	Creates a new dataset within the root group. More...

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

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

template<typename T >
scalar_dataset	create_scalar_dataset (const std::string &name)
	Creates a new 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 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=dataset_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=dataset_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 object reference to the root group.

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.

Related Functions
(Note that these are not member functions.)
group	mount (const file &mounted_file, const group &mount_point)
	Mounts a file at a specified location. More...

group	mount (const file &mounted_file, const file &mount_point)
	Mounts a file at a specified location. More...

void	unmount (const group &mount_point)
	Unmounts a previously mounted file. More...

group	mount (const file &mounted_file, const group &mount_point)
	Mounts a file at a specified location. More...

group	mount (const file &mounted_file, const file &mount_point)
	Mounts a file at a specified location. More...

void	unmount (const group &mount_point)
	Unmounts a previously mounted file. More...

Detailed Description

A handle to a file object.

It can be used to access all properties of an echelon 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::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::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::file::file	(	const std::string &	path,
		create_mode	mode
	)

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

Parameters

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

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

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

Parameters

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

Member Function Documentation

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

Creates a new 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)
shuffle_filter	enable/disable the shuffle filter
auto_chunking	enable/disable auto-chunking
chunk_shape	shape of a dataset chunk

Returns: a handle to the new dataset

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

Creates a new dataset within the root group.

If the maximal extent of the dataset is specified any value might be set to echelon::unlimited to not restrict this dimension.

Parameters

name name of the new dataset

datatype value type of the new dataset

dims shape of the new dataset

max_dims maximal extent of the dataset (each value might be 'unlimited')

options

additional dataset creation options

keyword	semantic
compression_level	level of the deflate compression (0 - 9)
shuffle_filter	enable/disable the shuffle filter
auto_chunking	enable/disable auto-chunking
chunk_shape	shape of a dataset chunk

Returns: a handle to the new dataset

template<typename T >

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

inline

Creates a new 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)
shuffle_filter	enable/disable the shuffle filter
auto_chunking	enable/disable auto-chunking
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

template<typename T >

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

inline

Creates a new dataset within the root group.

If the maximal extent of the dataset is specified any value might be set to echelon::unlimited to not restrict this dimension.

Parameters

name name of the new dataset

dims shape of the new dataset

max_dims maximal extent of the dataset (each value might be 'unlimited')

options

additional dataset creation options

keyword	semantic
compression_level	level of the deflate compression (0 - 9)
shuffle_filter	enable/disable the shuffle filter
auto_chunking	enable/disable auto-chunking
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::file::create_group ( const std::string & name )

Creates a new group within the root group.

Parameters

name	name of the new group

Returns: a handle to the new group

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

Creates a new 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::file::create_scalar_dataset ( const std::string & name )

inline

Creates a new 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::file::create_scalar_dataset	(	const std::string &	name,
		const T &	value
	)

inline

Creates a new 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::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::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::file::remove ( const std::string & name ) const

Removes the specified object from the root group.

Parameters

name	name of the removed object

dataset echelon::file::require_dataset	(	const std::string &	name,
		const type &	datatype,
		const std::vector< hsize_t > &	dims,
		const dataset_options &	options = `dataset_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)
shuffle_filter	enable/disable the shuffle filter
auto_chunking	enable/disable auto-chunking
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::file::require_dataset	(	const std::string &	name,
		const std::vector< hsize_t > &	dims,
		const dataset_options &	options = `dataset_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)
shuffle_filter	enable/disable the shuffle filter
auto_chunking	enable/disable auto-chunking
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::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::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::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::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::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::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

Friends And Related Function Documentation

group mount	(	const file &	mounted_file,
		const group &	mount_point
	)

Parameters

mounted_file	file to be mounted
mount_point	location at which the file is mounted

Returns: a handle to the mount point

group mount	(	const file &	mounted_file,
		const file &	mount_point
	)

Parameters

mounted_file	file to be mounted
mount_point	location at which the file is mounted

Returns: a handle to the mount point

group mount	(	const file &	mounted_file,
		const group &	mount_point
	)

Parameters

mounted_file	file to be mounted
mount_point	location at which the file is mounted

Returns: a handle to the mount point

group mount	(	const file &	mounted_file,
		const file &	mount_point
	)

Parameters

mounted_file	file to be mounted
mount_point	location at which the file is mounted

Returns: a handle to the mount point

void unmount ( const group & mount_point )

Parameters

mount_point mount point of the file to be unmounted

void unmount ( const group & mount_point )

Parameters

mount_point mount point of the file to be unmounted

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

file.hpp
file.cpp

Public Types

Public Member Functions

Related Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Friends And Related Function Documentation