From f5492ae03baf06d6ee68b27189e26998c4f3d35b Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Thu, 27 May 2004 15:55:53 -0500 Subject: [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: --- c++/src/H5DataSet.cpp | 5 +- c++/src/H5DataSet.h | 12 ++--- c++/src/H5IdComponent.cpp | 113 +++++++++++++++++++++++++++++++++++----------- c++/src/H5StrType.cpp | 111 +++++++++++++++++++++++++++++++++++++++------ c++/src/H5StrType.h | 3 ++ 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 -- cgit v0.12