Namespace hdf5::dataspace

Dataspace related classes and functions

Dataspace

class hdf5::dataspace::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

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

hdf5::Dimensions current_dimensions() const

current dimensions of a dataspace

Return the current dimensions of a dataspace.

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

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

SelectionManager

enum hdf5::dataspace::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

Scalar

class hdf5::dataspace::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 hdf5::dataspace::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 Simple&) = default

copy constructor

Use default implementation of the copy constructor

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

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

class hdf5::dataspace::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

enum hdf5::dataspace::SelectionType

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

enum hdf5::dataspace::SelectionOperation

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

Hyperslab

class hdf5::dataspace::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()

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

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