HDF5 files

Detailed Description

Create, open, and close an HDF5 container. In POSIX terms an HDF5 container is the entire image of a file system and the dataset is a document within. Datasets are manipulated via h5::create / h5::read / h5::write / h5::append. File operations map directly onto HDF5 CAPI calls but are furnished with RAII and type safety. How the returned managed handles may be passed to CAPI calls is governed by the H5CPP conversion policy. h5::mute | h5::unmute are miscellaneous thread-safe calls for the rare occasions when you need to turn HDF5 CAPI error-handler output off and on — typically used when failure is information (checking existence of a dataset / path by the call-fail pattern, etc.).

See also

H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI

Function Documentation

open() [1/2]

h5::ds_t h5::open ( const h5::fd_t&  fd, const std::string&  path, const h5::dapl_t&  dapl = h5::default_dapl  )

inline

Open an existing HDF5 dataset by path.

Returns an RAII-managed h5::ds_t handle; the underlying CAPI id is closed via H5Dclose on scope exit. Use h5::read<T>(ds, ...) to fetch values or h5::write(ds, ...) to update them.

If the dataset's creation property list carries the h5cpp high-throughput pipeline tag (H5CPP_DAPL_HIGH_THROUGHPUT), the pipeline's per-chunk cache is initialised here from the dataset's element size, so subsequent reads/writes pick up the pre-warmed filter chain transparently.

Parameters

fd	valid open h5::fd_t file descriptor
path	path to the HDF5 object (file path for file open/create; dataset path for dataset open)
dapl	dataset access property list (h5::dapl_t)

Returns

open h5::ds_t dataset descriptor; throws h5::error on failure

Exceptions

h5::error::io::dataset::open

on H5Dopen2 failure (dataset does not exist, file not opened for read, invalid dapl).

example:

h5::fd_t fd = h5::open("example.h5", H5F_ACC_RDWR);
h5::ds_t ds = h5::open(fd, "/grid/data");
auto v = h5::read<std::vector<float>>(ds);
// ds, fd close automatically on scope exit

See also

h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t

H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI

h5::create h5::read h5::write Handles, Descriptors, and Property Lists

mute()

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 CAPI

RAII pointers static_cast std::runtime_error std::unique_ptr

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

Examples

attributes.cpp, basics.cpp, and groups.cpp.

unmute()

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

Examples

attributes.cpp, basics.cpp, and groups.cpp.

create()

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  )

inline

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

path	path to the HDF5 object (file path for file open/create; dataset path for dataset open)
flags	file create flags: H5F_ACC_TRUNC | H5F_ACC_EXCL | H5F_ACC_DEBUG
fcpl	file creation property list — controls file meta-data layout
fapl	file access property list — controls file driver and parallel I/O settings

Returns

open h5::fd_t file descriptor; throws h5::error on failure

See also

h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t

H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI

RAII pointers static_cast std::runtime_error std::unique_ptr

{ 
   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 
}                                                       

open() [2/2]

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

path	path to the HDF5 object (file path for file open/create; dataset path for dataset open)
flags	file open flags: H5F_ACC_RDWR | H5F_ACC_RDONLY
fapl	file access property list — controls file driver and parallel I/O settings

Returns

open h5::fd_t file descriptor; throws h5::error on failure

See also

h5::open h5::read h5::write h5::fd_t h5::ds_t h5::err_t

H5Fcreate H5Fopen H5Fclose H5Dopen H5Dclose gzip CAPI

RAII pointers static_cast std::runtime_error std::unique_ptr

{
   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