Array interface

Detailed Description

Specialized functions to read/write n-dimensional arrays from/to HDF5.

It provides specialized functions to read/write an h5::array_interface::array_view from/to HDF5. An array view mimics a view on a generic n-dimensional array. It uses HDF5's hyperslab concept to perform the reading/writing.

Example 1: Write/Read a 2-dimensional array shows how to use the array interface to write and read a 2-dimensional array.

Classes
struct	h5::array_interface::array_view
	Struct representing a view on an n-dimensional array/dataspace. More...
struct	h5::array_interface::dataset_info
	Simple struct to store basic information about an HDF5 dataset. More...
struct	h5::array_interface::hyperslab
	Struct representing an HDF5 hyperslab. More...

Functions
template<typename T >
array_view	h5::array_interface::array_view_from_scalar (T &x)
	Create an array view for a scalar.
template<typename T >
array_view	h5::array_interface::array_view_from_vector (std::vector< T > const &v)
	Create an h5::array_interface::array_view for a std::vector.
dataset_info	h5::array_interface::get_dataset_info (dataset ds)
	Retrieve the shape and the h5::datatype from a dataset.
dataset_info	h5::array_interface::get_dataset_info (group g, std::string const &name)
	Retrieve the shape and the h5::datatype from a dataset with a given name in the given group.
std::pair< v_t, v_t >	h5::array_interface::get_parent_shape_and_h5_strides (long const *np_strides, int rank, long view_size)
	Given a view on an n-dimensional array (dataspace) by specifying its numpy/nda-style strides and its size (number of elements in the view), calculate the shape of a possible parent array and the corresponding HDF5 strides of the view.
void	h5::array_interface::read (group g, std::string const &name, array_view v, hyperslab sl={})
	Read a given hyperslab from an HDF5 dataset into an array view.
void	h5::array_interface::read_attribute (object obj, std::string const &name, array_view v)
	Read from an HDF5 attribute into an array view.
void	h5::array_interface::write (group g, std::string const &name, array_view const &v, bool compress)
	Write an array view to an HDF5 dataset.
void	h5::array_interface::write_attribute (object obj, std::string const &name, array_view v)
	Write an array view to an HDF5 attribute.
void	h5::array_interface::write_slice (group g, std::string const &name, array_view const &v, hyperslab sl)
	Write an array view to a selected hyperslab of an existing HDF5 dataset.

Function Documentation

array_view_from_scalar()

template<typename T >

array_view h5::array_interface::array_view_from_scalar

(

T &

x

)

#include <h5/scalar.hpp>

Create an array view for a scalar.

Template Parameters

T	Scalar type.

Parameters

x	Scalar value.

Returns

h5::array_interface::array_view of rank 0.

Definition at line 48 of file scalar.hpp.

array_view_from_vector()

template<typename T >

array_view h5::array_interface::array_view_from_vector

(

std::vector< T > const &

v

)

#include <h5/stl/vector.hpp>

Create an h5::array_interface::array_view for a std::vector.

Template Parameters

T	Value type of std::vector.

Parameters

v	std::vector.

Returns

h5::array_interface::array_view of rank 1.

Definition at line 49 of file vector.hpp.

get_dataset_info() [1/2]

dataset_info h5::array_interface::get_dataset_info

(

dataset

ds

)

#include <h5/array_interface.cpp>

Retrieve the shape and the h5::datatype from a dataset.

Parameters

ds	h5::dataset.

Returns

h5::array_interface::dataset_info containing the shape and HDF5 type of the dataset.

Definition at line 98 of file array_interface.cpp.

get_dataset_info() [2/2]

dataset_info h5::array_interface::get_dataset_info	(	group	g,
		std::string const &	name )

#include <h5/array_interface.cpp>

Retrieve the shape and the h5::datatype from a dataset with a given name in the given group.

Parameters

g	h5::group containing the dataset.
name	Name of the dataset.

Returns

h5::array_interface::dataset_info containing the shape and HDF5 type of the dataset.

Definition at line 110 of file array_interface.cpp.

get_parent_shape_and_h5_strides()

std::pair< v_t, v_t > h5::array_interface::get_parent_shape_and_h5_strides	(	long const *	np_strides,
		int	rank,
		long	view_size )

#include <h5/array_interface.cpp>

Given a view on an n-dimensional array (dataspace) by specifying its numpy/nda-style strides and its size (number of elements in the view), calculate the shape of a possible parent array and the corresponding HDF5 strides of the view.

The memory layout is assumend to be in C-order. Suppose parent_shape is an array containing the shape of the n-dimensional parent array, np_strides contains the numpy strides and h5_strides are the HDF5 strides. Then the following equations have to hold (rank = N):

• np_strides[N - 1] = h5_strides[N - 1]
• np_strides[N - 2] = h5_strides[N - 2] * parent_shape[N - 1]
• np_strides[N - 3] = h5_strides[N - 3] * parent_shape[N - 1] * parent_shape[N - 2]
• ...
• np_strides[N - N] = h5_strides[N - N] * parent_shape[N - 1] * parent_shape[N - 2] * ... * parent_shape[1].

Note

The shape of the parent array as well as the HDF5 strides that fulfill the above equations are not unique. This is not a problem as long as HDF5 manages to select the correct elements in memory.

Parameters

np_strides	Numpy/nda-style strides.
rank	Rank of the n-dimensional parent array.
view_size	Number of elements in the given view.

Returns

std::pair containing the shape of the parent array and the HDF5 strides of the view.

Definition at line 60 of file array_interface.cpp.

read()

void h5::array_interface::read	(	group	g,
		std::string const &	name,
		array_view	v,
		hyperslab	sl = {} )

#include <h5/array_interface.cpp>

Read a given hyperslab from an HDF5 dataset into an array view.

Parameters

g	h5::group which contains the dataset.
name	Name of the dataset.
v	h5::array_interface::array_view to read into.
sl	h5::array_interface::hyperslab specifying the selection to read from.

Definition at line 209 of file array_interface.cpp.

read_attribute()

void h5::array_interface::read_attribute	(	object	obj,
		std::string const &	name,
		array_view	v )

#include <h5/array_interface.cpp>

Read from an HDF5 attribute into an array view.

Parameters

obj	h5::object to which the attribute is attached.
name	Name of the attribute.
v	h5::array_interface::array_view to read into.

Definition at line 246 of file array_interface.cpp.

write()

void h5::array_interface::write	(	group	g,
		std::string const &	name,
		array_view const &	v,
		bool	compress )

#include <h5/array_interface.cpp>

Write an array view to an HDF5 dataset.

If a link with the given name already exists, it is first unlinked.

Parameters

g	h5::group in which the dataset is created.
name	Name of the dataset
v	h5::array_interface::array_view to be written.
compress	Whether to compress the dataset.

Definition at line 115 of file array_interface.cpp.

write_attribute()

void h5::array_interface::write_attribute	(	object	obj,
		std::string const &	name,
		array_view	v )

#include <h5/array_interface.cpp>

Write an array view to an HDF5 attribute.

Parameters

obj	h5::object to which the attribute is attached.
name	Name of the attribute.
v	v h5::array_interface::array_view to be written.

Definition at line 192 of file array_interface.cpp.

write_slice()

void h5::array_interface::write_slice	(	group	g,
		std::string const &	name,
		array_view const &	v,
		hyperslab	sl )

#include <h5/array_interface.cpp>

Write an array view to a selected hyperslab of an existing HDF5 dataset.

It checks if the number of elements in the view is the same as selected in the hyperslab and if the datatypes are compatible. Otherwise, an exception is thrown.

Parameters

g	h5::group which contains the dataset.
name	Name of the dataset.
v	h5::array_interface::array_view to be written.
sl	h5::array_interface::hyperslab specifying the selection to be written to.

Definition at line 162 of file array_interface.cpp.