Object-oriented Scientific Computing Library: Version 0.910
Public Member Functions | Protected Member Functions | Protected Attributes
hdf_file Class Reference

Store data in an HDF5 file. More...

#include <hdf_file.h>


Detailed Description

The member functions which write or get data from an HDF file begin with either get or set. Where appropriate, the next character is either c for character, d for double, f for float, or i for int.

The get functions are:

The set functions are:

The string I/O functions:

The vector I/O functions:

The matrix I/O functions:

By default, vectors and matrices are written to HDF files in a chunked format, so their length can be changed later as necessary. The chunk size is chosen in def_chunk() to be the closest power of 10 to the current vector size.

All files not closed by the user are closed in the destructor, but the destructor does not automatically close groups.

Warning:
This class is still in development. Because of this, hdf5 files generated by this class may not be easily read by future versions. Later versions of O2scl will have stronger guarantees on backwards compatibility.
Todo:
Error handling with HDF functions is a particular concern. Modify to throw O2scl exceptions when appropriate.
Idea for Future:
Automatically close groups, e.g. by storing hid_t's in a stack?

Definition at line 94 of file hdf_file.h.

Public Member Functions

int getd_ten3 (std::string name, o2scl::tensor3 &t3)
 Desc.
Open and close files
int open (std::string fname)
 Open a file named fname.
int close ()
 Close the file.
Manipulate ids
hid_t get_file_id ()
 Get the current file id.
int set_current_id (hid_t cur)
 Set the current working id.
hid_t get_current_id ()
 Retrieve the current working it.
Set functions
int setc (std::string name, char c)
 Set a character named name to value d.
int setd (std::string name, double d)
 Set a double named name to value d.
int setf (std::string name, float f)
 Set a float named name to value d.
int seti (std::string name, int i)
 Set an integer named name to value d.
int sets (std::string name, std::string s)
 Set a string named name to value s.
int sets_fixed (std::string name, std::string s)
 Set a string named name to value s.
Group manipulation
hid_t open_group (hid_t init_id, std::string path)
 Open a group relative to the location specified in init_id.
hid_t open_group (std::string path)
 Open a group relative to the current location.
int close_group (hid_t group)
 Close a previously created group.
Vector set functions

These functions automatically write all of the vector elements to the HDF file, if necessary extending the data that is already present.

int setd_vec (std::string name, const std::vector< double > &v)
 Set vector dataset named name with v.
int setd_vec (std::string name, const o2scl::ovector_const_view &v)
 Set vector dataset named name with v.
int setd_vec (std::string name, const o2scl::uvector_const_view &v)
 Set vector dataset named name with v.
int seti_vec (std::string name, const std::vector< int > &v)
 Set vector dataset named name with v.
int seti_vec (std::string name, const o2scl::ovector_int_const_view &v)
 Set vector dataset named name with v.
int seti_vec (std::string name, const o2scl::uvector_int_const_view &v)
 Set vector dataset named name with v.
Vector get functions

These functions automatically free any previously allocated memory in v and then allocate the proper space required to read the information from the HDF file.

int getd_vec (std::string name, std::vector< double > &v)
 Get vector dataset and place data in v.
int getd_vec (std::string name, o2scl::ovector &v)
 Get vector dataset and place data in v.
int getd_vec (std::string name, o2scl::uvector &v)
 Get vector dataset and place data in v.
int geti_vec (std::string name, std::vector< int > &v)
 Get vector dataset and place data in v.
int geti_vec (std::string name, o2scl::ovector_int &v)
 Get vector dataset and place data in v.
int geti_vec (std::string name, o2scl::uvector_int &v)
 Get vector dataset and place data in v.
Matrix set functions

These functions automatically write all of the vector elements to the HDF file, if necessary extending the data that is already present.

int setd_mat (std::string name, const o2scl::omatrix_const_view &m)
 Set matrix dataset named name with m.
int setd_mat (std::string name, const o2scl::umatrix_const_view &m)
 Set matrix dataset named name with m.
int seti_mat (std::string name, const o2scl::omatrix_int_const_view &m)
 Set matrix dataset named name with m.
int seti_mat (std::string name, const o2scl::umatrix_int_const_view &m)
 Set matrix dataset named name with m.
Matrix get functions

These functions automatically free any previously allocated memory in m and then allocate the proper space required to read the information from the HDF file.

int getd_mat (std::string name, o2scl::omatrix &m)
 Get matrix dataset and place data in m.
int getd_mat (std::string name, o2scl::umatrix &m)
 Get matrix dataset and place data in m.
int geti_mat (std::string name, o2scl::omatrix_int &m)
 Get matrix dataset and place data in m.
int geti_mat (std::string name, o2scl::umatrix_int &m)
 Get matrix dataset and place data in m.
Array set functions
int setc_arr (std::string name, size_t n, const char *c)
 Set a character array named name of size n to value c.
int setd_arr (std::string name, size_t n, const double *d)
 Set a double array named name of size n to value d.
int setf_arr (std::string name, size_t n, const float *f)
 Set a float array named name of size n to value f.
int seti_arr (std::string name, size_t n, const int *i)
 Set a integer array named name of size n to value i.
int sets_arr (std::string name, std::vector< std::string > &s)
 Set a vector of strings named name.
Fixed-length array set functions

If a dataset named name is already present, then the user-specified array must not be longer than the array already present in the HDF file.

int setc_arr_fixed (std::string name, size_t n, const char *c)
 Set a character array named name of size n to value c.
int setd_arr_fixed (std::string name, size_t n, const double *c)
 Set a double array named name of size n to value d.
int setf_arr_fixed (std::string name, size_t n, const float *f)
 Set a float array named name of size n to value f.
int seti_arr_fixed (std::string name, size_t n, const int *i)
 Set an integer array named name of size n to value i.
Get functions

If the specified object is not found, the O2scl error handler will be called.

int getc (std::string name, char &c)
 Get a character named name.
int getd (std::string name, double &d)
 Get a double named name.
int getf (std::string name, float &f)
 Get a float named name.
int geti (std::string name, int &i)
 Get a integer named name.
int gets (std::string name, std::string &s)
 Get a string named name.
int gets_fixed (std::string name, std::string &s)
 Get a string named name.
int gets_def_fixed (std::string name, std::string def, std::string &s)
 Get a string named name.
Array get functions

All of these functions (except gets_arr()) assume that the pointer allocated beforehand, and matches the size of the array in the HDF file. If the specified object is not found, the O2scl error handler will be called.

int getc_arr (std::string name, size_t n, char *c)
 Get a character array named name of size n.
int getd_arr (std::string name, size_t n, double *d)
 Get a double array named name of size n.
int getf_arr (std::string name, size_t n, float *f)
 Get a float array named name of size n.
int geti_arr (std::string name, size_t n, int *i)
 Get an integer array named name of size n.
int gets_arr (std::string name, std::vector< std::string > &s)
 Get a string array named name and store it in s.
Array get functions with memory allocation

These functions allocate memory with new, which should be freed by the user with delete .

int getc_arr_alloc (std::string name, size_t &n, char *c)
 Get a character array named name of size n.
int getd_arr_alloc (std::string name, size_t &n, double *d)
 Get a double array named name of size n.
int getf_arr_alloc (std::string name, size_t &n, float *f)
 Get a float array named name of size n.
int geti_arr_alloc (std::string name, size_t &n, int *i)
 Get an integer array named name of size n.
Get functions with default values

If the requested dataset is not found in the HDF file, the object is set to the specified default value and the error handler is not called.

int getc_def (std::string name, char def, char &c)
 Get a character named name.
int getd_def (std::string name, double def, double &d)
 Get a double named name.
int getf_def (std::string name, float def, float &f)
 Get a float named name.
int geti_def (std::string name, int def, int &i)
 Get a integer named name.
int gets_def (std::string name, std::string def, std::string &s)
 Get a string named name.
Get functions with pre-allocated pointer
int getd_vec_prealloc (std::string name, size_t n, double *d)
 Get a double array d pre-allocated to have size n.
int geti_vec_prealloc (std::string name, size_t n, int *i)
 Get an integer array i pre-allocated to have size n.
int getd_mat_prealloc (std::string name, size_t n, size_t m, double *d)
 Get a double matrix d pre-allocated to have size (n,m)
int geti_mat_prealloc (std::string name, size_t n, size_t m, int *i)
 Get an integer matrix i pre-allocated to have size (n,m)

Protected Member Functions

virtual hsize_t def_chunk (size_t n)
 Default chunk size.

Protected Attributes

hid_t file
 File ID.
bool file_open
 True if a file has been opened.
hid_t current
 Current file or group location.

Member Function Documentation

virtual hsize_t hdf_file::def_chunk ( size_t  n) [inline, protected, virtual]

Choose the closest power of 10 which is greater than or equal to 10 and less than or equal to $ 10^6 $.

Definition at line 114 of file hdf_file.h.

int hdf_file::sets ( std::string  name,
std::string  s 
)

The string is stored in the HDF file as an extensible character array rather than a string.

int hdf_file::sets_fixed ( std::string  name,
std::string  s 
)

This function stores s as a fixed-length string in the HDF file. If a dataset named name is already present, then s must not be longer than the string length already specified in the HDF file.

hid_t hdf_file::open_group ( hid_t  init_id,
std::string  path 
)
Note:
In order to ensure that future objects are written to the newly-created group, the user must use set_current_id() using the newly-created group ID for the argument.
hid_t hdf_file::open_group ( std::string  path)
Note:
In order to ensure that future objects are written to the newly-created group, the user must use set_current_id() using the newly-created group ID for the argument.
int hdf_file::setd_vec ( std::string  name,
const o2scl::ovector_const_view v 
)
Note:
In the case that the stride of the vector v is not unity, this function requires copying the data twice: once from the vector to a pointer, and once from the pointer to the file. Keep this in mind when performing I/O with larger data sets.
int hdf_file::seti_vec ( std::string  name,
const o2scl::ovector_int_const_view v 
)
Note:
In the case that the stride of the vector v is not unity, this function requires copying the data twice: once from the vector to a pointer, and once from the pointer to the file. Keep this in mind when performing I/O with larger data sets.
int hdf_file::setd_mat ( std::string  name,
const o2scl::omatrix_const_view m 
)
Note:
In the case that the trailing dimension (as reported by omatrix_const_view_tlate::tda() ) of the matrix m is greater than the number of columns, this function requires copying the data twice: once from the matrix to a pointer, and once from the pointer to the file. Keep this in mind when performing I/O with larger data sets.
int hdf_file::seti_mat ( std::string  name,
const o2scl::omatrix_int_const_view m 
)
Note:
In the case that the trailing dimension (as reported by omatrix_const_view_tlate::tda() ) of the matrix m is greater than the number of columns, this function requires copying the data twice: once from the matrix to a pointer, and once from the pointer to the file. Keep this in mind when performing I/O with larger data sets.
int hdf_file::sets_arr ( std::string  name,
std::vector< std::string > &  s 
)

Developer note:

String vectors are reformatted as a single character array, in order to allow each string to have different length and to make each string extensible. The size of the vector s is stored as an integer named nw.

int hdf_file::gets ( std::string  name,
std::string &  s 
)
Note:
Strings are stored as character arrays and thus retrieving a string from a file requires loading the information from the file into a character array, and then copying it to the string. This will be slow for very long strings.
int hdf_file::getc_arr ( std::string  name,
size_t  n,
char *  c 
)
Note:
The pointer c must be allocated beforehand to hold n entries, and n must match the size of the array in the HDF file.
int hdf_file::getd_arr ( std::string  name,
size_t  n,
double *  d 
)
Note:
The pointer d must be allocated beforehand to hold n entries, and n must match the size of the array in the HDF file.
int hdf_file::getf_arr ( std::string  name,
size_t  n,
float *  f 
)
Note:
The pointer f must be allocated beforehand to hold n entries, and n must match the size of the array in the HDF file.
int hdf_file::geti_arr ( std::string  name,
size_t  n,
int *  i 
)
Note:
The pointer i must be allocated beforehand to hold n entries, and n must match the size of the array in the HDF file.

The documentation for this class was generated from the following file:
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Documentation generated with Doxygen. Provided under the GNU Free Documentation License (see License Information).

Get Object-oriented Scientific Computing
Lib at SourceForge.net. Fast, secure and Free Open Source software
downloads.