H5Lite Class Reference

Class to bring together some high level methods to read/write data to HDF5 files. More...

List of all members.

Static Public Member Functions

static MXA_EXPORT void disableErrorHandlers ()
 Turns off the global error handler/reporting objects. Note that once they are turned off using this method they CAN NOT be turned back on. If you would like to turn them off for a piece of code then surround your code with the HDF_ERROR_HANDLER_OFF and HDF_ERROR_HANDLER_ON macros defined in H5Lite.h.
static MXA_EXPORT herr_t openId (hid_t loc_id, const std::string &objName, int32 obj_type)
 Opens an object for HDF5 operations.
static MXA_EXPORT herr_t closeId (hid_t obj_id, int32 obj_type)
 Opens an HDF5 Object.
static hid_t HDFTypeFromString (const std::string &value)
 Given one of the HDF Types as a string, this will return the HDF Type as an hid_t value.
static std::string StringForHDFType (hid_t type)
 Returns a string version of the HDF Type.
template<typename T>
static std::string HDFTypeForPrimitiveAsStr (T value)
 Returns the HDF Type for a given primitive value.
template<typename T>
static hid_t HDFTypeForPrimitive (T value)
 Returns the HDF Type for a given primitive value.
static MXA_EXPORT herr_t findAttribute (hid_t loc_id, const std::string &attrName)
 Inquires if an attribute named attr_name exists attached to the object loc_id.
static MXA_EXPORT herr_t findDataset (hid_t loc_id, const std::string &name)
 Finds a Data set given a data set name.
template<typename T>
static herr_t writeVectorDataset (hid_t loc_id, const std::string &dsetName, std::vector< hsize_t > &dims, std::vector< T > &data)
 Creates a Dataset with the given name at the location defined by loc_id.
template<typename T>
static herr_t writePointerDataset (hid_t loc_id, const std::string &dsetName, int32 rank, hsize_t *dims, T *data)
 Writes the data of a pointer to an HDF5 file.
template<typename T>
static herr_t writeDataset (hid_t loc_id, const std::string &dsetName, int32 &rank, hsize_t *dims, T *data)
 Creates a Dataset with the given name at the location defined by loc_id.
template<typename T>
static herr_t writeScalarDataset (hid_t loc_id, const std::string &dsetName, T &value)
 Creates a Dataset with the given name at the location defined by loc_id. This version of writeDataset should be used with a single scalar value. If you need to write an array of values, use the form that takes an std::vector<>.
static MXA_EXPORT herr_t writeStringDataset (hid_t loc_id, const std::string &dsetName, const std::string &data)
 Writes a std::string as a HDF Dataset.
static MXA_EXPORT herr_t writeStringDataset (hid_t loc_id, const std::string &dsetName, size_t size, const char *data)
 Writes a null terminated 'C String' to an HDF Dataset.
template<typename T>
static herr_t writePointerAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, int32 rank, uint64 *dims, T *data)
 Writes an Attribute to an HDF5 Object.
template<typename T>
static herr_t writeVectorAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, std::vector< uint64 > &dims, std::vector< T > &data)
 Writes an Attribute to an HDF5 Object.
static MXA_EXPORT herr_t writeStringAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, const std::string &data)
 Writes a string as a null terminated attribute.
static MXA_EXPORT herr_t writeStringAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, hsize_t size, const char *data)
 Writes a null terminated string as an attribute.
static MXA_EXPORT herr_t writeStringAttributes (hid_t loc_id, const std::string &objName, const std::map< std::string, std::string > &attributes)
 Writes attributes that all have a data type of STRING. The first value in each set is the key, the second is the actual value of the attribute.
template<typename T>
static herr_t writeScalarAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, T data)
 Writes an attribute to the given object. This method is designed with a Template parameter that represents a primitive value. If you need to write an array, please use the other over loaded method that takes a vector.
template<typename T>
static herr_t readPointerDataset (hid_t loc_id, const std::string &dsetName, T *data)
 Reads data from the HDF5 File into a preallocated array.
template<typename T>
static herr_t readVectorDataset (hid_t loc_id, const std::string &dsetName, std::vector< T > &data)
 Reads data from the HDF5 File into an std::vector<T> object. If the dataset is very large this can be an expensive method to use. It is here for convenience using STL with hdf5.
template<typename T>
static herr_t readScalarDataset (hid_t loc_id, const std::string &dsetName, T &data)
 Reads a dataset that consists of a single scalar value.
static MXA_EXPORT herr_t readStringDataset (hid_t loc_id, const std::string &dsetName, std::string &data)
 Reads a string dataset into the supplied string.
static MXA_EXPORT herr_t readStringDataset (hid_t loc_id, const std::string &dsetName, uint8 *data)
 reads a nullterminated string dataset into the supplied buffer. The buffer should be already preallocated.
template<typename T>
static herr_t readVectorAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, std::vector< T > &data)
 Reads an Attribute from an HDF5 Object.
template<typename T>
static herr_t readScalarAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, T &data)
 Reads a scalar attribute value from a dataset.
template<typename T>
static herr_t readPointerAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, T *data)
 Reads the Attribute into a pre-allocated pointer.
static MXA_EXPORT herr_t readStringAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, std::string &data)
 Reads a string attribute from an HDF object.
static MXA_EXPORT herr_t readStringAttribute (hid_t loc_id, const std::string &objName, const std::string &attrName, uint8 *data)
 Reads a string attribute from an HDF object into a precallocated buffer.
static MXA_EXPORT hid_t getAttributeNDims (hid_t loc_id, const std::string &objName, const std::string &attrName, hid_t &rank)
 Returns the number of dimensions for a given attribute.
static MXA_EXPORT hid_t getDatasetNDims (hid_t loc_id, const std::string &objName, hid_t &rank)
 Returns the number of dimensions for a given dataset.
static MXA_EXPORT hid_t getDatasetType (hid_t loc_id, const std::string &dsetName)
 Returns the H5T value for a given dataset.
static MXA_EXPORT herr_t getDatasetInfo (hid_t loc_id, const std::string &dsetName, std::vector< hsize_t > &dims, H5T_class_t &type_class, size_t &type_size)
 Get the information about a dataset.
static MXA_EXPORT herr_t getAttributeInfo (hid_t loc_id, const std::string &objName, const std::string &attr_name, std::vector< uint64 > &dims, H5T_class_t &type_class, size_t &type_size, hid_t &attr_type)
 Returns the information about an attribute. You must close the attributeType argument or resource leaks will occur. Use H5Tclose(attr_type); after your call to this method if you do not need the id for anything.

Protected Member Functions

 H5Lite ()
 ~H5Lite ()

Private Member Functions

void NEVER_USED ()


Detailed Description

Class to bring together some high level methods to read/write data to HDF5 files.

Author:
Mike Jackson
Date:
April 2007
Version:
Revision
1.3


Constructor & Destructor Documentation

H5Lite::H5Lite (  )  [protected]

H5Lite::~H5Lite (  )  [protected]


Member Function Documentation

static MXA_EXPORT void H5Lite::disableErrorHandlers (  )  [static]

Turns off the global error handler/reporting objects. Note that once they are turned off using this method they CAN NOT be turned back on. If you would like to turn them off for a piece of code then surround your code with the HDF_ERROR_HANDLER_OFF and HDF_ERROR_HANDLER_ON macros defined in H5Lite.h.

static MXA_EXPORT herr_t H5Lite::openId ( hid_t  loc_id,
const std::string &  objName,
int32  obj_type 
) [static]

Opens an object for HDF5 operations.

Parameters:
loc_id The parent object that holds the true object we want to open
objName The string name of the object
obj_type The HDF5_TYPE of object
Returns:
Standard HDF5 Error Conditions

static MXA_EXPORT herr_t H5Lite::closeId ( hid_t  obj_id,
int32  obj_type 
) [static]

Opens an HDF5 Object.

Parameters:
obj_id The Object id
obj_type Basic Object Type
Returns:
Standard HDF5 Error Conditions

static hid_t H5Lite::HDFTypeFromString ( const std::string &  value  )  [inline, static]

Given one of the HDF Types as a string, this will return the HDF Type as an hid_t value.

Parameters:
value The HDF_Type as a string
Returns:
the hid_t value for the given type. -1 if the string does not match a type.

static std::string H5Lite::StringForHDFType ( hid_t  type  )  [inline, static]

Returns a string version of the HDF Type.

Parameters:
type The HDF5 Type to query
Returns:

template<typename T>
static std::string H5Lite::HDFTypeForPrimitiveAsStr ( value  )  [inline, static]

Returns the HDF Type for a given primitive value.

Parameters:
value A value to use. Can be anything. Just used to get the type info from
Returns:
A std::string representing the HDF5 Type

template<typename T>
static hid_t H5Lite::HDFTypeForPrimitive ( value  )  [inline, static]

Returns the HDF Type for a given primitive value.

Parameters:
value A value to use. Can be anything. Just used to get the type info from
Returns:
The HDF5 native type for the value

static MXA_EXPORT herr_t H5Lite::findAttribute ( hid_t  loc_id,
const std::string &  attrName 
) [static]

Inquires if an attribute named attr_name exists attached to the object loc_id.

Parameters:
loc_id The location to search
attrName The attribute to search for
Returns:
Standard HDF5 Error condition

static MXA_EXPORT herr_t H5Lite::findDataset ( hid_t  loc_id,
const std::string &  name 
) [static]

Finds a Data set given a data set name.

Parameters:
loc_id The location to search
name The attribute to search for
Returns:
Standard HDF5 Error condition

template<typename T>
static herr_t H5Lite::writeVectorDataset ( hid_t  loc_id,
const std::string &  dsetName,
std::vector< hsize_t > &  dims,
std::vector< T > &  data 
) [inline, static]

Creates a Dataset with the given name at the location defined by loc_id.

Parameters:
loc_id The Parent location to store the data
dsetName The name of the dataset
dims The dimensions of the dataset
data The data to write to the file
Returns:
Standard HDF5 error conditions
The dimensions of the data sets are usually passed as both a "rank" and dimensions array. By using a std::vector<hsize_t> that stores the values of each of the dimensions we can reduce the number of arguments to this method as the value of the "rank" simply becomes dims.length(). So to create a Dims variable for a 3D data space of size(x,y,z) = {10,20,30} I would use the following code: std::vector<hsize_t> dims; dims.push_back(10); dims.push_back(20); dims.push_back(30);

Also when passing data BE SURE that the type of data and the data type match. For example if I create some data in a std::vector<UInt8Type> I would need to pass H5T_NATIVE_UINT8 as the dataType.

template<typename T>
static herr_t H5Lite::writePointerDataset ( hid_t  loc_id,
const std::string &  dsetName,
int32  rank,
hsize_t *  dims,
T *  data 
) [inline, static]

Writes the data of a pointer to an HDF5 file.

Parameters:
loc_id The hdf5 object id of the parent
dsetName The name of the dataset to write to. This can be a name of Path
rank The number of dimensions
dims The sizes of each dimension
data The data to be written.
Returns:
Standard hdf5 error condition.

template<typename T>
static herr_t H5Lite::writeDataset ( hid_t  loc_id,
const std::string &  dsetName,
int32 &  rank,
hsize_t *  dims,
T *  data 
) [inline, static]

Creates a Dataset with the given name at the location defined by loc_id.

Parameters:
loc_id The Parent location to store the data
dsetName The name of the dataset
dims The dimensions of the dataset
rank The number of dimensions to the dataset
data The data to write to the file
Returns:
Standard HDF5 error conditions
The dimensions of the data sets are usually passed as both a "rank" and dimensions array. By using a std::vector<hsize_t> that stores the values of each of the dimensions we can reduce the number of arguments to this method as the value of the "rank" simply becomes dims.length(). So to create a Dims variable for a 3D data space of size(x,y,z) = {10,20,30} I would use the following code: std::vector<hsize_t> dims; dims.push_back(10); dims.push_back(20); dims.push_back(30);

template<typename T>
static herr_t H5Lite::writeScalarDataset ( hid_t  loc_id,
const std::string &  dsetName,
T &  value 
) [inline, static]

Creates a Dataset with the given name at the location defined by loc_id. This version of writeDataset should be used with a single scalar value. If you need to write an array of values, use the form that takes an std::vector<>.

Parameters:
loc_id The Parent location to store the data
dsetName The name of the dataset
value The value to write to the HDF5 dataset
Returns:
Standard HDF5 error conditions

static MXA_EXPORT herr_t H5Lite::writeStringDataset ( hid_t  loc_id,
const std::string &  dsetName,
const std::string &  data 
) [static]

Writes a std::string as a HDF Dataset.

Parameters:
loc_id The Parent location to write the dataset
dsetName The Name to use for the dataset
data The actual data to write as a null terminated string
Returns:
Standard HDF5 error conditions

static MXA_EXPORT herr_t H5Lite::writeStringDataset ( hid_t  loc_id,
const std::string &  dsetName,
size_t  size,
const char *  data 
) [static]

Writes a null terminated 'C String' to an HDF Dataset.

Parameters:
loc_id The Parent location to write the dataset
dsetName The Name to use for the dataset
data const char pointer to write as a null terminated string
size The number of characters in the string
Returns:
Standard HDF5 error conditions

template<typename T>
static herr_t H5Lite::writePointerAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
int32  rank,
uint64 *  dims,
T *  data 
) [inline, static]

Writes an Attribute to an HDF5 Object.

Parameters:
loc_id The Parent Location of the HDFobject that is getting the attribute
objName The Name of Object to write the attribute into.
attrName The Name of the Attribute
rank The number of dimensions in the attribute data
dims The Dimensions of the attribute data
data The Attribute Data to write as a pointer
Returns:
Standard HDF Error Condition

template<typename T>
static herr_t H5Lite::writeVectorAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
std::vector< uint64 > &  dims,
std::vector< T > &  data 
) [inline, static]

Writes an Attribute to an HDF5 Object.

Parameters:
loc_id The Parent Location of the HDFobject that is getting the attribute
objName The Name of Object to write the attribute into.
attrName The Name of the Attribute
dims The Dimensions of the data set
data The Attribute Data to write
Returns:
Standard HDF Error Condition

static MXA_EXPORT herr_t H5Lite::writeStringAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
const std::string &  data 
) [static]

Writes a string as a null terminated attribute.

Parameters:
loc_id The location to look for objName
objName The Object to write the attribute to
attrName The name of the Attribute
data The string to write as the attribute
Returns:
Standard HDF error conditions

static MXA_EXPORT herr_t H5Lite::writeStringAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
hsize_t  size,
const char *  data 
) [static]

Writes a null terminated string as an attribute.

Parameters:
loc_id The location to look for objName
objName The Object to write the attribute to
attrName The name of the Attribute
size The number of characters in the string
data pointer to a const char array
Returns:
Standard HDF error conditions

static MXA_EXPORT herr_t H5Lite::writeStringAttributes ( hid_t  loc_id,
const std::string &  objName,
const std::map< std::string, std::string > &  attributes 
) [static]

Writes attributes that all have a data type of STRING. The first value in each set is the key, the second is the actual value of the attribute.

Parameters:
loc_id The location to look for objName
objName The Object to write the attribute to
attributes The attributes to be written where the first value is the name of the attribute, and the second is the actual value of the attribute.
Returns:
Standard HDF error condition

template<typename T>
static herr_t H5Lite::writeScalarAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
data 
) [inline, static]

Writes an attribute to the given object. This method is designed with a Template parameter that represents a primitive value. If you need to write an array, please use the other over loaded method that takes a vector.

Parameters:
loc_id The location to look for objName
objName The Object to write the attribute to
attrName The name of the attribute
data The data to be written as the attribute
Returns:
Standard HDF error condition

template<typename T>
static herr_t H5Lite::readPointerDataset ( hid_t  loc_id,
const std::string &  dsetName,
T *  data 
) [inline, static]

Reads data from the HDF5 File into a preallocated array.

Parameters:
loc_id The parent location that contains the dataset to read
dsetName The name of the dataset to read
data A Pointer to the PreAllocated Array of Data
Returns:
Standard HDF error condition

template<typename T>
static herr_t H5Lite::readVectorDataset ( hid_t  loc_id,
const std::string &  dsetName,
std::vector< T > &  data 
) [inline, static]

Reads data from the HDF5 File into an std::vector<T> object. If the dataset is very large this can be an expensive method to use. It is here for convenience using STL with hdf5.

Parameters:
loc_id The parent location that contains the dataset to read
dsetName The name of the dataset to read
data A std::vector<T>. Note the vector WILL be resized to fit the data. The best idea is to just allocate the vector but not to size it. The method will size it for you.
Returns:
Standard HDF error condition

template<typename T>
static herr_t H5Lite::readScalarDataset ( hid_t  loc_id,
const std::string &  dsetName,
T &  data 
) [inline, static]

Reads a dataset that consists of a single scalar value.

Parameters:
loc_id The HDF5 file or group id
dsetName The name or path to the dataset to read
data The variable to store the data into
Returns:
HDF error condition.

static MXA_EXPORT herr_t H5Lite::readStringDataset ( hid_t  loc_id,
const std::string &  dsetName,
std::string &  data 
) [static]

Reads a string dataset into the supplied string.

Parameters:
loc_id The parent group that holds the data object to read
dsetName The name of the dataset.
data The std::string to hold the data
Returns:
Standard HDF error condition

static MXA_EXPORT herr_t H5Lite::readStringDataset ( hid_t  loc_id,
const std::string &  dsetName,
uint8 *  data 
) [static]

reads a nullterminated string dataset into the supplied buffer. The buffer should be already preallocated.

Parameters:
loc_id The parent group that holds the data object to read
dsetName The name of the dataset.
data pointer to the buffer
Returns:
Standard HDF error condition

template<typename T>
static herr_t H5Lite::readVectorAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
std::vector< T > &  data 
) [inline, static]

Reads an Attribute from an HDF5 Object.

Use this method if you already know the datatype of the attribute. If you do not know this already then use another form of this method.

Parameters:
loc_id The Parent object that holds the object to which you want to read an attribute
objName The name of the object to which the attribute is to be read
attrName The name of the Attribute to read
data The memory to store the data
Returns:
Standard HDF Error condition

template<typename T>
static herr_t H5Lite::readScalarAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
T &  data 
) [inline, static]

Reads a scalar attribute value from a dataset.

Parameters:
loc_id 
objName The name of the dataset
attrName The name of the Attribute
data The preallocated memory for the variable to be stored into
Returns:
Standard HDF5 error condition

template<typename T>
static herr_t H5Lite::readPointerAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
T *  data 
) [inline, static]

Reads the Attribute into a pre-allocated pointer.

Parameters:
loc_id 
objName The name of the dataset
attrName The name of the Attribute
data The preallocated memory for the variable to be stored into
Returns:
Standard HDF5 error condition

static MXA_EXPORT herr_t H5Lite::readStringAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
std::string &  data 
) [static]

Reads a string attribute from an HDF object.

Parameters:
loc_id The Parent object that holds the object to which you want to read an attribute
objName The name of the object to which the attribute is to be read
attrName The name of the Attribute to read
data The memory to store the data
Returns:
Standard HDF Error condition

static MXA_EXPORT herr_t H5Lite::readStringAttribute ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
uint8 *  data 
) [static]

Reads a string attribute from an HDF object into a precallocated buffer.

Parameters:
loc_id The Parent object that holds the object to which you want to read an attribute
objName The name of the object to which the attribute is to be read
attrName The name of the Attribute to read
data The memory to store the data into
Returns:
Standard HDF Error condition

static MXA_EXPORT hid_t H5Lite::getAttributeNDims ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attrName,
hid_t &  rank 
) [static]

Returns the number of dimensions for a given attribute.

Parameters:
loc_id The HDF5 id of the parent group/file for the objName
objName The name of the dataset
attrName The name of the attribute
rank (out) Number of dimensions is store into this variable

static MXA_EXPORT hid_t H5Lite::getDatasetNDims ( hid_t  loc_id,
const std::string &  objName,
hid_t &  rank 
) [static]

Returns the number of dimensions for a given dataset.

Parameters:
loc_id The HDF5 id of the parent group/file for the objName
objName The name of the dataset
rank (out) Number of dimensions is store into this variable

static MXA_EXPORT hid_t H5Lite::getDatasetType ( hid_t  loc_id,
const std::string &  dsetName 
) [static]

Returns the H5T value for a given dataset.

Returns the type of data stored in the dataset. You MUST use H5Tclose(tid) on the returned value or resource leaks will occur.

Parameters:
loc_id A Valid HDF5 file or group id.
dsetName Path to the dataset
Returns:

static MXA_EXPORT herr_t H5Lite::getDatasetInfo ( hid_t  loc_id,
const std::string &  dsetName,
std::vector< hsize_t > &  dims,
H5T_class_t &  type_class,
size_t &  type_size 
) [static]

Get the information about a dataset.

Parameters:
loc_id The parent location of the Dataset
dsetName The name of the dataset
dims A std::vector that will hold the sizes of the dimensions
type_class The HDF5 class type
type_size THe HDF5 size of the data
Returns:
Negative value is Failure. Zero or Positive is success;

static MXA_EXPORT herr_t H5Lite::getAttributeInfo ( hid_t  loc_id,
const std::string &  objName,
const std::string &  attr_name,
std::vector< uint64 > &  dims,
H5T_class_t &  type_class,
size_t &  type_size,
hid_t &  attr_type 
) [static]

Returns the information about an attribute. You must close the attributeType argument or resource leaks will occur. Use H5Tclose(attr_type); after your call to this method if you do not need the id for anything.

Parameters:
loc_id The parent location of the Dataset
objName The name of the dataset
attr_name The name of the attribute
dims A std::vector that will hold the sizes of the dimensions
type_class The HDF5 class type
type_size THe HDF5 size of the data
attr_type The Attribute ID - which needs to be closed after you are finished with the data
Returns:

void H5Lite::NEVER_USED (  )  [inline, private]


The documentation for this class was generated from the following file:
Generated on Tue Nov 17 18:43:12 2009 for MXADataModel by  doxygen 1.5.2