From 80816a3dde8614c52d80f0090f8a5d08fc4546e7 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Wed, 26 May 2004 02:02:51 -0500 Subject: [svn-r8576] Purpose: Add more C++ wrapper and documentation - incrementally check-in Description: Added doxygen documentation to: H5DataSet.cpp H5DataSpace.cpp H5CommonFG.cpp and a wrapper for H5Rcreate to H5Object.* with tests will be added later. There are more documentation need to be added to these files but to preserve the changes, I check them in now. Platforms: SunOS 5.7 (arabica) Linux 2.4 (eirene) Misc. update: --- c++/src/H5CommonFG.cpp | 478 ++++++++++++++++++++++++++++++++++++++++-------- c++/src/H5DataSet.cpp | 230 +++++++++++++++++------ c++/src/H5DataSpace.cpp | 297 +++++++++++++++++++++++++----- c++/src/H5DataType.cpp | 14 +- c++/src/H5File.cpp | 10 +- c++/src/H5Object.cpp | 22 ++- c++/src/H5Object.h | 3 + 7 files changed, 872 insertions(+), 182 deletions(-) diff --git a/c++/src/H5CommonFG.cpp b/c++/src/H5CommonFG.cpp index 8477fed..67711f9 100644 --- a/c++/src/H5CommonFG.cpp +++ b/c++/src/H5CommonFG.cpp @@ -49,12 +49,21 @@ namespace H5 { #endif -// Creates a new group at this location which can be a file or another group. -Group CommonFG::createGroup( const string& name, size_t size_hint ) const -{ - return( createGroup( name.c_str(), size_hint )); -} - +//-------------------------------------------------------------------------- +// Function: CommonFG::createGroup +///\brief Creates a new group at this location which can be a file +/// or another group. +///\param name - IN: Name of the group +///\param value - IN: Size to reserve +///\return Group instance +///\exception H5::FileIException or H5::GroupIException +///\par Description +/// The optional \a size_hint specifies how much file space to +/// reserve for storing the names that will appear in this new +/// group. If a non-positive value is provided for the \a size_hint +/// then a default size is chosen. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- Group CommonFG::createGroup( const char* name, size_t size_hint ) const { // Call C routine H5Gcreate to create the named group, giving the @@ -72,11 +81,27 @@ Group CommonFG::createGroup( const char* name, size_t size_hint ) const return( group ); } -// Opens an existing group in a location which can be a file or another group -Group CommonFG::openGroup( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::createGroup +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +Group CommonFG::createGroup( const string& name, size_t size_hint ) const { - return( openGroup( name.c_str() )); + return( createGroup( name.c_str(), size_hint )); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::openGroup +///\brief Opens an existing group in a location which can be a file +/// or another group. +///\param name - IN: Name of the group to open +///\return Group instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- Group CommonFG::openGroup( const char* name ) const { // Call C routine H5Gopen to open the named group, giving the @@ -94,11 +119,29 @@ Group CommonFG::openGroup( const char* name ) const return( group ); } -// Creates a new dataset at this location. -DataSet CommonFG::createDataSet( const string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::openGroup +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +Group CommonFG::openGroup( const string& name ) const { - return( createDataSet( name.c_str(), data_type, data_space, create_plist )); + return( openGroup( name.c_str() )); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::createDataSet +///\brief Creates a new dataset at this location. +///\param name - IN: Name of the dataset to create +///\param data_type - IN: +///\param data_space - IN: +///\param create_plist - IN: +///\return DataSet instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSet CommonFG::createDataSet( const char* name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist ) const { // Obtain identifiers for C API @@ -120,11 +163,26 @@ DataSet CommonFG::createDataSet( const char* name, const DataType& data_type, co return( dataset ); } -// Opens an existing dataset at this location. -DataSet CommonFG::openDataSet( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::createDataSet +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +DataSet CommonFG::createDataSet( const string& name, const DataType& data_type, const DataSpace& data_space, const DSetCreatPropList& create_plist ) const { - return( openDataSet( name.c_str() )); + return( createDataSet( name.c_str(), data_type, data_space, create_plist )); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::openDataSet +///\brief Opens an existing dataset at this location. +///\param name - IN: Name of the dataset to open +///\return DataSet instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSet CommonFG::openDataSet( const char* name ) const { // Call C function H5Dopen to open the specified dataset, giving @@ -142,12 +200,32 @@ DataSet CommonFG::openDataSet( const char* name ) const return( dataset ); } -// Creates a link of the specified type from new_name to current_name; -// both names are interpreted relative to the specified location id -void CommonFG::link( H5G_link_t link_type, const string& curr_name, const string& new_name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::openDataSet +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +DataSet CommonFG::openDataSet( const string& name ) const { - link( link_type, curr_name.c_str(), new_name.c_str() ); + return( openDataSet( name.c_str() )); } + +// Creates a link of the specified type from new_name to current_name; +//-------------------------------------------------------------------------- +// Function: CommonFG::link +///\brief Creates a link of the specified type from \a new_name to +/// \a curr_name; +///\param link_type - IN: +///\param curr_name - IN: +///\param new_name - IN: +///\exception H5::FileIException or H5::GroupIException +///\par Description +/// Note that both names are interpreted relative to the +/// specified location. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::link( H5G_link_t link_type, const char* curr_name, const char* new_name ) const { herr_t ret_value = H5Glink( getLocId(), link_type, curr_name, new_name ); @@ -157,11 +235,25 @@ void CommonFG::link( H5G_link_t link_type, const char* curr_name, const char* ne } } -// Removes the specified name at this location. -void CommonFG::unlink( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::link +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a curr_name and \a new_name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::link( H5G_link_t link_type, const string& curr_name, const string& new_name ) const { - unlink( name.c_str() ); + link( link_type, curr_name.c_str(), new_name.c_str() ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::unlink +///\brief Removes the specified name at this location. +///\param name - IN: Name of the object to be removed +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::unlink( const char* name ) const { herr_t ret_value = H5Gunlink( getLocId(), name ); @@ -171,11 +263,26 @@ void CommonFG::unlink( const char* name ) const } } -// Renames an object at this location. -void CommonFG::move( const string& src, const string& dst ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::unlink +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::unlink( const string& name ) const { - move( src.c_str(), dst.c_str() ); + unlink( name.c_str() ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::move +///\brief Renames an object at this location. +///\param src - IN: +///\param dst - IN: +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::move( const char* src, const char* dst ) const { herr_t ret_value = H5Gmove( getLocId(), src, dst ); @@ -185,11 +292,27 @@ void CommonFG::move( const char* src, const char* dst ) const } } -// Returns information about an object -void CommonFG::getObjinfo( const string& name, hbool_t follow_link, H5G_stat_t& statbuf ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::move +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a src and \a dst. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::move( const string& src, const string& dst ) const { - getObjinfo( name.c_str(), follow_link, statbuf ); + move( src.c_str(), dst.c_str() ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::getObjinfo +///\brief Returns information about an object. +///\param name - IN: Name of the object +///\param follow_link - IN: +///\param statbuf - IN: +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::getObjinfo( const char* name, hbool_t follow_link, H5G_stat_t& statbuf ) const { herr_t ret_value = H5Gget_objinfo( getLocId(), name, follow_link, &statbuf ); @@ -199,11 +322,27 @@ void CommonFG::getObjinfo( const char* name, hbool_t follow_link, H5G_stat_t& st } } -// Returns the name of the object that the symbolic link points to. -string CommonFG::getLinkval( const string& name, size_t size ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::getObjinfo +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::getObjinfo( const string& name, hbool_t follow_link, H5G_stat_t& statbuf ) const { - return( getLinkval( name.c_str(), size )); + getObjinfo( name.c_str(), follow_link, statbuf ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::getLinkval +///\brief Returns the name of the object that the symbolic link points to. +///\param name - IN: +///\param size - IN: +///\return Name of the object +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string CommonFG::getLinkval( const char* name, size_t size ) const { char* value_C = new char[size+1]; // temporary C-string for C API @@ -218,11 +357,26 @@ string CommonFG::getLinkval( const char* name, size_t size ) const return( value ); } -// Sets the comment for an object specified by its name -void CommonFG::setComment( const string& name, const string& comment ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::getLinkval +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +string CommonFG::getLinkval( const string& name, size_t size ) const { - setComment( name.c_str(), comment.c_str() ); + return( getLinkval( name.c_str(), size )); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::setComment +///\brief Sets the comment for an object specified by its name. +///\param name - IN: +///\param comment - IN: +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::setComment( const char* name, const char* comment ) const { herr_t ret_value = H5Gset_comment( getLocId(), name, comment ); @@ -232,11 +386,27 @@ void CommonFG::setComment( const char* name, const char* comment ) const } } -// Retrieves comment for specified object -string CommonFG::getComment( const string& name, size_t bufsize ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::setComment +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name and \a comment. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::setComment( const string& name, const string& comment ) const { - return( getComment( name.c_str(), bufsize )); + setComment( name.c_str(), comment.c_str() ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::getComment +///\brief Retrieves comment for the specified object. +///\param name - IN: Name of the object +///\param bufsize - IN: +///\return Comment string +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string CommonFG::getComment( const char* name, size_t bufsize ) const { // temporary C-string for the object's comment @@ -254,11 +424,27 @@ string CommonFG::getComment( const char* name, size_t bufsize ) const return( comment ); } -// Mounts the file 'child' onto this group -void CommonFG::mount( const string& name, H5File& child, PropList& plist ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::getComment +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +string CommonFG::getComment( const string& name, size_t bufsize ) const { - mount( name.c_str(), child, plist ); + return( getComment( name.c_str(), bufsize )); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::mount +///\brief Mounts the file 'child' onto this group. +///\param name - IN: +///\param child - IN: +///\param plist - IN: +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::mount( const char* name, H5File& child, PropList& plist ) const { // Obtain identifiers for C API @@ -275,11 +461,25 @@ void CommonFG::mount( const char* name, H5File& child, PropList& plist ) const } } -// Unmounts the file named 'name' from this parent group -void CommonFG::unmount( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::mount +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::mount( const string& name, H5File& child, PropList& plist ) const { - unmount( name.c_str() ); + mount( name.c_str(), child, plist ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::unmount +///\brief Unmounts the file named 'name' from this parent group. +///\param name - IN: +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void CommonFG::unmount( const char* name ) const { // Call C routine H5Fmount to do the mouting @@ -292,6 +492,18 @@ void CommonFG::unmount( const char* name ) const } } +//-------------------------------------------------------------------------- +// Function: CommonFG::unmount +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void CommonFG::unmount( const string& name ) const +{ + unmount( name.c_str() ); +} + // This private member function calls the C API H5Topen to open the // named datatype and returns the datatype's identifier. The function // is used by the functions openXxxType's below for opening the sub-types @@ -316,77 +528,175 @@ hid_t CommonFG::p_openDataType( const char* name ) const // p_openDataType to open a named datatype in this location // -// Opens the named generic datatype in this group. -DataType CommonFG::openDataType( const string& name ) const -{ - return( openDataType( name.c_str()) ); -} +//-------------------------------------------------------------------------- +// Function: CommonFG::openDataType +///\brief Opens the named generic datatype at this location. +///\param name - IN: Name of the datatype to open +///\return DataType instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataType CommonFG::openDataType( const char* name ) const { DataType data_type( p_openDataType( name )); return( data_type ); } -// Opens the named enumeration datatype in this group. -EnumType CommonFG::openEnumType( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::openDataType +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +DataType CommonFG::openDataType( const string& name ) const { - return( openEnumType( name.c_str()) ); -} + return( openDataType( name.c_str()) ); +} + +//-------------------------------------------------------------------------- +// Function: CommonFG::openEnumType +///\brief Opens the named enumeration datatype at this location. +///\param name - IN: Name of the enumeration datatype to open +///\return EnumType instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType CommonFG::openEnumType( const char* name ) const { EnumType enum_type( p_openDataType( name )); return( enum_type ); } -// Opens the named compound datatype in this group. -CompType CommonFG::openCompType( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::openEnumType +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +EnumType CommonFG::openEnumType( const string& name ) const { - return( openCompType( name.c_str()) ); -} + return( openEnumType( name.c_str()) ); +} + +//-------------------------------------------------------------------------- +// Function: CommonFG::openCompType +///\brief Opens the named compound datatype at this location. +///\param name - IN: Name of the compound datatype to open +///\return CompType instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- CompType CommonFG::openCompType( const char* name ) const { CompType comp_type( p_openDataType( name )); return( comp_type ); } -// Opens the named integer datatype in this group. -IntType CommonFG::openIntType( const string& name ) const -{ - return( openIntType( name.c_str()) ); +//-------------------------------------------------------------------------- +// Function: CommonFG::openCompType +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +CompType CommonFG::openCompType( const string& name ) const +{ + return( openCompType( name.c_str()) ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::openIntType +///\brief Opens the named integer datatype at this location. +///\param name - IN: Name of the integer datatype to open +///\return IntType instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- IntType CommonFG::openIntType( const char* name ) const { IntType int_type( p_openDataType( name )); return( int_type ); } -// Opens the named floating-point datatype in this group. -FloatType CommonFG::openFloatType( const string& name ) const +//-------------------------------------------------------------------------- +// Function: CommonFG::openIntType +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +IntType CommonFG::openIntType( const string& name ) const { - return( openFloatType( name.c_str()) ); + return( openIntType( name.c_str()) ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::openFloatType +///\brief Opens the named floating-point datatype at this location. +///\param name - IN: Name of the floating-point datatype to open +///\return FloatType instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- FloatType CommonFG::openFloatType( const char* name ) const { FloatType float_type( p_openDataType( name )); return( float_type ); } -// Opens the named string datatype of this group -StrType CommonFG::openStrType( const string& name ) const -{ - return( openStrType( name.c_str()) ); +//-------------------------------------------------------------------------- +// Function: CommonFG::openFloatType +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +FloatType CommonFG::openFloatType( const string& name ) const +{ + return( openFloatType( name.c_str()) ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::openStrType +///\brief Opens the named string datatype at this location. +///\param name - IN: Name of the string datatype to open +///\return StrType instance +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- StrType CommonFG::openStrType( const char* name ) const { StrType str_type( p_openDataType( name )); return( str_type ); } -// Iterates a user's function over the entries of a group. -int CommonFG::iterateElems( const string& name, int *idx, H5G_iterate_t op , void* op_data ) +//-------------------------------------------------------------------------- +// Function: CommonFG::openStrType +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +StrType CommonFG::openStrType( const string& name ) const { - return( iterateElems( name.c_str(), idx, op, op_data )); + return( openStrType( name.c_str()) ); } + +//-------------------------------------------------------------------------- +// Function: CommonFG::iterateElems +///\brief Iterates a user's function over the entries of a group. +///\param name - IN: +///\param idx - IN: +///\param op - IN: +///\param op_data - IN: +///\return The return value of the first operator that returns non-zero, +/// or zero if all members were processed with no operator +/// returning non-zero. +///\exception H5::FileIException or H5::GroupIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- int CommonFG::iterateElems( const char* name, int *idx, H5G_iterate_t op , void* op_data ) { int ret_value = H5Giterate( getLocId(), name, idx, op, op_data ); @@ -397,13 +707,31 @@ int CommonFG::iterateElems( const char* name, int *idx, H5G_iterate_t op , void* return( ret_value ); } -CommonFG::CommonFG() -{ // do nothing +//-------------------------------------------------------------------------- +// Function: CommonFG::iterateElems +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it takes an +/// \c std::string for \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +int CommonFG::iterateElems( const string& name, int *idx, H5G_iterate_t op , void* op_data ) +{ + return( iterateElems( name.c_str(), idx, op, op_data )); } -CommonFG::~CommonFG() -{ // do nothing -} +//-------------------------------------------------------------------------- +// Function: CommonFG default constructor +///\brief Default constructor. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +CommonFG::CommonFG() {} + +//-------------------------------------------------------------------------- +// Function: CommonFG destructor +///\brief Properly terminates access to this object. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +CommonFG::~CommonFG() {} #ifndef H5_NO_NAMESPACE } diff --git a/c++/src/H5DataSet.cpp b/c++/src/H5DataSet.cpp index 84bed5c..950f28c 100644 --- a/c++/src/H5DataSet.cpp +++ b/c++/src/H5DataSet.cpp @@ -38,17 +38,36 @@ namespace H5 { #endif -// Default constructor +//-------------------------------------------------------------------------- +// Function: DataSet default constructor +///\brief Default constructor: Creates a stub dataset. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSet::DataSet() : AbstractDs() {} -// Creates a copy of DataSet using an existing id +//-------------------------------------------------------------------------- +// Function: DataSet overloaded constructor +///\brief Creates an DataSet object using the id of an existing dataset. +///\param existing_id - IN: Id of an existing dataset +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSet::DataSet( const hid_t dataset_id ) : AbstractDs( dataset_id ) {} -// Copy constructor makes a copy of the original object by using base -// class' copy constructors +//-------------------------------------------------------------------------- +// Function: DataSet copy constructor +///\brief Copy constructor: makes a copy of the original DataSet object. +///\param original - IN: DataSet instance to copy +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSet::DataSet( const DataSet& original ) : AbstractDs( original ) {} -// Gets a copy of the dataspace of this dataset +//-------------------------------------------------------------------------- +// Function: DataSet::getSpace +///\brief Gets a copy of the dataspace of this dataset. +///\return DataSpace instance +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace DataSet::getSpace() const { // Calls C function H5Dget_space to get the id of the dataspace @@ -78,7 +97,13 @@ hid_t DataSet::p_getType() const } } -// Gets the dataset creation property list +//-------------------------------------------------------------------------- +// Function: DataSet::getCreatePlist +///\brief Gets the dataset creation property list. +///\return DSetCreatPropList instance +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DSetCreatPropList DataSet::getCreatePlist() const { hid_t create_plist_id = H5Dget_create_plist( id ); @@ -91,7 +116,13 @@ DSetCreatPropList DataSet::getCreatePlist() const return( create_plist ); } -// Returns the amount of storage required for a dataset. +//-------------------------------------------------------------------------- +// Function: DataSet::getStorageSize +///\brief Returns the amount of storage required for a dataset. +///\return Amount of storage +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hsize_t DataSet::getStorageSize() const { hsize_t storage_size = H5Dget_storage_size( id ); @@ -104,27 +135,39 @@ hsize_t DataSet::getStorageSize() const } } -// Returns the number of bytes required to store VL data. +//-------------------------------------------------------------------------- +// Function: DataSet::getVlenBufSize +///\brief Returns the number of bytes required to store VL data. +///\return Amount of storage +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hsize_t DataSet::getVlenBufSize( DataType& type, DataSpace& space ) const { // Obtain identifiers for C API - //hid_t type_id = type.getId(); - //hid_t space_id = space.getId(); - //hsize_t size; - - //herr_t ret_value = H5Dget_vlen_buf_size( id, type_id, space_id, &size ); - //if( ret_value >= 0 ) - // return( size ); - //else - //{ - //throw DataSetIException(); - //} - throw DataSetIException( "DataSet::getVlenBufSize", - "Currently not implemented yet."); - return (0); + hid_t type_id = type.getId(); + hid_t space_id = space.getId(); + + hsize_t size; // for amount of storage + + herr_t ret_value = H5Dvlen_get_buf_size( id, type_id, space_id, &size ); + if( ret_value < 0 ) + { + throw DataSetIException("DataSet::getStorageSize", "H5Dget_storage_size failed"); + } + return( size ); } -// Reclaims VL datatype memory buffers. +//-------------------------------------------------------------------------- +// Function: DataSet::getVlenBufSize +///\brief Reclaims VL datatype memory buffers. +///\param dataspace - IN: Selection for the memory buffer to free the +/// VL datatypes within +///\param xfer_plist - IN: Property list used to create the buffer +///\param buf - IN: Pointer to the buffer to be reclaimed +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::vlenReclaim( DataType& type, DataSpace& space, DSetMemXferPropList& xfer_plist, void* buf ) const { // Obtain identifiers for C API @@ -139,8 +182,21 @@ void DataSet::vlenReclaim( DataType& type, DataSpace& space, DSetMemXferPropList } } -// Reads raw data from the specified dataset into buf, converting from -// file datatype and dataspace to memory datatype and dataspace. +//-------------------------------------------------------------------------- +// Function: DataSet::read +///\brief Reads raw data from the specified dataset. +///\param buf - IN: Buffer for read data +///\param mem_type - IN: Memory datatype +///\param mem_space - IN: Memory dataspace +///\param file_space - IN: Dataset's dataspace in the file +///\param xfer_plist - IN: Transfer property list for this I/O operation +///\exception H5::DataSetIException +///par Description +/// This function reads raw data from this dataset into the +/// buffer \a buf, converting from file datatype and dataspace +/// to memory datatype \a mem_type and dataspace \a mem_space. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::read( void* buf, const DataType& mem_type, const DataSpace& mem_space, const DataSpace& file_space, const DSetMemXferPropList& xfer_plist ) const { // Obtain identifiers for C API @@ -156,6 +212,12 @@ void DataSet::read( void* buf, const DataType& mem_type, const DataSpace& mem_sp } } +//-------------------------------------------------------------------------- +// Function: DataSet::read +///\brief This is an overloaded member function, provided for convenience. +/// It takes a reference to a \c std::string for the buffer. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::read( string& strg, const DataType& mem_type, const DataSpace& mem_space, const DataSpace& file_space, const DSetMemXferPropList& xfer_plist ) const { // Allocate C character string for reading @@ -170,9 +232,22 @@ void DataSet::read( string& strg, const DataType& mem_type, const DataSpace& mem delete strg_C; } -// Writes raw data from an application buffer buffer to a dataset, -// converting from memory datatype and dataspace to file datatype -// and dataspace. +//-------------------------------------------------------------------------- +// Function: DataSet::write +///\brief Writes raw data from an application buffer to a dataset. +///\param buf - IN: Buffer containing data to be written +///\param mem_type - IN: Memory datatype +///\param mem_space - IN: Memory dataspace +///\param file_space - IN: Dataset's dataspace in the file +///\param xfer_plist - IN: Transfer property list for this I/O operation +///\exception H5::DataSetIException +///par Description +/// This function writes raw data from an application buffer +/// \a buf to a dataset, converting from memory datatype +/// \a mem_type and dataspace \a mem_space to file datatype +/// and dataspace. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::write( const void* buf, const DataType& mem_type, const DataSpace& mem_space, const DataSpace& file_space, const DSetMemXferPropList& xfer_plist ) const { // Obtain identifiers for C API @@ -188,6 +263,12 @@ void DataSet::write( const void* buf, const DataType& mem_type, const DataSpace& } } +//-------------------------------------------------------------------------- +// Function: DataSet::write +///\brief This is an overloaded member function, provided for convenience. +/// It takes a reference to a \c std::string for the buffer. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::write( const string& strg, const DataType& mem_type, const DataSpace& mem_space, const DataSpace& file_space, const DSetMemXferPropList& xfer_plist ) const { // Convert string to C-string @@ -198,7 +279,23 @@ void DataSet::write( const string& strg, const DataType& mem_type, const DataSpa write(strg_C, mem_type, mem_space, file_space, xfer_plist); } -// Iterates over all selected elements in a dataspace. +//-------------------------------------------------------------------------- +// Function: DataSet::iterateElems +///\brief Iterates over all selected elements in a dataspace. +///\param buf - IN/OUT: Pointer to the buffer in memory containing the +/// elements to iterate over +///\param type - IN: Datatype for the elements stored in \a buf +///\param space - IN: Dataspace for \a buf. Also contains the selection +/// to iterate over. +///\param op - IN: Function pointer to the routine to be called for +/// each element in \a buf iterated over +///\param op_data - IN/OUT: Pointer to any user-defined data associated +/// with the operation +///\exception H5::DataSetIException +///\note This function may not work correctly yet - it's still +/// under development. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- int DataSet::iterateElems( void* buf, const DataType& type, const DataSpace& space, H5D_operator_t op, void* op_data ) { // Obtain identifiers for C API @@ -213,7 +310,17 @@ int DataSet::iterateElems( void* buf, const DataType& type, const DataSpace& spa } } -// Extends a dataset with unlimited dimension. +//-------------------------------------------------------------------------- +// Function: DataSet::extend +///\brief Extends a dataset with unlimited dimension. +///\param size - IN: Array containing the new magnitude of each dimension +///\exception H5::DataSetIException +///\par Description +/// For more information, please see the Description section in +/// C layer Reference Manual at: +/// http: +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::extend( const hsize_t* size ) const { herr_t ret_value = H5Dextend( id, size ); @@ -223,25 +330,17 @@ void DataSet::extend( const hsize_t* size ) const } } -/*-------------------------------------------------------------------------- - NAME - fillMemBuf - PURPOSE - Fills a selection in memory with a value - USAGE - fillMemBuf(fill, fill_type, buf, buf_type, space) - fillMemBuf(buf, buf_type, space) - void *buf; IN/OUT: Memory buffer to fill selection within - DataType& buf_type; IN: Datatype of the elements in buffer - DataSpace& space; IN: Dataspace describing memory buffer & - containing selection to use. - const void *fill; IN: Pointer to fill value to use - default NULL - DataType& fill_type; IN: Datatype of the fill value - DESCRIPTION - Use the selection in the dataspace to fill elements in a memory buffer. - COMMENTS, BUGS, ASSUMPTIONS - Second usage uses all zeros as fill value ---------------------------------------------------------------------------*/ +//-------------------------------------------------------------------------- +// Function: DataSet::fillMemBuf +///\brief Fills a selection in memory with a value. +///\param fill - IN: Pointer to fill value to use - default NULL +///\param fill_type - IN: Datatype of the fill value +///\param buf - IN/OUT: Memory buffer to fill selection within +///\param buf_type - IN: Datatype of the elements in buffer +///\param space - IN: Dataspace describing memory buffer & containing selection to use +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::fillMemBuf(const void *fill, DataType& fill_type, void *buf, DataType& buf_type, DataSpace& space) { hid_t fill_type_id = fill_type.getId(); @@ -253,6 +352,18 @@ void DataSet::fillMemBuf(const void *fill, DataType& fill_type, void *buf, DataT throw DataSetIException("DataSet::fillMemBuf", "H5Dfill failed"); } } + +//-------------------------------------------------------------------------- +// Function: DataSet::fillMemBuf +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function in that it only takes the +/// the last three arguments. +///\param buf - IN/OUT: Memory buffer to fill selection within +///\param buf_type - IN: Datatype of the elements in buffer +///\param space - IN: Dataspace describing memory buffer & containing selection to use +///\exception H5::DataSetIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::fillMemBuf(void *buf, DataType& buf_type, DataSpace& space) { hid_t buf_type_id = buf_type.getId(); @@ -264,8 +375,15 @@ void DataSet::fillMemBuf(void *buf, DataType& buf_type, DataSpace& space) } } -// This private function calls the C API H5Dclose to close this dataset. -// Used by IdComponent::reset +//-------------------------------------------------------------------------- +// Function: DataSet::p_close (private) +///\brief Closes this dataset. +///\exception H5::DataSetIException +///\note +/// This function will be obsolete because its functionality +/// is recently handled by the C library layer. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSet::p_close() const { herr_t ret_value = H5Dclose( id ); @@ -275,11 +393,11 @@ void DataSet::p_close() const } } -// The destructor of this instance calls IdComponent::reset to -// reset its identifier - no longer true -// Older compilers (baldric) don't support template member functions -// and IdComponent::reset is one; so at this time, the resetId is not -// a member function so it can be template to work around that problem. +//-------------------------------------------------------------------------- +// Function: DataSet destructor +///\brief Properly terminates access to this dataset. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSet::~DataSet() { // The dataset id will be closed properly diff --git a/c++/src/H5DataSpace.cpp b/c++/src/H5DataSpace.cpp index 5921274..63c4076 100644 --- a/c++/src/H5DataSpace.cpp +++ b/c++/src/H5DataSpace.cpp @@ -32,10 +32,21 @@ namespace H5 { const DataSpace DataSpace::ALL( H5S_ALL ); -// Default constructor +//-------------------------------------------------------------------------- +// Function: DataSpace default constructor +///\brief Default constructor: Creates a stub datatype +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace::DataSpace() : IdComponent() {} -// This constructor creates a DataSpace instance, given a dataspace type +//-------------------------------------------------------------------------- +// Function: DataSpace overloaded constructor +///\brief Creates a dataspace given a dataspace type. +///\param type - IN: Type of the dataspace to be created, which +/// currently can be either \c H5S_SCALAR or \c H5S_SIMPLE +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace::DataSpace( H5S_class_t type ) : IdComponent() { id = H5Screate( type ); @@ -45,7 +56,15 @@ DataSpace::DataSpace( H5S_class_t type ) : IdComponent() } } -// Creates a new simple data space and opens it for access. +//-------------------------------------------------------------------------- +// Function: DataSpace overloaded constructor +///\brief Creates a new simple dataspace and opens it for access. +///\param rank - IN: Number of dimensions of dataspace. +///\param dims - IN: An array of the size of each dimension. +///\param maxdims - IN: An array of the maximum size of each dimension. +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace::DataSpace( int rank, const hsize_t * dims, const hsize_t * maxdims) : IdComponent() { id = H5Screate_simple( rank, dims, maxdims ); @@ -55,20 +74,31 @@ DataSpace::DataSpace( int rank, const hsize_t * dims, const hsize_t * maxdims) : } } -/* Constructor that takes an existing dataspace id -Description: - Uses an HDF5 id to create a DataSpace identifier instance. - This id can be either an existing dataspace id or a default - dataspace id. Design note: in the case of default dataspace, - the identifier still has reference counter; the p_close function - will take care of not to call H5Sclose on the default id. -*/ +//-------------------------------------------------------------------------- +// Function: DataSpace overloaded constructor +///\brief Creates an DataSpace object using the id of an existing +/// dataspace. +///\param existing_id - IN: Id of an existing datatype +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace::DataSpace( const hid_t space_id ) : IdComponent( space_id ) {} -// Copy constructor: makes a copy of the original DataSpace instance +//-------------------------------------------------------------------------- +// Function: DataSpace copy constructor +///\brief Copy constructor: makes a copy of the original DataSpace object. +///\param original - IN: DataSpace instance to copy +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace::DataSpace( const DataSpace& original ) : IdComponent( original ) {} -// Makes a copy of an existing dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::copy +///\brief Makes a copy of an existing dataspace. +///\param like_space - IN: Dataspace to be copied +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::copy( const DataSpace& like_space ) { // reset the identifier of this instance - send 'this' in so that @@ -91,15 +121,31 @@ void DataSpace::copy( const DataSpace& like_space ) } } -// Makes a copy of the dataspace on the right hand side and stores -// the new id in the left hand side object. +//-------------------------------------------------------------------------- +// Function: DataSpace::operator= +///\brief Assignment operator +///\param rhs - IN: Reference to the existing dataspace +///\return Reference to DataSpace instance +///\exception H5::DataSpaceIException +// Description +// Makes a copy of the type on the right hand side and stores +// the new id in the left hand side object. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace& DataSpace::operator=( const DataSpace& rhs ) { copy(rhs); return(*this); } -// Determines whether this dataspace is a simple dataspace. +//-------------------------------------------------------------------------- +// Function: DataSpace::isSimple +///\brief Determines whether this dataspace is a simple dataspace. +///\return true if the dataspace is a simple dataspace, and false, +/// otherwise +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- bool DataSpace::isSimple () const { htri_t simple = H5Sis_simple( id ); @@ -114,7 +160,18 @@ bool DataSpace::isSimple () const } } -// Sets the offset of this simple dataspace. +//-------------------------------------------------------------------------- +// Function: DataSpace::offsetSimple +///\brief Sets the offset of this simple dataspace. +///\param offset - IN: Offset to position the selection at +///\exception H5::DataSpaceIException +///\par Description +/// This function creates an offset for the selection within +/// an extent, allowing the same shaped selection to be moved +/// to different locations within a dataspace without requiring +/// it to be re-defined. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::offsetSimple ( const hssize_t* offset ) const { herr_t ret_value = H5Soffset_simple( id, offset ); @@ -124,7 +181,16 @@ void DataSpace::offsetSimple ( const hssize_t* offset ) const } } -// Retrieves dataspace dimension size and maximum size +//-------------------------------------------------------------------------- +// Function: DataSpace::getSimpleExtentDims +///\brief Retrieves dataspace dimension size and maximum size. +///\param dims - IN: Name of the new member +///\param maxdims - IN: Pointer to the value of the new member +///\return Number of dimensions, the same value as returned by +/// \c DataSpace::getSimpleExtentNdims() +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- int DataSpace::getSimpleExtentDims ( hsize_t *dims, hsize_t *maxdims ) const { int ndims = H5Sget_simple_extent_dims( id, dims, maxdims ); @@ -136,7 +202,13 @@ int DataSpace::getSimpleExtentDims ( hsize_t *dims, hsize_t *maxdims ) const return( ndims ); } -// Determines the dimensionality of a dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::getSimpleExtentNdims +///\brief Determines the dimensionality of a dataspace. +///\return Number of dimensions +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- int DataSpace::getSimpleExtentNdims () const { int ndims = H5Sget_simple_extent_ndims( id ); @@ -148,10 +220,17 @@ int DataSpace::getSimpleExtentNdims () const return( ndims ); } -// Determines the number of elements in a dataspace -// 12/05/00: due to C API change -// return type hssize_t vs. hsize_t -// num_elements = -1 when failure occurs vs. 0 +//-------------------------------------------------------------------------- +// Function: DataSpace::getSimpleExtentNpoints +///\brief Determines the number of elements in a dataspace. +///\return Number of elements +///\exception H5::DataSpaceIException +// Modification +// 12/05/00: due to C API change +// return type hssize_t vs. hsize_t +// num_elements = -1 when failure occurs vs. 0 +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hssize_t DataSpace::getSimpleExtentNpoints () const { hssize_t num_elements = H5Sget_simple_extent_npoints( id ); @@ -165,7 +244,13 @@ hssize_t DataSpace::getSimpleExtentNpoints () const } } -// Determine the current class of a dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::getSimpleExtentType +///\brief Determine the current class of a dataspace. +///\return Class of the dataspace +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- H5S_class_t DataSpace::getSimpleExtentType () const { H5S_class_t class_name = H5Sget_simple_extent_type( id ); @@ -177,7 +262,13 @@ H5S_class_t DataSpace::getSimpleExtentType () const return( class_name ); } -// Copies the extent of a dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::extentCopy +///\brief Copies the extent of a dataspace. +///\param dest_space - IN: DataSpace to copy from +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::extentCopy ( DataSpace& dest_space ) const { hid_t dest_space_id = dest_space.getId(); @@ -188,7 +279,15 @@ void DataSpace::extentCopy ( DataSpace& dest_space ) const } } -// Sets or resets the size of an existing dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::setExtentSimple +///\brief Sets or resets the size of an existing dataspace. +///\param rank - IN: +///\param current_size - IN: +///\param maximum_size - IN: +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::setExtentSimple( int rank, const hsize_t *current_size, const hsize_t *maximum_size ) const { herr_t ret_value; @@ -199,7 +298,12 @@ void DataSpace::setExtentSimple( int rank, const hsize_t *current_size, const hs } } -// Removes the extent from a dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::setExtentNone +///\brief Removes the extent from a dataspace. +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::setExtentNone () const { herr_t ret_value = H5Sset_extent_none( id ); @@ -209,7 +313,13 @@ void DataSpace::setExtentNone () const } } -// Determines the number of elements in a dataspace selection +//-------------------------------------------------------------------------- +// Function: DataSpace::getSelectNpoints +///\brief Returns the number of elements in a dataspace selection. +///\return Number of elements +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hssize_t DataSpace::getSelectNpoints () const { hssize_t num_elements = H5Sget_select_npoints( id ); @@ -221,7 +331,13 @@ hssize_t DataSpace::getSelectNpoints () const return( num_elements ); } -// Get number of hyperslab blocks +//-------------------------------------------------------------------------- +// Function: DataSpace::getSelectHyperNblocks +///\brief Returns number of hyperslab blocks. +///\return Number of hyperslab blocks +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hssize_t DataSpace::getSelectHyperNblocks () const { hssize_t num_blocks = H5Sget_select_hyper_nblocks( id ); @@ -233,7 +349,15 @@ hssize_t DataSpace::getSelectHyperNblocks () const return( num_blocks ); } -// Gets the list of hyperslab blocks currently selected +//-------------------------------------------------------------------------- +// Function: DataSpace::getSelectHyperBlocklist +///\brief Gets the list of hyperslab blocks currently selected +///\param startblock - IN: Hyperslab block to start with +///\param numblocks - IN: Number of hyperslab blocks to get +///\param buf - IN: List of hyperslab blocks selected +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::getSelectHyperBlocklist( hsize_t startblock, hsize_t numblocks, hsize_t *buf ) const { herr_t ret_value; @@ -245,7 +369,13 @@ void DataSpace::getSelectHyperBlocklist( hsize_t startblock, hsize_t numblocks, } } -// Gets the number of element points in the current selection +//-------------------------------------------------------------------------- +// Function: DataSpace::getSelectElemNpoints +///\brief Returns the number of element points in the current selection. +///\return Number of element points +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- hssize_t DataSpace::getSelectElemNpoints () const { hssize_t num_points = H5Sget_select_elem_npoints( id ); @@ -257,7 +387,19 @@ hssize_t DataSpace::getSelectElemNpoints () const return( num_points ); } -// Gets the list of element points currently selected +//-------------------------------------------------------------------------- +// Function: DataSpace::getSelectElemPointlist +///\brief Gets the list of element points currently selected +///\param startpoint - IN: Element point to start with +///\param numpoints - IN: Number of element points to get +///\param buf - IN: List of element points selected +///\exception H5::DataSpaceIException +///\par Description +/// For more information, please refer to the C layer Reference +/// Manual at: +/// http: +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::getSelectElemPointlist ( hsize_t startpoint, hsize_t numpoints, hsize_t *buf ) const { herr_t ret_value; @@ -269,7 +411,19 @@ void DataSpace::getSelectElemPointlist ( hsize_t startpoint, hsize_t numpoints, } } -// Gets the bounding box containing the current selection +//-------------------------------------------------------------------------- +// Function: DataSpace::getSelectBounds +///\brief Gets the bounding box containing the current selection. +///\param start - IN: Starting coordinates of the bounding box +///\param end - IN: Ending coordinates of the bounding box, i.e., +/// the coordinates of the diagonally opposite corner +///\exception H5::DataSpaceIException +///\par Description +/// For more information, please refer to the C layer Reference +/// Manual at: +/// http: +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::getSelectBounds ( hssize_t* start, hssize_t* end ) const { herr_t ret_value = H5Sget_select_bounds( id, start, end ); @@ -280,7 +434,22 @@ void DataSpace::getSelectBounds ( hssize_t* start, hssize_t* end ) const } } -// Selects array elements to be included in the selection for a dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::H5Sselect_elements +///\brief Selects array elements to be included in the selection for +/// this dataspace. +///\param op - IN: Operator specifying how the new selection is to be +/// combined with the existing selection for the dataspace +///\param num_elements - IN: Number of elements to be selected +///\param coord - IN: A 2-dimensional array of 0-based values +/// specifying the coordinates of the elements being selected +///\exception H5::DataSpaceIException +///\par Description +/// For more information, please refer to the C layer Reference +/// Manual at: +/// http: +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::selectElements ( H5S_seloper_t op, const size_t num_elements, const hssize_t *coord[ ] ) const { herr_t ret_value; @@ -292,7 +461,12 @@ void DataSpace::selectElements ( H5S_seloper_t op, const size_t num_elements, co } } -// Selects the entire dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::selectAll +///\brief Selects the entire dataspace. +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::selectAll () const { herr_t ret_value = H5Sselect_all( id ); @@ -302,7 +476,12 @@ void DataSpace::selectAll () const } } -//Resets the selection region to include no elements +//-------------------------------------------------------------------------- +// Function: DataSpace::selectNone +///\brief Resets the selection region to include no elements. +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::selectNone () const { herr_t ret_value = H5Sselect_none( id ); @@ -313,7 +492,15 @@ void DataSpace::selectNone () const } } -// Verifies that the selection is within the extent of the dataspace +//-------------------------------------------------------------------------- +// Function: DataSpace::selectValid +///\brief Verifies that the selection is within the extent of the +/// dataspace. +///\return true if the selection is within the extent of the +/// dataspace, and false, otherwise +///\exception H5::DataSpaceIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- bool DataSpace::selectValid () const { htri_t ret_value = H5Sselect_valid( id ); @@ -328,7 +515,21 @@ bool DataSpace::selectValid () const } } -// Selects a hyperslab region to add to the current selected region +//-------------------------------------------------------------------------- +// Function: DataSpace::selectHyperslab +///\brief Selects a hyperslab region to add to the current selected region. +///\param op - IN: Operation to perform on current selection +///\param count - IN: Offset of the start of hyperslab +///\param start - IN: Number of blocks included in the hyperslab +///\param stride - IN: Hyperslab stride +///\param block - IN: Size of block in the hyperslab +///\exception H5::DataSpaceIException +///\par Description +/// For more information, please refer to the C layer Reference +/// Manual at: +/// http: +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::selectHyperslab( H5S_seloper_t op, const hsize_t *count, const hssize_t *start, const hsize_t *stride, const hsize_t *block ) const { herr_t ret_value; @@ -340,7 +541,15 @@ void DataSpace::selectHyperslab( H5S_seloper_t op, const hsize_t *count, const h } } -// Closes the dataspace if it is not a constant +//-------------------------------------------------------------------------- +// Function: DataSpace::p_close (private) +///\brief Closes the dataspace if it is not a constant +///\exception H5::FileIException +///\note +/// This function will be obsolete because its functionality +/// is recently handled by the C library layer. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void DataSpace::p_close() const { hid_t space_id = id; @@ -354,11 +563,11 @@ void DataSpace::p_close() const } } -// The destructor of this instance calls IdComponent::reset to -// reset its identifier - no longer true -// Older compilers (baldric) don't support template member functions -// and IdComponent::reset is one; so at this time, the resetId is not -// a member function so it can be template to work around that problem. +//-------------------------------------------------------------------------- +// Function: DataSpace destructor +///\brief Properly terminates access to this dataspace. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- DataSpace::~DataSpace() { // The dataspace id will be closed properly diff --git a/c++/src/H5DataType.cpp b/c++/src/H5DataType.cpp index 867eb4e..1b268e7 100644 --- a/c++/src/H5DataType.cpp +++ b/c++/src/H5DataType.cpp @@ -120,8 +120,8 @@ void DataType::copy( const DataType& like_type ) // Function: DataType::operator= ///\brief Assignment operator ///\param rhs - IN: Reference to the existing datatype +///\return Reference to DataType instance ///\exception H5::DataTypeIException -/// // Description // Makes a copy of the type on the right hand side and stores // the new id in the left hand side object. @@ -458,7 +458,7 @@ void DataType::setTag( const string& tag ) const } //-------------------------------------------------------------------------- -// Function: DataType::setTag +// Function: DataType::getTag ///\brief Gets the tag associated with an opaque datatype. ///\return Tag associated with the opaque datatype ///\exception H5::DataTypeIException @@ -529,9 +529,13 @@ bool DataType::isVariableStr() const } //-------------------------------------------------------------------------- -// This private function calls the C API H5Tclose to close this datatype. -// Used by H5Object::p_reset. -// Programmer Binh-Minh Ribler - 2000 +// Function: DataType::p_close (private) +///\brief Closes this datatype. +///\exception H5::DataTypeIException +///\note +/// This function will be obsolete because its functionality +/// is recently handled by the C library layer. +// Programmer Binh-Minh Ribler - 2000 //-------------------------------------------------------------------------- void DataType::p_close() const { diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp index b87dd33..d869c6f 100644 --- a/c++/src/H5File.cpp +++ b/c++/src/H5File.cpp @@ -412,7 +412,15 @@ void H5File::getVFDHandle(void **file_handle) } } -// Calls the C API H5Fclose to close this file. Used by IdComponent::reset +//-------------------------------------------------------------------------- +// Function: H5File::p_close (private) +///\brief Closes this H5 file. +///\exception H5::FileIException +///\note +/// This function will be obsolete because its functionality +/// is recently handled by the C library layer. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void H5File::p_close() const { herr_t ret_value = H5Fclose( id ); diff --git a/c++/src/H5Object.cpp b/c++/src/H5Object.cpp index 8a0f3b1..3fd6561 100644 --- a/c++/src/H5Object.cpp +++ b/c++/src/H5Object.cpp @@ -262,7 +262,7 @@ void H5Object::removeAttr( const string& name ) const } //-------------------------------------------------------------------------- -// Function: H5Object::getNumAttrs +// Function: H5Object::flush ///\brief Flushes all buffers associated with a file to disk. ///\param scope - IN: Specifies the scope of the flushing action, /// which can be either of these values: @@ -283,6 +283,26 @@ void H5Object::flush(H5F_scope_t scope ) const } //-------------------------------------------------------------------------- +// Function: H5Object::Reference +///\brief Creates a reference. +///\param name - IN: Name of the object to be referenced +///\return A reference +///\exception H5::ReferenceIException +// Programmer Binh-Minh Ribler - May, 2004 +//-------------------------------------------------------------------------- +void* H5Object::Reference(const char* name, H5R_type_t ref_type, DataSpace& dataspace) const +{ + void *ref; + herr_t ret_value = H5Rcreate(ref, id, name, ref_type, dataspace.getId()); + if (ret_value < 0) + { + throw AttributeIException("H5Object::getNumAttrs", + "H5Aget_num_attrs failed - returned negative number of attributes"); + } + return(ref); +} + +//-------------------------------------------------------------------------- // Function: H5Object destructor ///\brief Subclasses destructors will properly terminate access to /// this H5 object. diff --git a/c++/src/H5Object.h b/c++/src/H5Object.h index cc8b891..c4113f1 100644 --- a/c++/src/H5Object.h +++ b/c++/src/H5Object.h @@ -85,6 +85,9 @@ class H5_DLLCPP H5Object : public IdComponent { void removeAttr( const string& name ) const; void removeAttr( const char* name ) const; + // Creates a reference to a named H5 object in this object. + void* Reference(const char* name, H5R_type_t ref_type, DataSpace& dataspace) const; + virtual ~H5Object(); protected: -- cgit v0.12