h5::H5File< Access_t > Class Template Reference

Opens an HDF5 file for access and allows manipulation of data. More...

#include <File.hpp>

Public Member Functions
	H5File (std::string file_name, bool append_to_file=false)
const std::string &	name () const noexcept
	Get name of the H5 file.
const std::vector< std::string >	groups () const noexcept
	Get a std::vector of the names of all immediate subgroups of the file.
template<typename ObjectType , typename... Args>
ObjectType &	insert (const std::string &path, Args &&... args)
	Insert an object into an H5 file. More...
template<typename ObjectType , typename... Args>
ObjectType &	try_insert (const std::string &path, Args &&... args) noexcept
	Inserts an object like insert if it does not exist, returns the object if it does.
void	close_current_object () const noexcept
template<typename ObjectType >
bool	exists (const std::string &path) const noexcept
	H5File (const H5File &)=delete
	It does not make sense to copy an object referring to a file, only to move it.
H5File &	operator= (const H5File &)=delete
	It does not make sense to copy an object referring to a file, only to move it.
template<typename ObjectType , typename... Args, typename std::enable_if_t<((void) sizeof(ObjectType), Access_t==AccessType::ReadWrite)> * = nullptr>
ObjectType &	get (const std::string &path, Args &&... args)
template<typename ObjectType , typename... Args>
const ObjectType &	get (const std::string &path, Args &&... args) const

Detailed Description

template<AccessType Access_t>
class h5::H5File< Access_t >

Opens an HDF5 file for access and allows manipulation of data.

Opens an HDF5 file either in ReadOnly or ReadWrite mode depending on the template parameter Access_t. In ReadWrite mode h5::Object's can be inserted into the file, and objects can be retrieved to have their data manipulated. Example objects are dat files, text files, and volume data files. A single H5File can contain many different objects so that the number of files stored during a simulation is reduced.

When an h5::object inside an H5File is opened or created the H5File object holds a copy of the h5::object. Only one object can be open at a time, which means if a reference to the object is kept around after the H5File's current object is closed there is a dangling reference.

Example

To open a file for read-write access:

    h5::H5File<h5::AccessType::ReadWrite> my_file(file_name);

Note

The dangling reference issue could be fixed by having a function in addition to get that takes a lambda. The lambda takes exactly one parameter of the type of the h5::Object it will be operating on. While this approach is likely to be syntactically strange for many users it will most likely be more performant than the shared_ptr solution.

Template Parameters

Access_t

either h5::AccessType::ReadWrite or h5::AccessType::ReadOnly

Constructor & Destructor Documentation

H5File()

template<AccessType Access_t>

h5::H5File< Access_t >::H5File ( std::string  file_name, bool  append_to_file = false  )

explicit

Requires: file_name is a valid path and ends in .h5.

Effects: On object creation opens the HDF5 file at file_name

Parameters

file_name	the path to the file to open or create
append_to_file	if true allow appending to the file, otherwise abort the simulation if the file exists

Member Function Documentation

close_current_object()

template<AccessType Access_t>

void h5::H5File< Access_t >::close_current_object ( ) const

inlinenoexcept

Effects: Closes the current object, if there is none then has no effect

get() [1/2]

template<AccessType Access_t>

template<typename ObjectType , typename... Args, typename std::enable_if_t<((void) sizeof(ObjectType), Access_t==AccessType::ReadWrite)> * >

ObjectType & h5::H5File< Access_t >::get	(	const std::string &	path,
		Args &&...	args
	)

Requires: ObjectType is a valid h5::Object derived class, path is a valid path in the HDF5 file

Returns: a reference to the object inside the HDF5 file.

Template Parameters

ObjectType

the type of the h5::Object to be retrieved, e.g. Dat

Parameters

path	the path of the retrieved object
args	arguments forwarded to the ObjectType constructor

get() [2/2]

template<AccessType Access_t>

template<typename ObjectType , typename... Args>

const ObjectType & h5::H5File< Access_t >::get	(	const std::string &	path,
		Args &&...	args
	)		const

Requires: ObjectType is a valid h5::Object derived class, path is a valid path in the HDF5 file

Returns: a reference to the object inside the HDF5 file.

Template Parameters

ObjectType

the type of the h5::Object to be retrieved, e.g. Dat

Parameters

path	the path of the retrieved object
args	arguments forwarded to the ObjectType constructor

insert()

template<AccessType Access_t>

template<typename ObjectType , typename... Args>

ObjectType & h5::H5File< Access_t >::insert	(	const std::string &	path,
		Args &&...	args
	)

Insert an object into an H5 file.

Requires: ObjectType is a valid h5::Object derived class, path is a valid path in the HDF5 file, and args are valid arguments to be forwarded to the constructor of ObjectType.

Effects: Creates a new H5 object of type ObjectType at the location path in the HDF5 file.

Returns: a reference the created object.

Template Parameters

ObjectType

the type of the h5::Object to be inserted, e.g. Dat

Parameters

path	the path of the inserted object
args	additional arguments to be passed to the constructor of the object