summaryrefslogtreecommitdiffstats
path: root/c++
diff options
context:
space:
mode:
authorBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-27 20:55:53 (GMT)
committerBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-27 20:55:53 (GMT)
commitf5492ae03baf06d6ee68b27189e26998c4f3d35b (patch)
tree20ec104637b9743b335906a2fb9a661f7aa3477b /c++
parent2ce06c39120fe3d89c0faa1c948b5a0399e968e2 (diff)
downloadhdf5-f5492ae03baf06d6ee68b27189e26998c4f3d35b.zip
hdf5-f5492ae03baf06d6ee68b27189e26998c4f3d35b.tar.gz
hdf5-f5492ae03baf06d6ee68b27189e26998c4f3d35b.tar.bz2
[svn-r8593] Purpose:
Add more C++ wrapper and documentation - incrementally check-in Description Added another overloaded constructor to StrType. Added doxygen documentation to H5IdComponent.cpp. Corrected some comments. This is an incremental check-in to preserve the code, corresponding tests will follow in a few weeks. Platforms: SunOS 5.7 (arabica) Linux 2.4 (eirene) Misc. update:
Diffstat (limited to 'c++')
-rw-r--r--c++/src/H5DataSet.cpp5
-rw-r--r--c++/src/H5DataSet.h12
-rw-r--r--c++/src/H5IdComponent.cpp113
-rw-r--r--c++/src/H5StrType.cpp111
-rw-r--r--c++/src/H5StrType.h3
5 files changed, 195 insertions, 49 deletions
diff --git a/c++/src/H5DataSet.cpp b/c++/src/H5DataSet.cpp
index b8ee423..112b3fa 100644
--- a/c++/src/H5DataSet.cpp
+++ b/c++/src/H5DataSet.cpp
@@ -51,7 +51,7 @@ DataSet::DataSet() : AbstractDs() {}
///\param existing_id - IN: Id of an existing dataset
// Programmer Binh-Minh Ribler - 2000
//--------------------------------------------------------------------------
-DataSet::DataSet( const hid_t dataset_id ) : AbstractDs( dataset_id ) {}
+DataSet::DataSet(const hid_t existing_id) : AbstractDs(existing_id) {}
//--------------------------------------------------------------------------
// Function: DataSet copy constructor
@@ -196,7 +196,8 @@ hsize_t DataSet::getVlenBufSize( DataType& type, DataSpace& space ) const
//--------------------------------------------------------------------------
// Function: DataSet::getVlenBufSize
///\brief Reclaims VL datatype memory buffers.
-///\param dataspace - IN: Selection for the memory buffer to free the
+///\param type - IN: Datatype, which is the datatype stored in the buffer
+///\param space - 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
diff --git a/c++/src/H5DataSet.h b/c++/src/H5DataSet.h
index 39640ea..6960757 100644
--- a/c++/src/H5DataSet.h
+++ b/c++/src/H5DataSet.h
@@ -79,18 +79,16 @@ class H5_DLLCPP DataSet : public AbstractDs {
// Retrieves a dataspace with the region pointed to selected.
DataSpace getRegion(void *ref, H5R_type_t ref_type = H5R_DATASET_REGION) const;
- // Creates a copy of an existing DataSet using its id
- // Note: used by CommonFG to return a DataSet; should be modified
- // to use friend template function instead)
- DataSet( const hid_t dataset_id );
+ // Creates a copy of an existing DataSet using its id.
+ DataSet(const hid_t existing_id);
- // Used by the API to appropriately close a dataset
+ // Used by the API to appropriately close a dataset.
virtual void p_close() const;
- // Default constructor
+ // Default constructor.
DataSet();
- // Copy constructor
+ // Copy constructor.
DataSet( const DataSet& original );
virtual ~DataSet();
diff --git a/c++/src/H5IdComponent.cpp b/c++/src/H5IdComponent.cpp
index 4056dc2..a9c3520 100644
--- a/c++/src/H5IdComponent.cpp
+++ b/c++/src/H5IdComponent.cpp
@@ -25,22 +25,37 @@
namespace H5 {
#endif
-// Default constructor - private
+//--------------------------------------------------------------------------
+// Function: IdComponent default constructor - private
+///\brief Default constructor.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
IdComponent::IdComponent() : id( -1 )
{
// starts counting object references
ref_count = new RefCounter;
}
-// Constructor that takes an HDF5 object id. It creates an instance
-// of IdComponent to hold the HDF5 id
+//--------------------------------------------------------------------------
+// Function: IdComponent overloaded constructor
+///\brief Creates an IdComponent object using the id of an existing object.
+///\param h5_id - IN: Id of an existing object
+///\exception H5::DataTypeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+
IdComponent::IdComponent( const hid_t h5_id ) : id( h5_id )
{
// starts counting object references
ref_count = new RefCounter;
}
-// Copy constructor: makes a copy of the original object
+//--------------------------------------------------------------------------
+// Function: IdComponent copy constructor
+///\brief Copy constructor: makes a copy of the original IdComponent object.
+///\param original - IN: IdComponent instance to copy
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
IdComponent::IdComponent( const IdComponent& original )
{
id = original.id;
@@ -48,17 +63,36 @@ IdComponent::IdComponent( const IdComponent& original )
ref_count->increment(); // increment number of references to this id
}
-// Increment reference counter
+//--------------------------------------------------------------------------
+// Function: IdComponent::incRefCount
+///\brief Increment id reference counter.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void IdComponent::incRefCount() { ref_count->increment(); }
-// Decrement reference counter
+//--------------------------------------------------------------------------
+// Function: IdComponent::decRefCount
+///\brief Decrement id reference counter.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void IdComponent::decRefCount() { ref_count->decrement(); }
-// Get the reference counter to this identifier
+//--------------------------------------------------------------------------
+// Function: IdComponent::getCounter
+///\brief Returns the reference counter to this identifier.
+///\return Reference count
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
int IdComponent::getCounter() { return( ref_count->getCounter()); }
-// Decrements the reference counter then determines if there are no more
-// reference to this object
+//--------------------------------------------------------------------------
+// Function: IdComponent::noReference
+///\brief Decrements the reference counter then determines if there
+/// are no more reference to this object.
+///\return true if there are no more reference to this object, and false,
+/// otherwise
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
bool IdComponent::noReference()
{
if( ref_count->getCounter() > 0 )
@@ -66,13 +100,20 @@ bool IdComponent::noReference()
return( ref_count->getCounter() == 0 ? true:false );
}
-/* Assignment operator.
- Description:
- Reset the identifier of this object so that the HDF5 id can be properly
- closed. Copy the new identifier to this object, then increment the
- reference counter of the identifier to indicate that another object
- is referencing the identifier.
-*/
+//--------------------------------------------------------------------------
+// Function: IdComponent::operator=
+///\brief Assignment operator.
+///\param rhs - IN: Reference to the existing object
+///\return Reference to IdComponent instance
+///\exception H5::IdComponentException when attempt to close the HDF5
+/// object fails
+// Description
+// Reset the identifier of this object so that the HDF5 id can
+// be properly closed. Copy the id from rhs to this object,
+// then increment the reference counter of the id to indicate
+// that another object is referencing it.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
IdComponent& IdComponent::operator=( const IdComponent& rhs )
{
// reset the identifier of this object - resetIdComponent will call the
@@ -93,13 +134,18 @@ IdComponent& IdComponent::operator=( const IdComponent& rhs )
return( *this );
}
-/* Sets the identifier of this object to a new value
- Description:
- Reset the current identifier of this object so that the HDF5
- id can be appropriately closed. If only this object references
- its identifier, its reference counter will be deleted. A new
- reference counter is created for the new HDF5 object id.
-*/
+//--------------------------------------------------------------------------
+// Function: IdComponent::incRefCount
+///\brief Sets the identifier of this object to a new value.
+///\exception H5::IdComponentException when the attempt to close the HDF5
+/// object fails
+// Description:
+// Reset the current id of this object so that the HDF5
+// id can be appropriately closed. If only this object references
+// its id, its reference counter will be deleted. A new
+// reference counter is created for the new HDF5 object id.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void IdComponent::setId( hid_t new_id )
{
// reset the identifier of this object, call appropriate H5Xclose
@@ -115,20 +161,33 @@ void IdComponent::setId( hid_t new_id )
ref_count = new RefCounter;
}
-// Gets the id of this object
+//--------------------------------------------------------------------------
+// Function: IdComponent::incRefCount
+///\brief Returns the id of this object
+///\return HDF5 id
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
hid_t IdComponent::getId () const
{
return( id );
}
-// Reset this object by deleting its RefCounter
+//--------------------------------------------------------------------------
+// Function: IdComponent::reset
+///\brief Reset the reference counter of this object.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void IdComponent::reset ()
{
delete ref_count;
ref_count = NULL;
}
-// Default destructor
+//--------------------------------------------------------------------------
+// Function: IdComponent destructor
+///\brief Noop destructor.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
IdComponent::~IdComponent() {
/* uncomment this block and complete it when deciding to use dontAtExit
@@ -156,7 +215,7 @@ IdComponent::~IdComponent() {
}
//
-// Implementation for HDF5 Reference Interface
+// Implementation of protected functions for HDF5 Reference Interface.
//
//--------------------------------------------------------------------------
diff --git a/c++/src/H5StrType.cpp b/c++/src/H5StrType.cpp
index 683fc0b..1961365 100644
--- a/c++/src/H5StrType.cpp
+++ b/c++/src/H5StrType.cpp
@@ -33,19 +33,45 @@
namespace H5 {
#endif
-// Default constructor
+//--------------------------------------------------------------------------
+// Function: StrType default constructor
+///\brief Default constructor: Creates a stub string datatype
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::StrType() : AtomType() {}
-// Creates a string type using a predefined type
+//--------------------------------------------------------------------------
+// Function: StrType overloaded constructor
+///\brief Creates a string datatype using a predefined type.
+///\param pred_type - IN: Predefined datatype
+///\exception H5::DataTypeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::StrType( const PredType& pred_type ) : AtomType()
{
// use DataType::copy to make a copy of this predefined type
copy( pred_type );
}
-// Creates a string type with a specified length - 1st argument could
-// have been skipped, but this constructor will collide with the one
-// that takes an existing id below
+//--------------------------------------------------------------------------
+// Function: StrType overloaded constructor
+///\brief Creates a string datatype with a specified length
+///\param existing_id - IN: Id of an existing datatype
+///\exception H5::DataTypeIException
+// Description
+// The 1st argument could have been skipped, but this
+// constructor will collide with the one that takes an
+// existing id.
+//
+// Update: by passing 'size' by reference will avoid the
+// clashing problem, so the 1st argument can actually be
+// omitted. This constructor should be replaced by the
+// other after announcing. - May, 2004
+///\note
+/// This constructor will be obsolete in later releases,
+/// please use StrType( const size_t& size ) instead.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::StrType( const PredType& pred_type, const size_t size ) : AtomType()
{
// use DataType::copy to make a copy of the string predefined type
@@ -53,14 +79,37 @@ StrType::StrType( const PredType& pred_type, const size_t size ) : AtomType()
copy(pred_type);
setSize(size);
}
+StrType::StrType( const size_t& size ) : AtomType()
+{
+ // use DataType::copy to make a copy of the string predefined type
+ // then set its length
+ copy(H5T_C_S1);
+ setSize(size);
+}
-// Creates a string datatype using an existing id
+//--------------------------------------------------------------------------
+// Function: StrType overloaded constructor
+///\brief Creates an StrType object using the id of an existing datatype.
+///\param existing_id - IN: Id of an existing datatype
+///\exception H5::DataTypeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::StrType( const hid_t existing_id ) : AtomType( existing_id ) {}
-// Copy constructor: makes copy of the original StrType object
+//--------------------------------------------------------------------------
+// Function: StrType copy constructor
+///\brief Copy constructor: makes a copy of the original StrType object.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::StrType( const StrType& original ) : AtomType ( original ) {}
-// Gets the string datatype of the specified dataset - will reimplement - BMR
+//--------------------------------------------------------------------------
+// Function: EnumType overloaded constructor
+///\brief Gets the string datatype of the specified dataset
+///\param dataset - IN: Dataset that this string datatype associates with
+///\exception H5::DataTypeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::StrType( const DataSet& dataset ) : AtomType ()
{
// Calls C function H5Dget_type to get the id of the datatype
@@ -72,7 +121,14 @@ StrType::StrType( const DataSet& dataset ) : AtomType ()
}
}
-// Retrieves the character set type of a string datatype.
+//--------------------------------------------------------------------------
+// Function: StrType::getCset
+///\brief Retrieves the character set type of this string datatype.
+///\return Character set type, which can be:
+/// \li \c H5T_CSET_ASCII (0) - Character set is US ASCII.
+///\exception H5::DataTypeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
H5T_cset_t StrType::getCset() const
{
H5T_cset_t cset = H5Tget_cset( id );
@@ -85,7 +141,14 @@ H5T_cset_t StrType::getCset() const
return( cset );
}
-// Sets character set to be used.
+//--------------------------------------------------------------------------
+// Function: StrType::setCset
+///\brief Sets character set to be used.
+///\param cset - IN: character set type
+///\exception H5::DataTypeIException
+/// \li \c H5T_CSET_ASCII (0) - Character set is US ASCII.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void StrType::setCset( H5T_cset_t cset ) const
{
herr_t ret_value = H5Tset_cset( id, cset );
@@ -96,7 +159,16 @@ void StrType::setCset( H5T_cset_t cset ) const
}
}
-// Retrieves the string padding method for a string datatype.
+//--------------------------------------------------------------------------
+// Function: StrType::getCset
+///\brief Retrieves the storage mechanism for of this string datatype.
+///\return String storage mechanism, which can be:
+/// \li \c H5T_STR_NULLTERM (0) - Null terminate (as C does)
+/// \li \c H5T_STR_NULLPAD (0) - Pad with zeros
+/// \li \c H5T_STR_SPACEPAD (0) - pad with spaces (as FORTRAN does)
+///\exception H5::DataTypeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
H5T_str_t StrType::getStrpad() const
{
H5T_str_t strpad = H5Tget_strpad( id );
@@ -110,7 +182,16 @@ H5T_str_t StrType::getStrpad() const
return( strpad );
}
-// Defines the storage mechanism for character strings.
+//--------------------------------------------------------------------------
+// Function: StrType::setStrpad
+///\brief Defines the storage mechanism for this string datatype.
+///\param strpad - IN: String padding type
+///\exception H5::DataTypeIException
+///\par Description
+/// For detail, please refer to the C layer Reference Manual at:
+/// http://hdf.ncsa.uiuc.edu/HDF5/doc/RM_H5T.html#Datatype-SetStrpad
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void StrType::setStrpad( H5T_str_t strpad ) const
{
herr_t ret_value = H5Tset_strpad( id, strpad );
@@ -121,7 +202,11 @@ void StrType::setStrpad( H5T_str_t strpad ) const
}
}
-// This destructor terminates access to the datatype
+//--------------------------------------------------------------------------
+// Function: StrType destructor
+///\brief Properly terminates access to this string datatype.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
StrType::~StrType() {}
#ifndef H5_NO_NAMESPACE
diff --git a/c++/src/H5StrType.h b/c++/src/H5StrType.h
index 8d6070c..6ee6025 100644
--- a/c++/src/H5StrType.h
+++ b/c++/src/H5StrType.h
@@ -29,6 +29,9 @@ class H5_DLLCPP StrType : public AtomType {
StrType( const PredType& pred_type );
// Creates a string type with specified length
+ StrType( const size_t& size );
+
+ // Creates a string type with specified length - will be obsolete
StrType( const PredType& pred_type, const size_t size );
// Creates a string datatype using an existing id