Namespace hdf5::dataspace

Dataspace related classes and functions

Dataspace

class Dataspace

dataspace base class

Subclassed by hdf5::dataspace::Scalar, hdf5::dataspace::Simple

Public Functions

virtual ~Dataspace()

destructor

Has to be virtual due to inheritance

Dataspace()

default constructor

The default constructor will leave the dataspace as an invalid HDF5 object. Default construction is however necessary for using a Dataspace with certain C++ STL containers.

See also

is_valid()

Dataspace(ObjectHandle &&handle)

constructor

Constructs a dataspace object from an rvalue reference to an HDF5 handle. The class will take full ownership of the handle.

Parameters:

handle – rvalue reference to the handle

Dataspace(Dataspace &&type) = default

move constructor

Use default implementation here.

Dataspace(const Dataspace &space)

copy constructor

Dataspace &operator=(const Dataspace &space)

copy assignment

virtual hssize_t size() const

number of elements in the dataspace

Throws:

std::runtime_error – in case of a failure

inline explicit operator hid_t() const

allows explicit conversion to hid_t

This function is mainly used by static_cast for explicit conversion to hid_t.

Dataspace space();
hid_t id = static_cast<hid_t>(space);

Type type() const

get the type of the dataspace

Throws:

std::runtime_error – in case of a failure

bool is_valid() const

check validity of the dataspace

Returns true if the dataspace is a valid HDF5 object. This member function should return true in most cases. However, in cases that the dataspace was

• default constructed

• or the close() method was called before

this function will return false.

See also

Dataspace()

Throws:

std::runtime_error – in case of a failure

Returns:

true if valid, false if invalid

Public Members

SelectionManager selection

access to selection manager

This public member provides access to the selection manager of the dataspace. See the SelectionManager documentation for interface details.

See also

SelectionManager

Scalar

class Scalar : public hdf5::dataspace::Dataspace

scalar dataspace

Dataspace for a single value

Public Functions

Scalar()

default constructor

Scalar(const Dataspace &space)

constructor

Construct a scalar dataspace from its base class. In this case. If the Dataspace instance is not a scalar instance an exception will be thrown.

Throws:

std::runtime_error – in case of an error

Parameters:

space – reference to a Dataspace instance

Simple

class Simple : public hdf5::dataspace::Dataspace

simple multidimensional dataspace

Public Functions

Simple()

default constructor

Simple(const Dataspace &space)

constructor

Construct a simple dataspace from a reference to its base instance. If space does not refer to a simple dataspace an exception will be thrown.

Throws:

std::runtime_error – in case of a failure

Parameters:

space – reference to a dataspace instance

Simple(const Dimensions &current, const Dimensions &maximum = hdf5::Dimensions())

constructor

If the maximum dimensions is not provided it will be set to the current number of elements along each dimension.

See also

dimensions

Throws:

std::runtime_error – in case of a failure

Parameters:

• current – current number of elements along each dimension

• maximum – maximum number of elements along each dimension

size_t rank() const

get number of dimensions

Throws:

std::runtime_error – in case of a failure

void dimensions(const Dimensions &current, const Dimensions &maximum = Dimensions())

set number of elements along each dimension

Throws:

std::runtime_error – in case of a failure

Dimensions current_dimensions() const

get current dimensions

Throws:

std::runtime_error – in case of a failure

Dimensions maximum_dimensions() const

get maximum dimensions

Throws:

std::runtime_error – in case of a failure

Public Static Attributes

static const hsize_t unlimited

dimension value for unlimited number of elements

Selection related classes and functions

Selection and SelectionList

class Selection

selection base class

Subclassed by hdf5::dataspace::Hyperslab, hdf5::dataspace::Points

Public Types

using UniquePointer = std::unique_ptr<Selection>

pointer for selection stacks

As selections use virtual functions for being applied we have to

Public Functions

Selection() = default

default constructor

Use the compiler provided default implementation.

Selection(const Selection&) = default

copy constructor

Use the compiler provided default implementation.

virtual ~Selection()

destructor

The destructor has to be virtual to inherit from this class.

virtual void apply(const Dataspace &space, SelectionOperation ops) const = 0

apply a selection onto a dataspace

The current selection will be applied to dataspace space using the operator determined by ops.

Throws:

std::runtime_error – in case of a failure

Parameters:

• space – reference to the dataspace onto which to apply the selection

• ops – operator for the selection

virtual Dimensions dimensions() const = 0

get current dimensions

Get a number of elements along each dimension a selection spans this is particularly useful in the case of a Hyperslab

Throws:

std::runtime_error – in case of a failure

Returns:

the selection dimentsions

virtual size_t size() const = 0

get the selection size

Get the total number of elements adressed by an individual selection

Throws:

std::runtime_error – in case of a failure

Returns:

the selection type enumerator

virtual SelectionType type() const = 0

get the selection type

Get the type of the selection

Returns:

the selection type enumerator

using hdf5::dataspace::SelectionList = std::list<OperationWithSelection>

Dataspace hdf5::dataspace::operator||(const Dataspace &space, const SelectionList &selections)

Hyperslab

class Hyperslab : public hdf5::dataspace::Selection

hyperslab selection class

Hyperslabs represent complex multidimensional selections within an HDF5 dataset. The number of dimensions for every hyperslab is determined during construction and cannot be altered once it has been fixed.

Todo:

• we may have to add a function to check if all the Dimension instances have the same size. However, this might be an expensive procedure and we should take performance considerations into account here.

Public Functions

Hyperslab()

default constructor

The default constructor is present to allow Hyperslabs in STL containers. It must be noted that any attempt to change an internal value will result in a std::runtime_error exception. The rank of a default constructed Hyperslab would be 0. As a Hyperslab of rank 0 would not make any sense one could use this to identify a default constructed Hyperslab.

Post:

all internal buffers remain unallocated

~Hyperslab() override

destructor

Hyperslab(const Hyperslab&) = default

copy constructor

Use compiler generated default implementation here

Hyperslab(size_t rank)

constructor

Construct a Hyperslab selection of a given rank.

Parameters:

rank – the number of dimensions

Post:

all start values are set to 0

Post:

all stride values are set to 1

Post:

all count values are set to 0

Post:

all block values are set to 0

Hyperslab(const Dimensions &offset, const Dimensions &block, const Dimensions &count, const Dimensions &stride)

constructor

This constructor exposes the full capabilities of a hyperslab. All parameters can be adjusted.

Parameters:

• offset – the offset from which to start the selection

• block – the size of a single block in the selection

• count – the number of blocks along each dimensions

• stride – the stride along each dimension between the blocks

Hyperslab(const Dimensions &offset, const Dimensions &block)

constructor

Construct a hyperslab which constists of a single block starting at a particular offset.

Parameters:

• offset – the start offset of the block

• block – the size of the single block

Hyperslab(const Dimensions &offset, const Dimensions &count, const Dimensions &stride)

constructor

Construct a hyperslab which consists of count blocks of size 1 along each dimension separated by stride elements.

Parameters:

• offset – starting offset of the selection

• count – number of blocks along each dimensions

• stride – the stride between the blocks along each dimension

size_t rank() const noexcept

get rank

Returns:

number of dimensions in the selection

void offset(size_t index, size_t value)

set start value for a dimension

Set the start value of the hyperslab for a particular dimension determined by index to value. This method throws an exception if the dimension index exceeds the rank of the hyperslab.

Throws:

std::runtime_error – in case of a failure

Parameters:

• index – dimension index

• value – new start value

void offset(const Dimensions &values)

set all start values

Set the start values for all dimensions of the hyperslab. If the size of values exceeds the rank of the hyperslab an exception will be thrown.

Throws:

std::runtime_error – in case of a failure

Parameters:

values – new start values for the hyperslab

const Dimensions &offset() const

get start values

Throws:

std::runtime_error – if the Hyperslab is default constructed

Returns:

const reference to the start values of the hyperslab

void stride(size_t index, size_t value)

set stride value for an individual dimension

Throws:

std::runtime_error – in case of a failure

Parameters:

• index – dimension index for which to set the stride

• value – new stride value

void stride(const Dimensions &values)

set all stride values for the Hyperslab

Throws:

std::runtime_error – in case of a failure

Parameters:

values – new stride values for the Hyperslab

const Dimensions &stride() const

get stride values for the Hyperslab

Throws:

std::runtime_error – in case of a failure

Returns:

const reference to the stride values

void count(size_t index, size_t value)

set count value for a particular dimension

Throws:

std::runtime_error – in case of a failure

Parameters:

• index – dimension index

• value – new count value for this dimension

void count(const Dimensions &values)

set all count values

Throws:

std::runtime_error – in case of a failure

Parameters:

values – reference to the new count values

const Dimensions &count() const

get count values

Return a const reference to the count values of the Hypeslab. The values cannot be changed via this reference.

Throws:

std::runtime_error – in case of a failure

Returns:

reference to count values

void block(size_t index, size_t value)

set block size for dimension

Throws:

std::runtime_error – in case of a failure

Parameters:

• index – dimension index

• value – the new block size for this dimension

void block(const Dimensions &values)

set all block values

Set all block values for the hyperslab selection.

Throws:

std::runtime_error – in case of a failure

Parameters:

values – reference to the new block values

const Dimensions &block() const

get block values

Get a const reference to the block values of the hyperslab.

Throws:

std::runtime_error – in case of a failure

Returns:

const reference to the block values

virtual void apply(const Dataspace &space, SelectionOperation ops) const override

apply a selection onto a dataspace

The current selection will be applied to dataspace space using the operator determined by ops.

Throws:

std::runtime_error – in case of a failure

Parameters:

• space – reference to the dataspace onto which to apply the selection

• ops – operator for the selection

virtual Dimensions dimensions() const override

get current dimensions

Get a number of elements along each dimension a selection spans this is particularly useful in the case of a Hyperslab

Throws:

std::runtime_error – in case of a failure

Returns:

the selection dimentsions

virtual size_t size() const override

get the selection size

Get the total number of elements adressed by an individual selection

Throws:

std::runtime_error – in case of a failure

Returns:

the selection type enumerator

virtual SelectionType type() const override

get the selection type

Get the type of the selection

Returns:

the selection type enumerator

Dataspace hdf5::dataspace::operator||(const Dataspace &space, const Hyperslab &selection)

Points

class Points : public hdf5::dataspace::Selection

point selection implementation

Public Functions

Points() = default

default constructor

We use the compiler provided default implementation.

~Points() override = default

destructor

Use the compiler provided default implementation.

explicit Points(size_t rank)

constructor

Create a new point selection or a given rank

Parameters:

rank – the number of dimensions of the selection

explicit Points(const std::vector<std::vector<hsize_t>> &coord_set)

constructor

Create a point selection from a set of selection coordinates. The number of dimensions of the first coordinates determines the rank of the selection.

Parameters:

coord_set – set of selection coordinates

size_t rank() const

get the number of dimensions

Returns:

number of dimensions of the selection.

size_t points() const

get the number of points in the selection

Returns:

number of points as unsigned integer

void add(const std::vector<hsize_t> &coords)

add a new point to the selection

Parameters:

coords – index coordinates of the point

Throws:

runtime_error – in the case of a failure

void add_set(const std::vector<std::vector<hsize_t>> &coord_set)

add point set to the selection

Parameters:

coord_set – coordinate set

Throws:

runtime_error – in the case of a failure

virtual void apply(const Dataspace &space, SelectionOperation ops) const override

apply the selection to a dataspace

Parameters:

• space – reference to the dataspace onto which the selection should be applied

• ops – opertion used to apply the selection

virtual size_t size() const override

get the selection size

Get the total number of elements adressed by an individual selection

Throws:

std::runtime_error – in case of a failure

Returns:

the selection type enumerator

virtual SelectionType type() const override

get the selection type

Get the type of the selection

Returns:

the selection type enumerator

virtual Dimensions dimensions() const override

get current dimensions

Get a number of elements along each dimension a selection spans this is particularly useful in the case of a Hyperslab

Throws:

std::runtime_error – in case of a failure

Returns:

the selection dimentsions

SelectionManager

class SelectionManager

interface for selection management

The SelectionManager provides an interface to access the selections made on a Dataspace. It stores a reference to the dataspace it belongs to and applies or removes selections on this dataspace.

Public Functions

SelectionManager() = delete

not default constructible

SelectionManager(Dataspace &space)

constructor

Parameters:

space – reference to the dataspace the manager instance belongs to

SelectionManager(const SelectionManager&) = default

copy constructor

Use the default implementation here

void operator()(SelectionOperation ops, const Selection &selection) const

apply a selection

Throws:

std::runtime_error – in case of a failure

Parameters:

• ops – selection operator

• selection – reference to the selection to apply

size_t size() const

return the number of elements in the current selection

This value may differ from the number of elements stored in a dataspace.

Throws:

std::runtime_error – in case of a failure

SelectionType type() const

get the type of the current selection

void all() const

select everything

void none() const

select nothing

View

class View

guard object for selections

The View class applies selections on a dataspace. Since a copy of the original dataspace is created the former one remains unchanged.

Public Functions

View() = default

default constructor

Need this for STL container compatibility. Can rely on default implementation provided by the compiler.

View(const View&) = default

copy constructor

Need this for STL container compatibility. Use the default implementation provided by the compiler.

explicit View(const Dataspace &space)

constructor

This constructor applies now selection but selects all elements in the dataspace.

Throws:

std::runtime_error – in the case of a failure

Parameters:

space – reference to the original dataspace

View(const Dataspace &space, const SelectionList &selections)

constructor

Creates a copy of the dataspace and applies all selections provieed by th selection list to this copy.

Throws:

std::runtime_error – in case of a failure

Parameters:

• space – reference to the original dataspace

• selections – reference to the list of selections to apply

View(const Dataspace &space, const Hyperslab &selection)

constructor

Creates a copy of the dataspace and applies a single hyperslab on it. This is a conveniance constructor in the case that we need only a single hyperslab.

Throws:

std::runtime_error – in case of a failure

Parameters:

• space – reference to the original dataspace

• selection – reference to the original hyperslab

void operator()(const SelectionList &selections) const

apply a new set of selections

Calling this operator will erase all current selections and replace them by the new set of selections provided by the selections argument.

Throws:

std::runtime_error –

void operator()(const Hyperslab &slab) const

set a single hyperslab

This is a mere convienance function for situations where a single Hyperslab should be selected. This even might be the most common case at all.

Throws:

std::runtime_error – in case of a failure

Parameters:

slab – reference to the hyperslab

size_t size() const

get number of elements in the view

DataspaceHolder

class DataspaceHolder

data space object holder

Public Functions

inline DataspaceHolder()

default constructor

The default constructor. The dataspace pool is created internally

inline DataspaceHolder(DataspacePool &pool)

constructor

Parameters:

pool – dataspace pool

template<typename T>
const Dataspace &get(const T &v)

factory holder method for getting reference of data spaces

Returns data space reference for static data space object if available. Otherwise it creates a new data space object and returns its reference.

Parameters:

v – provided dataspace data

Returns:

data space reference for data space object

DataspacePool

class DataspacePool

data space object pool

Public Functions

const Simple &getSimple(size_t size)

reference of Simple data spaces

Returns data space reference for static data space object

Throws:

std::runtime_error – in case of a failure

Parameters:

size – dimension of 1D Simple Dataspace to get or create

Returns:

data space reference for data space object

const Simple &getSimple(const Dimensions &current, const Dimensions &maximum = Dimensions())

reference of Simple data spaces

Returns data space reference for static data space object

Throws:

std::runtime_error – in case of a failure

Parameters:

• current – current number of elements along each dimension

• maximum – maximum number of elements along each dimension

Returns:

data space reference for data space object

Type traits

TypeTrait

template<typename T>
class TypeTrait

type trait for dataspace construction

This trait provides a static function creating a new dataspace for a particular instance of T. To integrate new types just add a specialization of this trait.

Template Parameters:

T – type for which to construct a dataspace

Enumerations

Type

enum class hdf5::dataspace::Type : std::underlying_type<H5S_class_t>::type

determine the datatype instance

This enumeration type is primarily used to identify the particular type of dataspace when given only a reference to dataspace::Dataspace.

Values:

enumerator Scalar

the dataspace is an instance of dataspace::Scalar

enumerator Simple

the dataspace is an instance of dataspace::Simple

enumerator NoData

the dataspace is an instance of dataspace::Null

Warning

dataspace::Null is currently not implemented

std::ostream &hdf5::dataspace::operator<<(std::ostream &stream, const Type &t)

SelectionType

enum class hdf5::dataspace::SelectionType : std::underlying_type<H5S_sel_type>::type

selection type

Determines what kind of selection is applied to a datatype. Like datapsace::Type this identifies the particular type of selection when given only a reference to dataspace::Selection.

Values:

enumerator None

nothing is selected

enumerator Points

the selection is a point selection (dataspace::Points)

enumerator Hyperslab

the selection is a hyperslab selection (dataspace::Hyperslab)

enumerator All

everything is selected

std::ostream &hdf5::dataspace::operator<<(std::ostream &stream, const SelectionType &t)

SelectionOperation

enum class hdf5::dataspace::SelectionOperation : std::underlying_type<H5S_seloper_t>::type

selection operator

Values:

enumerator Set

replace all selections by this one

enumerator Or

select all elements which are in this or the previously applied selections

enumerator And

selects the overlapping region of the actual selection and previously applied selections

enumerator XOr

select all elements which are either in this or in the previously applied selections but not in both

enumerator NotB

select those elements which are on the previously applied selections but not in the current one

enumerator NotA

select only those elements which are in the current selection and not in the previous ones

enumerator Append

for point selections: add the point to the end of the current list of points

enumerator Prepend

for point selections: add the point to the beginning of the current list of points

std::ostream &hdf5::dataspace::operator<<(std::ostream &stream, const SelectionOperation &o)