h5::open | h5::create | h5::mute | h5::unmute

Detailed Description

These h5::open | h5::close | h5::create operations are to create/manipulate an hdf5 container. In POSIX sense HDF5 container is an entire image of a file system and the dataset is a document within. Datasets may be manipulated with h5::create | h5::read | h5::write | h5::append operations. While File IO operations are straight maps from already existing CAPI HDF5 calls, they are furnished with RAII, and type safety to aid productivity. How the returned managed handles may be passed to CAPI calls is governed by H5CPP conversion policy h5::mute | h5::unmute are miscellaneous thread safe calls for those rare occasions when you need to turn HDF5 CAPI error handler output off and on. Typically used when failure is information: checking existence of [dataset|path] by call-fail pattern, etc...

Function Documentation

h5::fd_t h5::create ( const std::string path,
unsigned  flags,
const h5::fcpl_t &  fcpl = h5::default_fcpl,
const h5::fapl_t &  fapl = h5::default_fapl 
)
inlinenoexcept

creates an HDF5 file with given set of properties and returns a managed h5::fd_t resource handle. Depending on active conversion policy h5::fd_t may be passed implicitly,explicitly or not at all to HDF5 CAPI calls.

Parameters
file_paththe location where the hdf5 container is created within the OS file system.
flagsFile create flags: (H5F_ACC_TRUNC | H5F_ACC_EXCL ) | H5F_ACC_DEBUG
fcplfile creation property list identifier, used when modifying default file meta-data
faplfile access property list identifier:
Returns
an open h5::fd_t descriptor
See also
h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip
RAII static_cast std::unique_ptr std::runtime_error
{
auto fd = h5::create("example.h5", H5F_ACC_TRUNC ); // create file and save descriptor
H5Dcreate(fd, ... ); // CAPI call with implicit conversion
H5Dcreate(static_cast<hid_t>(fd), ...); // or explicit cast
h5::fd_t fd_2 = h5::create("other.h5", // thin smart pointer like RAII support
H5F_ACC_EXCL | H5F_ACC_DEBUG, // CAPI arguments are implicitly converted
H5P_DEFAULT, H5P_DEFAULT ); // if enabled
}
{ // DON'Ts: assign returned smart pointer to hid_t directly, becuase
// underlying handle gets assigned to, then the smart pointer closes backing
// resource as it goes out of scope:
// hid_t fd = h5::create("example.h5", H5_ACC_TRUNC); // fd is now invalid
//
// DOs: capture smart pointer only when you use it, then pass it to CAPI
// if it were an hid_t, or use static_cast<> to signal intent
auto fd = h5::create("example.h5", H5_ACC_TRUNC); // instead, do this
H5Dopen(fd, "mydataset", ... ); // if implicit cast enabled, or
H5Dcreate(static_cast<hid_t>(fd), ...); // when explicit cast enforced
hid_t capi_fd = static_cast<hid_t>( fd ); // also fine, intent is clear
}
h5::fd_t h5::open ( const std::string path,
unsigned  flags,
const h5::fapl_t &  fapl = h5::default_fapl 
)
inline

opens an existing HDF5 file, the returned h5::fd_t descriptor automatically closes backed resource when leaving code block The h5::fd_t is a thin hid_t size object with std::unique_ptr like properties.

Parameters
file_paththe location where the hdf5 container is created within the OS file system.
flagsFile open flags: (H5F_ACC_RDWR | H5F_ACC_RDONLY)
faplfile access property list identifier:
Returns
an open h5::fd_t descriptor
See also
h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip
RAII static_cast std::unique_ptr std::runtime_error
{
h5::fd_t fd = h5::open("example.h5", H5F_ACC_RDWR); // open an hdf5 file
... // do some work
} // underlying hid_t is closed when leaving code block
Examples:
arma.cpp, blaze.cpp, blitz.cpp, dlib.cpp, eigen3.cpp, itpp.cpp, and ublas.cpp.
h5::ds_t h5::open ( const fd_t &  fd,
const std::string path,
const h5::dapl_t &  dapl = h5::default_dapl 
)
inline

open an existing dataset/document within an valid HDF5 file, the returned handle automatically closed when leaving code block

Parameters
fdvalid h5::fd_t file descriptor
dataset_paththe location of the dataset/document within HDF5 container
dapldata access property list identifier
Returns
an open h5::fd_t descriptor
See also
h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip
RAII static_cast std::unique_ptr std::runtime_error
{
h5::fd_t fd = h5::open("example.h5", H5F_ACC_RDWR); // open an hdf5 file in read-write mode
h5::ds_t ds = h5::open(fd,"dataset.txt") // obtain ds descriptor
... // do some work
} // ds and fd closes automatically
void h5::close ( h5::fd_t &  fd)
inline

A dummy call, to facilitate open-do some work - close pattern

Parameters
fdvalid h5::fd_t file descriptor
See also
h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip
RAII static_cast std::unique_ptr std::runtime_error
h5::fd_t fd = h5::open("example.h5", H5F_ACC_RDWR); // returned descriptor automatically
... // do some work
h5::close(fd); // dummy call for symmetry
Examples:
compound.cpp.
void h5::mute ( )
inline

removes default error handler preventing diagnostic error messages printed for direct CAPI calls. This is a thread safe implementation. Read on Error Handling/Exceptions

See also
h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t
H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip
RAII static_cast std::unique_ptr std::runtime_error
h5::mute(); // mute error handling
... H5?xxx calls ... // do your capi calls which output annoying error messages
h5::unmute(); // restore previously saved handler
void h5::unmute ( )
inline

restores previously saved error handler with h5::mute Read on Error Handling/Exceptions

@code
h5::mute(); // mute error handling
... H5?xxx calls ... // do your capi calls which output annoying error messages
h5::unmute(); // restore previously saved handler