summaryrefslogtreecommitdiffstats
path: root/c++/src
diff options
context:
space:
mode:
authorBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-26 07:02:51 (GMT)
committerBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-26 07:02:51 (GMT)
commit80816a3dde8614c52d80f0090f8a5d08fc4546e7 (patch)
tree1b32a2bdc1d0831783a4f513b46f1885b968b6b8 /c++/src
parent2e588eef3fe7e7108168d095d385502fd8e41b9d (diff)
downloadhdf5-80816a3dde8614c52d80f0090f8a5d08fc4546e7.zip
hdf5-80816a3dde8614c52d80f0090f8a5d08fc4546e7.tar.gz
hdf5-80816a3dde8614c52d80f0090f8a5d08fc4546e7.tar.bz2
[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:
Diffstat (limited to 'c++/src')
-rw-r--r--c++/src/H5CommonFG.cpp478
-rw-r--r--c++/src/H5DataSet.cpp230
-rw-r--r--c++/src/H5DataSpace.cpp297
-rw-r--r--c++/src/H5DataType.cpp14
-rw-r--r--c++/src/H5File.cpp10
-rw-r--r--c++/src/H5Object.cpp22
-rw-r--r--c++/src/H5Object.h3
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: