Namespace hdf5::file

The File class

class hdf5::file::File

Public Functions

File() = default

default constructor

Use default implementation here. We need this to store instances of this class in an STL container. A default constructed instance of File is in an invalid state. This can be checked using the is_valid() method.

See also

is_valid()

File(const File&) = default

copy constructor

Use default implementation here.

File(File&&) = default

move constructor

Use default implementation here.

explicit File(ObjectHandle &&handle)

constructor

Construct a file from an rvalue reference to a handle.

Parameters

handle – rvalue reference to the file handler

AccessFlags intent() const

get access flags for the file

Throws

std::runtime_error – in case of a failure

size_t size() const

get the file size in bytes

Throws

std::runtime_error – in case of a failure

ssize_t buffer_size() const

get the buffer size in bytes

Throws

std::runtime_error – in case of a failure

void flush(Scope scope) const

flush the file

Throws

std::runtime_error – in case of a failure

Parameters

scope – the scope within which the file should be flushed

void close()

close the file

Throws

std::runtime_error – in case of a failure

fs::path path() const

get path on file system

Return the file system path of the file.

size_t count_open_objects(SearchFlags flag) const

count number of open objects

Return the number of open objects belonging to that very file instance.

node::Group root(const property::GroupAccessList &gapl = property::GroupAccessList()) const

get root group

Return an instance to the root group of the file.

Throws

std::runtime_error – in case of a failure

Parameters

gapl – reference to a group access property list

Returns

new instance of node::Group

template<typename T>
size_t to_buffer(T &data) const

retrieve a copy of the image of an existing, open file

See also

ImageFlags

Throws

std::runtime_error – in case of a failure

Template Parameters

T – source type

Parameters

data – reference to the source instance of T

Returns

size of used space in a buffer

template<typename T>
size_t to_buffer_reshape(T &data, const datatype::Datatype &mem_type, const dataspace::Dataspace &mem_space) const

retrieve a copy of the image of an existing, open file

It reshapes the mem_space if its rank does not match to the selection rank

See also

ImageFlags

Throws

std::runtime_error – in case of a failure

Template Parameters

T – source type

Parameters

• data – reference to the source instance of T

• mem_type – reference to the memory data type

• mem_space – reference to the memory data space

Returns

size of used space in a buffer

bool is_valid() const

check validity of the instance

Return true if the instance refers to a valid HDF5 file instance.

Throws

std::runtime_error – in case of a failure

Returns

true if valid, false otherwise

ObjectId id() const

return a unique id for the file object

Return an instance of ObjectId which uniquely identifies a file object.

Functions

create()

File hdf5::file::create(const fs::path &path, AccessFlags flags = AccessFlags::Exclusive, const property::FileCreationList &fcpl = property::FileCreationList(), const property::FileAccessList &fapl = property::FileAccessList())

create a new file

See also

AccessFlags

See also

FileCreationList

See also

FileAccessList

Parameters

• path – the path to the new file

• flags – HDF5 file creation flags

• fcpl – reference to a file creation property list

• fapl – reference to a file access property list

Throws

std::runtime_error – in case of a failure

Returns

new instance of File

open()

File hdf5::file::open(const fs::path &path, AccessFlags flags = AccessFlags::ReadOnly, const property::FileAccessList &fapl = property::FileAccessList())

open an existing file

See also

AccessFlags

See also

FileAccessList

Parameters

• path – the path to the file to open

• flags – file open flags

• fapl – reference to a file access property list

Throws

std::runtime_error – in case of a failure

Returns

a new File instance

is_hdf5_file()

bool hdf5::file::is_hdf5_file(const fs::path &path)

check if the file reference by the path is an HDF5 file

Parameters

path – reference to the files path

Throws

std::runtime_error – in case of a failure

Returns

true if the path references an HDF5 file, false otherwise

Enumerations

AccessFlags and AccessFlagsBase

enum class hdf5::file::AccessFlags : unsigned

flags controlling file opening and creation

Values:

enumerator Truncate

enumerator Exclusive

enumerator ReadWrite

enumerator ReadOnly

enumerator SWMRRead

(since hdf5 1.10.0)

enumerator SWMRWrite

(since hdf5 1.10.0)

using hdf5::file::AccessFlagsBase = std::underlying_type<AccessFlags>::type

AccessFlagsBase hdf5::file::operator|(const AccessFlags &lhs, const AccessFlags &rhs)

AccessFlagsBase hdf5::file::operator|(const AccessFlagsBase &lhs, const AccessFlags &rhs)

AccessFlagsBase hdf5::file::operator|(const AccessFlags &lhs, const AccessFlagsBase &rhs)

AccessFlagsBase hdf5::file::operator&(const AccessFlags &lhs, const AccessFlags &rhs)

AccessFlagsBase hdf5::file::operator&(const AccessFlagsBase &lhs, const AccessFlags &rhs)

AccessFlagsBase hdf5::file::operator&(const AccessFlags &lhs, const AccessFlagsBase &rhs)

std::ostream &hdf5::file::operator<<(std::ostream &stream, const AccessFlags &flags)

SearchFlags and SearchFlagsBase

enum class hdf5::file::SearchFlags : unsigned int

flags controlling object search in a file

Values:

enumerator File

enumerator Dataset

enumerator Group

enumerator Datatype

enumerator Attribute

enumerator All

enumerator Local

using hdf5::file::SearchFlagsBase = std::underlying_type<SearchFlags>::type

SearchFlagsBase hdf5::file::operator|(const SearchFlags &lhs, const SearchFlags &rhs)

SearchFlagsBase hdf5::file::operator|(const SearchFlagsBase &lhs, const SearchFlags &rhs)

SearchFlagsBase hdf5::file::operator|(const SearchFlags &lhs, const SearchFlagsBase &rhs)

SearchFlagsBase hdf5::file::operator&(const SearchFlags &lhs, const SearchFlags &rhs)

SearchFlagsBase hdf5::file::operator&(const SearchFlagsBase &lhs, const SearchFlags &rhs)

SearchFlagsBase hdf5::file::operator&(const SearchFlags &lhs, const SearchFlagsBase &rhs)

std::ostream &hdf5::file::operator<<(std::ostream &stream, const SearchFlags &flags)

ImageFlags and ImageFlagsBase

enum class hdf5::file::ImageFlags : unsigned

flags controlling image file opening and getting

Values:

enumerator ReadOnly

enumerator ReadWrite

enumerator DontCopy

enumerator DontRelease

enumerator All

using hdf5::file::ImageFlagsBase = std::underlying_type<ImageFlags>::type

ImageFlagsBase hdf5::file::operator|(const ImageFlags &lhs, const ImageFlags &rhs)

ImageFlagsBase hdf5::file::operator|(const ImageFlagsBase &lhs, const ImageFlags &rhs)

ImageFlagsBase hdf5::file::operator|(const ImageFlags &lhs, const ImageFlagsBase &rhs)

ImageFlagsBase hdf5::file::operator&(const ImageFlags &lhs, const ImageFlags &rhs)

ImageFlagsBase hdf5::file::operator&(const ImageFlagsBase &lhs, const ImageFlags &rhs)

ImageFlagsBase hdf5::file::operator&(const ImageFlags &lhs, const ImageFlagsBase &rhs)

std::ostream &hdf5::file::operator<<(std::ostream &stream, const ImageFlags &flags)

Scope and ScopeBase

enum class hdf5::file::Scope : std::underlying_type<H5F_scope_t>::type

file scope

Values:

enumerator Local

enumerator Global

using hdf5::file::ScopeBase = std::underlying_type<Scope>::type

std::ostream &hdf5::file::operator<<(std::ostream &stream, const Scope &scope)

Driver classes

Driver

class hdf5::file::Driver

abstract class for file drivers

Driver classes in h5cpp do not hold a real reference to a driver object. They rather store information about how to setup the driver. This is mainly due to the fact that we are currently accessing the drivers only via the file access property list.

Subclassed by hdf5::file::DirectDriver, hdf5::file::MemoryDriver, hdf5::file::MPIDriver, hdf5::file::PosixDriver

Public Types

using UniquePointer = std::unique_ptr<Driver>

unique pointer type

Public Functions

virtual void operator()(const hdf5::property::FileAccessList &fapl) const = 0

set a driver

Sets a driver to a particular file access property list.

virtual DriverID id() const noexcept = 0

get driver ID

Return the ID of a particular driver.

enum class hdf5::file::DriverID : unsigned

enumeration to determine the file driver

Values:

enumerator Posix

enumerator Direct

enumerator Memory

enumerator MPI

PosixDriver

class hdf5::file::PosixDriver : public hdf5::file::Driver

Public Functions

virtual void operator()(const property::FileAccessList &fapl) const override

set a driver

Sets a driver to a particular file access property list.

virtual DriverID id() const noexcept override

get driver ID

Return the ID of a particular driver.

MemoryDriver

class hdf5::file::MemoryDriver : public hdf5::file::Driver

memory file driver

Using this driver HDF5 writes the file not to disk but in memory which can reduce the overhead from disk IO. If backing_store option is enabled the file will be written to disk with the same file name used to create the file in memory.

Public Functions

MemoryDriver() noexcept

default constructor

Sets the increment to 1MByte and backing store to false.

MemoryDriver(size_t increment, bool backing_store) noexcept

constructor

Parameters

• increment – number of bytes used to increment the memory buffer if it runs out of storage

• backing_store – enable disk storage after file close

MemoryDriver(const MemoryDriver&) = default

copy constructor

Use the default implementation here.

bool backing_store() const noexcept

get backing store status

void backing_store(bool value) noexcept

set backing store status

size_t increment() const noexcept

get increment value

void increment(size_t value)

set increment

virtual void operator()(const property::FileAccessList &fapl) const override

set a driver

Sets a driver to a particular file access property list.

virtual DriverID id() const noexcept override

get driver ID

Return the ID of a particular driver.

DirectDriver

class hdf5::file::DirectDriver : public hdf5::file::Driver

direct write without buffering (for hdf5 compiled with H5_HAVE_DIRECT)

Public Functions

DirectDriver()

default constructor

DirectDriver(size_t alignment, size_t block_size, size_t copy_buffer_size)

constructor

DirectDriver(const DirectDriver&) = default

copy constructor

size_t alignment() const noexcept

get alignment value

void alignment(size_t value)

set alignment value

Throws

std::runtime_error – in case of an error

Parameters

value – the new alignment value

size_t block_size() const noexcept

get block size

void block_size(size_t value)

set block size

Throws

std::runtime_error – in case of a failure

Parameters

value – the new block size

size_t copy_buffer_size() const noexcept

get copy buffer size

void copy_buffer_size(size_t value)

set copy buffer size

Throws

std::runtime_error – in case of a failure

Parameters

value – the new copy buffer size

virtual void operator()(const property::FileAccessList &fapl) const

set a driver

Sets a driver to a particular file access property list.

virtual DriverID id() const noexcept

get driver ID

Return the ID of a particular driver.

MPIDriver

class hdf5::file::MPIDriver : public hdf5::file::Driver

class for the MPI driver (for hdf5 with compiled MPI)

Public Functions

virtual void operator()(const property::FileAccessList &fapl) const override

set a driver

Sets a driver to a particular file access property list.

virtual DriverID id() const noexcept override

get driver ID

Return the ID of a particular driver.