objects

C++ API

HDF5 handlers and C++ RAII

All types are wrapped into h5::impl::hid_t<T> template then

1 T := [ file_handles | property_list ]
2 file_handles := [ fd_t | ds_t | att_t | err_t | grp_t | id_t | obj_t ]
3 property_lists := [ file | group | link | dataset | type | object | attrib | access ]
4 
5 # create access transfer copy
6 file := [fcpl_t | fapl_t ]
7 group := [gcpl_t | gapl_t ]
8 link := [lcpl_t | lapl_t ]
9 dataset := [dcpl_t | dapl_t | dtpl_t ]
10 type := [ tapl_t ]
11 object := [ocpl_t | ocpyl_t ]
12 attrib := [acpl_t

C/C++ type map to HDF5 file space

1 integral := [ unsigned | signed ] [int_8 | int_16 | int_32 | int_64 | float | double ]
2 vectors := *integral
3 rugged_arrays := **integral
4 string := **char
5 linalg := armadillo | eigen |
6 scalar := integral | pod_struct | string
7 
8 # not handled yet: long double, complex, specialty types

scalars: are integral types and take up a

Support for STL

currently std::vector and std::string

TODO: write detailed description of supported types, and how memory space is mapped to file space

Support for Popular Scientific Libraries

operations [create | read | write] has been implemented with zero-copy whenever passed by reference. In case of direct read operations when the requested object is assigned, the object is created only once, because of copy elision. this mechanism is useful when sketching out idea's and your focus is on the flow as opposed to performance.

// copy-elision or return value optimization:RVO
arma::mat rvo = h5::read<arma::mat>(fd, "path_to_object");

For high performance operations: within loops or sub routines, choose the function prototypes that takes reference to already created objects, then update the content with partial IO call.

h5::ds_t ds = h5::open( ... ) // open dataset
arma::mat M(n_rows,n_cols); // create placeholder, data-space is reserved on the heap
h5::count_t count{n_rows,n_cols}; // describe the memory region you are reading into
h5::offset_t offset{0,0}; // position we reasing data from
// high performance loop with minimal memory operations
for( auto i: column_indices )
h5::read(ds, M, count, offset); // count, offset and other proeprties may be speciefied in any order
1 T := ([unsigned] ( int8_t | int16_t | int32_t | int64_t )) | ( float | double )
2 S := T | c/c++ struct | std::string
3 ref := std::vector<S>
4  | arma::Row<T> | arma::Col<T> | arma::Mat<T> | arma::Cube<T>
5  | Eigen::Matrix<T,Dynamic,Dynamic> | Eigen::Matrix<T,Dynamic,1> | Eigen::Matrix<T,1,Dynamic>
6  | Eigen::Array<T,Dynamic,Dynamic> | Eigen::Array<T,Dynamic,1> | Eigen::Array<T,1,Dynamic>
7  | blaze::DynamicVector<T,rowVector> | blaze::DynamicVector<T,colVector>
8  | blaze::DynamicVector<T,blaze::rowVector> | blaze::DynamicVector<T,blaze::colVector>
9  | blaze::DynamicMatrix<T,blaze::rowMajor> | blaze::DynamicMatrix<T,blaze::colMajor>
10  | itpp::Mat<T> | itpp::Vec<T>
11  | blitz::Array<T,1> | blitz::Array<T,2> | blitz::Array<T,3>
12  | dlib::Matrix<T> | dlib::Vector<T,1>
13  | ublas::matrix<T> | ublas::vector<T>
14 ptr := T*
15 accept := ref | ptr

Here is the chart how supported linalg systems implement acessors, memory layout

1  data num elements vec mat:rm mat:cm cube
2 -------------------------------------------------------------------------------------------------------------------------
3 eigen {.data()} {size()} {rows():1,cols():0} {cols():0,rows():1} {n/a}
4 arma {.memptr()} {n_elem} {n_rows:0,n_cols:1} {n_slices:2,n_rows:0,n_cols:1}
5 blaze {.data()} {n/a} {columns():1,rows():0} {rows():0,columns():1} {n/a}
6 blitz {.data()} {size()} {cols:1, rows:0} {slices:2, cols:1,rows:0}
7 itpp {._data()} {length()} {cols():1,rows():0}
8 ublas {.data().begin()} {n/a} {size2():1, size1():0}
9 dlib {&ref(0,0)} {size()} {nc():1, nr():0}