Basic H5CPP Operations

This example shows the small core of H5CPP: typed descriptors, RAII-managed HDF5 handles, composable property lists, error handling, file creation, and dataset creation. The point is simple: keep the HDF5 C API available, but make the common path look like C++.

Files

File	Purpose
basic.cpp	Demonstrates basic H5CPP operations
001.h5	Minimal file creation example
002.h5	File creation with custom creation properties
003.h5	File creation using raw HDF5 default property lists
004.h5	Dataset creation examples

Include

#include <h5cpp/all>
#include <cstddef>

h5cpp/all pulls in the high-level H5CPP API, wrappers, property-list helpers, and type mappings.

Type Descriptors

H5CPP maps C++ types to HDF5 datatype descriptors through templates.

h5::dt_t<int> my_int_type;
hid_t capi_style_id = static_cast<hid_t>(my_int_type);

h5::dt_t<int> creates a managed copy of H5T_NATIVE_INT.

The descriptor behaves like the other H5CPP handles:

• it owns the HDF5 resource;
• it closes automatically when it leaves scope;
• it can be cast to hid_t for C API interop;
• the casted hid_t must be treated as borrowed, not manually closed.

H5CPP_CHECK_EQ(
    H5Tequal(capi_style_id, H5T_NATIVE_INT), std::runtime_error, "HDF5 type system failure!!!");

Types also have compile-time and runtime names:

std::cout << h5::name<int>::value << std::endl;
std::cout << my_int_type << std::endl;

For custom types, register a mapping:

H5CPP_REGISTER_TYPE(C_COMPOUND_TYPE, HDF5_COMPOUND_TYPE)

For POD compound types, this is usually generated by the H5CPP compiler.

Property Lists

Property lists are ordinary H5CPP objects, but small configuration fragments can be composed with |.

h5::dcpl_t dcpl = h5::chunk{12} | h5::gzip{2};

They can also be merged:

h5::dcpl_t dcpl0 = h5::chunk{12} | h5::gzip{2};
h5::dcpl_t dcpl1 = h5::chunk{12} | h5::gzip{2};
 
h5::dcpl_t dcpl = dcpl0 | dcpl1;
dcpl0 |= dcpl1;

Common examples:

h5::fcpl_t fcpl = h5::file_space_page_size{4096} | h5::userblock{512}; // file control property list
h5::fapl_t fapl = h5::fclose_degree_weak | h5::stdio;                  // file access property list
h5::dcpl_t dcpl = h5::chunk{2, 3} | h5::fill_value<short>{42}          // data control property list
  | h5::fletcher32 | h5::shuffle | h5::nbit | h5::gzip{9};             
h5::lcpl_t lcpl = h5::create_path | h5::utf8;                          // link control property list 

Defaults are available as h5::default_fcpl, h5::default_fapl, h5::default_lcpl, h5::default_dcpl, and similar.

Error Handling

HDF5 prints its own diagnostic stack by default. For expected failures, mute it temporarily and catch the H5CPP exception.

h5::mute(); // hush HDF5 CAPI diagnostin messages
try {
    h5::dcpl_t dcpl = h5::gzip{79798}; // invalid gzip level
} catch (const h5::error::any& err) {
    std::cerr << "THIS ERROR is on PURPOSE: " << err.what() << std::endl;
}
h5::unmute(); // restore the diagnostincs

This keeps intentional error tests from spraying noise onto stderr.

RAII Handles

All H5CPP handles own HDF5 resources.

{
    h5::fd_t fd = h5::create("001.h5", H5F_ACC_TRUNC);
    hid_t ref = static_cast<hid_t>(fd);
    (void)ref;
    // Do not call H5Fclose(ref).
}

When fd leaves scope, H5CPP calls the matching HDF5 close function. The hid_t cast exists for C API interop. Treat it as a managed reference.

Creating Files

Basic file creation:

auto fd = h5::create("001.h5", H5F_ACC_TRUNC);

Create with file creation properties:

auto fd = h5::create(
    "002.h5",
    H5F_ACC_TRUNC,
    h5::file_space_page_size{4096}
  | h5::userblock{512}
);

You can also pass raw HDF5 property-list identifiers:

h5::create("003.h5", H5F_ACC_TRUNC, H5P_DEFAULT, H5P_DEFAULT);

The file handle closes automatically when it leaves scope.

Creating Datasets

Create a dataset with explicit current dimensions, maximum dimensions, link creation properties, dataset creation properties, and dataset access properties:

auto fd = h5::create("004.h5", H5F_ACC_TRUNC);
auto ds = h5::create<short>( fd, "/type/short/tree_0", h5::current_dims{10, 20}, h5::max_dims{10, H5S_UNLIMITED},
      h5::create_path | h5::utf8, h5::chunk{2, 3} | h5::fill_value<short>{42} 
    | h5::fletcher32 | h5::shuffle | h5::nbit | h5::gzip{9}, h5::default_dapl );

h5::create_path creates missing intermediate groups. h5::utf8 marks link names as UTF-8.

The same operation can be written with a named dataset creation property list:

h5::dcpl_t dcpl = h5::chunk{2, 3} | h5::fill_value<short>{42} | h5::fletcher32 | h5::shuffle | h5::nbit | h5::gzip{2};
auto ds = h5::create<short>( fd, "/type/short/tree_1",
    h5::current_dims{10, 20}, h5::max_dims{10, H5S_UNLIMITED}, dcpl );

Or with defaults made explicit:

auto ds = h5::create<short>( fd, "/type/short/tree_2",
    h5::current_dims{10, 20}, h5::max_dims{10, H5S_UNLIMITED}, h5::default_lcpl, dcpl, h5::default_dapl );

Unlimited Dimensions

If only max_dims is given, H5CPP derives the current dimensions from it. For unlimited dimensions, the current size starts at zero:

auto ds = h5::create<short>( fd, "/type/short/max_dims", h5::max_dims{10, H5S_UNLIMITED}, h5::chunk{10, 1} );

This creates a dataset with logical shape:

10 x 0

That is useful for append-style storage such as packet tables.

---

Minimal Pattern

The basic H5CPP workflow is:

auto fd = h5::create("data.h5", H5F_ACC_TRUNC);
auto ds = h5::create<double>( fd, "/path/to/dataset",
    h5::current_dims{100, 4}, h5::chunk{10, 4} | h5::gzip{2} );

That is the core idea:

C++ type + HDF5 path + dimensions + optional properties -> managed HDF5 dataset

No manual H5Tclose, H5Sclose, H5Pclose, H5Dclose, or H5Fclose on the normal path.

Source

• basics.cpp — rendered with syntax highlighting