uzuki2::hdf5 Namespace Reference

Parse an R list from a HDF5 file. More...

Classes
struct	Options
	Options for HDF5 file parsing. More...

Functions
template<class Provisioner_ , class Externals_ >
ParsedList	parse (const H5::Group &handle, Externals_ ext, const Options &options)
template<class Provisioner_ , class Externals_ >
ParsedList	parse (const std::string &file, const std::string &name, Externals_ ext, Options options=Options())
void	validate (const H5::Group &handle, int num_external, const Options &options)
void	validate (const std::string &file, const std::string &name, int num_external, const Options &options)

Detailed Description

Parse an R list from a HDF5 file.

The hierarchical nature of HDF5 allows it to naturally store nested list structures. It supports random access of list components, which provides some optimization opportunities for parsing large lists. However, it incurs a large overhead per list element; for small lists, users may prefer to use a JSON file instead (see json).

Function Documentation

parse() [1/2]

template<class Provisioner_ , class Externals_ >

ParsedList uzuki2::hdf5::parse	(	const H5::Group &	handle,
		Externals_	ext,
		const Options &	options )

Template Parameters

Provisioner_	A class namespace defining static methods for creating new Base objects.
Externals_	Class describing how to resolve external references for type EXTERNAL.

Parameters

handle	Handle for a HDF5 group corresponding to the list.
ext	Instance of an external reference resolver class.
options	Optional parameters.

Returns

A ParsedList containing a pointer to the root Base object. Depending on Provisioner_, this may contain references to all nested objects.

Any invalid representations in contents will cause an error to be thrown.

Provisioner requirements

The Provisioner_ class is expected to provide the following static methods:

• Nothing* new_Nothing(), which returns a new instance of a Nothing subclass.
• Other* new_Other(void* p), which returns a new instance of a Other subclass. p is a pointer to an "external" object, generated by calling ext.get() (see below).
• List* new_List(size_t l, bool n), which returns a new instance of a List with length l. If n = true, names are present and will be added via List::set_name().
• IntegerVector* new_Integer(size_t l, bool n, bool s), which returns a new instance of an IntegerVector subclass of length l. If n = true, names are present and will be added via Vector::set_name(). If s = true and l = 1, the value was represented on file as a scalar integer.
• NumberVector* new_Number(size_t l, bool n, bool s), which returns a new instance of a NumberVector subclass of length l. If n = true, names are present and will be added via Vector::set_name(). If s = true and l = 1, the value was represented on file as a scalar float.
• StringVector* new_String(size_t l, bool n, bool s, StringVector::Format f), which returns a new instance of a StringVector subclass of length l with format f. If n = true, names are present and will be added via Vector::set_name(). If s = true and l = 1, the value was represented on file as a scalar string.
• BooleanVector* new_Boolean(size_t l, bool n, bool s), which returns a new instance of a BooleanVector subclass of length l. If n = true, names are present and will be added via Vector::set_name(). If s = true and l = 1, the value was represented on file as a scalar boolean.
• Factor* new_Factor(size_t l, bool n, bool s, size_t ll, bool o), which returns a new instance of a Factor subclass of length l and with ll unique levels. If n = true, names are present and will be added via Vector::set_name(). If s = true and l = 1, the lone index was represented on file as a scalar integer. If o = true, the levels should be assumed to be sorted.

Externals requirements

The Externals_ class is expected to provide the following const methods:

• void* get(size_t i) const, which returns a pointer to an "external" object, given the index of that object. This will be stored in the corresponding Other subclass generated by Provisioner_::new_External.
• size_t size(), which returns the number of available external references.

parse() [2/2]

template<class Provisioner_ , class Externals_ >

ParsedList uzuki2::hdf5::parse	(	const std::string &	file,
		const std::string &	name,
		Externals_	ext,
		Options	options = Options() )

Parse HDF5 file contents using the uzuki2 specification, given the file path.

Template Parameters

Provisioner_	A class namespace defining static methods for creating new Base objects.
Externals_	Class describing how to resolve external references for type EXTERNAL.

Parameters

file	Path to a HDF5 file.
name	Name of the HDF5 group containing the list in file.
ext	Instance of an external reference resolver class.
options	Optional parameters.

Returns

A ParsedList containing a pointer to the root Base object. Depending on Provisioner_, this may contain references to all nested objects.

Any invalid representations in contents will cause an error to be thrown.

validate() [1/2]

void uzuki2::hdf5::validate ( const H5::Group & handle, int num_external, const Options & options )

inline

Validate HDF5 file contents against the uzuki2 specification, given the group handle. Any invalid representations will cause an error to be thrown.

Parameters

handle	Handle for a HDF5 group corresponding to the list.
num_external	Expected number of external references.
options	Optional parameters.

validate() [2/2]

void uzuki2::hdf5::validate ( const std::string & file, const std::string & name, int num_external, const Options & options )

inline

Validate HDF5 file contents against the uzuki2 specification, given the file path. Any invalid representations will cause an error to be thrown.

Parameters

file	Path to a HDF5 file.
name	Name of the HDF5 group containing the list in file.
num_external	Expected number of external references.
options	Optional parameters.