philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r8576] Purpose:

Browse Source 
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:
This commit is contained in:
Binh-Minh Ribler
2004-05-26 02:02:51 -05:00
parent 2e588eef3f
commit 80816a3dde
7 changed files with 871 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
c++/src/H5DataSpace.cpp
View File

@@ -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