[svn-r10212] Purpose: Added more wrappers

Description:
    Added the following to the C++ library
        + overloaded functions:
                string CommonFG::getObjnameByIdx(hsize_t idx)
                H5T_order_t AtomType::getOrder()
        + wrappers for H5*close
        + wrappers for H5Arename, H5Aget_storage_size, and H5Dget_storage_size

Platforms tested:
    Linux 2.4 (heping)
    AIX 5.1 (copper)
    SunOS 5.8 64-bit (sol)

c++/src/H5AbstractDs.h

@@ -30,26 +30,31 @@ class H5_DLLCPP AbstractDs : public H5Object {
 	// Note that this datatype is a generic one and can only be accessed 
 	// via generic member functions, i.e., member functions belong 
 	// to DataType.  To get specific datatype, i.e. EnumType, FloatType, 
-	// etc..., use the specific functions, that follow, instead .
+	// etc..., use the specific functions, that follow, instead.
 	DataType getDataType() const;
 
-        // Gets a copy of the specific datatype of this abstract dataset
+        // Gets a copy of the specific datatype of this abstract dataset.
         EnumType getEnumType() const;
         CompType getCompType() const;
         IntType getIntType() const;
         FloatType getFloatType() const;
         StrType getStrType() const;
 
-	// Gets the dataspace of this abstract dataset - pure virtual
+	// Gets the dataspace of this abstract dataset - pure virtual.
 	virtual DataSpace getSpace() const = 0;
 
         // Gets the class of the datatype that is used by this abstract 
-	// dataset        
+	// dataset.
 	H5T_class_t getTypeClass() const;
 
+        // Returns the amount of storage size required for this abstract 
+	// dataset - pure virtual.
+        virtual hsize_t getStorageSize() const = 0;
+
 	// Copy constructor
 	AbstractDs( const AbstractDs& original );
 
+	// Destructor
 	virtual ~AbstractDs(); 
 
    protected:

c++/src/H5AtomType.cpp

@@ -73,15 +73,14 @@ void AtomType::setSize( size_t size ) const
 //--------------------------------------------------------------------------
 // Function:	AtomType::getOrder
 ///\brief	Returns the byte order of an atomic datatype.
-///\param	order_string - OUT: Text description of the returned byte order
 ///\return	Byte order, which can be:
 ///		\li \c H5T_ORDER_LE
 ///		\li \c H5T_ORDER_BE
 ///		\li \c H5T_ORDER_VAX
 ///\exception	H5::DataTypeIException
-// Programmer	Binh-Minh Ribler - 2000
+// Programmer	Binh-Minh Ribler - Mar, 2005
 //--------------------------------------------------------------------------
-H5T_order_t AtomType::getOrder( string& order_string ) const
+H5T_order_t AtomType::getOrder() const
 {
    // Call C routine to get the byte ordering
    H5T_order_t type_order = H5Tget_order( id );
@@ -92,6 +91,32 @@ H5T_order_t AtomType::getOrder( string& order_string ) const
       throw DataTypeIException("AtomType::getOrder", 
 		"H5Tget_order returns H5T_ORDER_ERROR");
    }
+   return( type_order );
+}
+
+//--------------------------------------------------------------------------
+// Function:	AtomType::getOrder
+///\brief	This is an overloaded member function, provided for convenience.
+///             It takes a reference to a \c std::string for the buffer that
+///		provide the text description of the returned byte order.
+///		The text description can be either of the following:
+///		"Little endian byte ordering (0)";
+///		"Big endian byte ordering (1)";
+///		"VAX mixed byte ordering (2)";
+///\param	order_string - OUT: Text description of the returned byte order
+///\return	Byte order, which can be:
+///		\li \c H5T_ORDER_LE
+///		\li \c H5T_ORDER_BE
+///		\li \c H5T_ORDER_VAX
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+H5T_order_t AtomType::getOrder( string& order_string ) const
+{
+   // Call the overloaded to get the type order without text
+   H5T_order_t type_order = getOrder();
+
+   // Then provide the text and return the type order
    if( type_order == H5T_ORDER_LE )
       order_string = "Little endian byte ordering (0)";
    else if( type_order == H5T_ORDER_BE )

c++/src/H5AtomType.h

@@ -28,6 +28,7 @@ class H5_DLLCPP AtomType : public DataType {
    public:
 	// Returns the byte order of an atomic datatype. 
 	H5T_order_t getOrder( string& order_string ) const;
+	H5T_order_t getOrder() const;
 
 	// Sets the byte ordering of an atomic datatype. 
 	void setOrder( H5T_order_t order ) const;

c++/src/H5Attribute.cpp

@@ -256,6 +256,38 @@ string Attribute::getName() const
    return( attr_name ); 
 }
 
+//--------------------------------------------------------------------------
+// Function:	Attribute::close
+///\brief:	Closes this attribute.
+///\exception	H5::AttributeIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void Attribute::close()
+{
+   herr_t ret_value = H5Aclose(id);
+   if( ret_value < 0 )
+   {
+      throw AttributeIException("Attribute::close", "H5Aclose failed");
+   }
+   // reset the id because the attribute that it represents is now closed
+   id = 0;
+}
+
+//--------------------------------------------------------------------------
+// Function:	Attribute::getStorageSize
+///\brief	Returns the amount of storage size required for this attribute.
+///\return	Size of the storage or 0, for no data
+///\exception	H5::AttributeIException
+// Note:        H5Dget_storage_size returns 0 when there is no data.  This
+//              function should have no failure. (from SLU)
+// Programmer	Binh-Minh Ribler - Mar, 2005
+//--------------------------------------------------------------------------
+hsize_t Attribute::getStorageSize() const
+{
+   hsize_t storage_size = H5Aget_storage_size(id);
+   return (storage_size);
+}
+
 //--------------------------------------------------------------------------
 // Function:	Attribute destructor
 ///\brief	Properly terminates access to this attribute.

c++/src/H5Attribute.h

@@ -22,6 +22,9 @@ namespace H5 {
 
 class H5_DLLCPP Attribute : public AbstractDs {
    public:
+	// Closes this attribute.
+	virtual void close();
+
 	// Gets the name of this attribute.
 	ssize_t getName( size_t buf_size, string& attr_name ) const;
 	string getName( size_t buf_size ) const; // returns name, not its length
@@ -30,6 +33,9 @@ class H5_DLLCPP Attribute : public AbstractDs {
 	// Gets a copy of the dataspace for this attribute.
 	virtual DataSpace getSpace() const;
 
+	// Returns the amount of storage size required for this attribute.
+	hsize_t getStorageSize() const;
+
 	// Reads data from this attribute.
 	void read( const DataType& mem_type, void *buf ) const;
 	void read( const DataType& mem_type, string& strg ) const;
@@ -57,6 +63,9 @@ class H5_DLLCPP Attribute : public AbstractDs {
 	// do not inherit iterateAttrs from H5Object
 	int iterateAttrs() { return 0; }
 
+	// do not inherit iterateAttrs from H5Object
+	void rename() {}
+
 	// Default constructor
 	Attribute();
 };

c++/src/H5CommonFG.cpp

@@ -754,6 +754,40 @@ hsize_t CommonFG::getNumObjs() const
    return (num_objs);
 }
 
+//--------------------------------------------------------------------------
+// Function:	CommonFG::getObjnameByIdx
+///\brief	Returns the name of an object in this group, given the
+///		object's index.
+///\param	idx  -     IN: Transient index of the object
+///\return	Object name
+///\exception	H5::FileIException or H5::GroupIException
+///\par Description
+///		The value of idx can be any nonnegative number less than the 
+///		total number of objects in the group, which is returned by 
+///		the function \c CommonFG::getNumObjs.  Note that this is a 
+///		transient index; thus, an object may have a different index 
+///		each time the group is opened.
+// Programmer	Binh-Minh Ribler - Mar, 2005
+//--------------------------------------------------------------------------
+string CommonFG::getObjnameByIdx(hsize_t idx) const
+{
+    // call H5Gget_objname_by_idx with name as NULL to get its length
+    ssize_t name_len = H5Gget_objname_by_idx(getLocId(), idx, NULL, 0);
+    if(name_len < 0)
+    {
+      throwException("getObjnameByIdx", "H5Gget_objname_by_idx failed");
+    }
+
+    // now, allocate C buffer to get the name
+    char* name_C = new char[name_len];
+    name_len = H5Gget_objname_by_idx(getLocId(), idx, name_C, name_len);
+
+    // clean up and return the string
+    string name = string(name_C);
+    delete [] name_C;
+    return (name);
+}
+
 //--------------------------------------------------------------------------
 // Function:	CommonFG::getObjnameByIdx
 ///\brief	Retrieves the name of an object in this group, given the

c++/src/H5CommonFG.h

@@ -69,6 +69,7 @@ class H5_DLLCPP CommonFG {
 	// Retrieves the name of an object in this group, given the
 	// object's index.
 	ssize_t getObjnameByIdx(hsize_t idx, string& name, size_t size) const;
+	string getObjnameByIdx(hsize_t idx) const;
 
 	// Returns the type of an object in this group, given the
 	// object's index.

c++/src/H5CompType.cpp

@@ -208,6 +208,10 @@ H5T_class_t CompType::getMemberClass( unsigned member_num ) const
       throw DataTypeIException("CompType::getMemberClass", 
 		"H5Tget_class returns H5T_NO_CLASS");
    }
+
+   // close the member datatype
+   H5Tclose(member_type_id);
+
    return( member_class );
 }
 

c++/src/H5DataSet.cpp

@@ -118,20 +118,16 @@ DSetCreatPropList DataSet::getCreatePlist() const
 //--------------------------------------------------------------------------
 // Function:	DataSet::getStorageSize
 ///\brief	Returns the amount of storage required for a dataset.  
-///\return	Amount of storage
+///\return	Size of the storage or 0, for no data
 ///\exception	H5::DataSetIException
-// Programmer	Binh-Minh Ribler - 2000
+// Note:	H5Dget_storage_size returns 0 when there is no data.  This
+//		function should have no failure. (from SLU)
+// Programmer	Binh-Minh Ribler - Mar, 2005
 //--------------------------------------------------------------------------
 hsize_t DataSet::getStorageSize() const
 {
-   hsize_t storage_size = H5Dget_storage_size( id );
-
-   if( storage_size > 0 )  // checking with Quincey for failure value - BMR
-      return( storage_size );
-   else
-   {
-      throw DataSetIException("DataSet::getStorageSize", "H5Dget_storage_size failed");
-   }
+   hsize_t storage_size = H5Dget_storage_size(id);
+   return(storage_size);
 }
 
 //--------------------------------------------------------------------------
@@ -187,13 +183,13 @@ hsize_t DataSet::getVlenBufSize( DataType& type, DataSpace& space ) const
    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");
+      throw DataSetIException("DataSet::getVlenBufSize", "H5Dvlen_get_buf_size failed");
    }
    return( size );
 }
 
 //--------------------------------------------------------------------------
-// Function:	DataSet::getVlenBufSize
+// Function:	DataSet::vlenReclaim
 ///\brief	Reclaims VL datatype memory buffers. 
 ///\param	type - IN: Datatype, which is the datatype stored in the buffer
 ///\param	space - IN: Selection for the memory buffer to free the 
@@ -478,6 +474,23 @@ DataSpace DataSet::getRegion(void *ref, H5R_type_t ref_type) const
    return(dataspace);
 }
 
+//--------------------------------------------------------------------------
+// Function:	DataSet::close
+///\brief	Closes this dataset.
+///\exception	H5::DataSetIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void DataSet::close()
+{
+   herr_t ret_value = H5Dclose( id );
+   if( ret_value < 0 )
+   {
+      throw DataSetIException("DataSet::close", "H5Dclose failed");
+   }
+   // reset the id because the group that it represents is now closed
+   id = 0;
+}
+
 //--------------------------------------------------------------------------
 // Function:	DataSet destructor
 ///\brief	Properly terminates access to this dataset.

c++/src/H5DataSet.h

@@ -24,6 +24,9 @@ namespace H5 {
 
 class H5_DLLCPP DataSet : public AbstractDs {
    public:
+	// Close this dataset.
+	virtual void close();
+
 	// Extends the dataset with unlimited dimension.
 	void extend( const hsize_t* size ) const;
 
@@ -44,7 +47,7 @@ class H5_DLLCPP DataSet : public AbstractDs {
 	// Determines whether space has been allocated for a dataset.
 	void getSpaceStatus(H5D_space_status_t& status) const;
 
-	// Gets the storage size of this dataset.
+	// Returns the amount of storage size required for this dataset.
 	hsize_t getStorageSize() const;
 
 	// not yet implemented??

c++/src/H5DataSpace.cpp

@@ -537,6 +537,28 @@ void DataSpace::selectHyperslab( H5S_seloper_t op, const hsize_t *count, const h
    }
 }
 
+//--------------------------------------------------------------------------
+// Function:	DataSpace::close
+///\brief	Closes this dataspace.
+///\exception	H5::DataSpaceIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void DataSpace::close()
+{
+   if( id != H5S_ALL ) // not a constant, should call H5Sclose
+   {
+      herr_t ret_value = H5Sclose(id);
+      if( ret_value < 0 )
+      {
+         throw DataSpaceIException("DataSpace::close", "H5Sclose failed");
+      }
+      // reset the id because the dataspace that it represents is now closed
+      id = 0;
+   }
+   else // cannot close a constant
+      throw DataSpaceIException("DataSpace::close", "Cannot close a constant");
+}
+
 //--------------------------------------------------------------------------
 // Function:	DataSpace destructor
 ///\brief	Properly terminates access to this dataspace.
@@ -554,7 +576,7 @@ DataSpace::~DataSpace()
          decRefCount();
       }
       catch (Exception close_error) {
-         throw DataSpaceIException("DataSpace::copy", close_error.getDetailMsg());
+	 cerr << "DataSpace::~DataSpace - " << close_error.getDetailMsg() << endl;
       }
    }  // if
 }  

c++/src/H5DataSpace.h

@@ -34,6 +34,9 @@ class H5_DLLCPP DataSpace : public IdComponent {
 	// Assignment operator
 	DataSpace& operator=( const DataSpace& rhs );
 
+        // Closes this dataspace.
+        virtual void close();
+
 	// Makes copy of an existing dataspace.
 	void copy(const DataSpace& like_space);
 

c++/src/H5DataType.cpp

@@ -597,6 +597,29 @@ DataSpace DataType::getRegion(void *ref, H5R_type_t ref_type) const
    return(dataspace);
 }
 
+//--------------------------------------------------------------------------
+// Function:	DataType::close
+///\brief	Closes the datatype if it is not a predefined type.
+///\exception	H5::DataTypeIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void DataType::close()
+{
+   // If this datatype is not a predefined type, call H5Tclose on it.
+   if( is_predtype == false )
+   {
+      herr_t ret_value = H5Tclose(id);
+      if( ret_value < 0 )
+      {
+         throw DataTypeIException("DataType::close", "H5Tclose failed");
+      }
+      // reset the id because the datatype that it represents is now closed
+      id = 0;
+   }
+   else // cannot close a predefined type
+      throw DataTypeIException("DataType::close", "Cannot close a predefined type");
+}
+
 //--------------------------------------------------------------------------
 // Function:	DataType destructor
 ///\brief	Properly terminates access to this datatype.

c++/src/H5DataType.h

@@ -28,6 +28,9 @@ class H5_DLLCPP DataType : public H5Object {
 	// Copy constructor: makes a copy of the original object
 	DataType( const DataType& original );
 
+	// Closes this datatype.
+	virtual void close();
+
 	// Copies an existing datatype to this datatype object
 	void copy( const DataType& like_type );
 

c++/src/H5File.cpp

@@ -531,6 +531,23 @@ hid_t H5File::getLocId() const
    return( getId() );
 }
 
+//--------------------------------------------------------------------------
+// Function:	H5File::close
+///\brief	Closes this HDF5 file.
+///\exception	H5::FileIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void H5File::close()
+{
+   herr_t ret_value = H5Fclose( id );
+   if( ret_value < 0 )
+   {
+      throw FileIException("H5File::close", "H5Fclose failed");
+   }
+   // reset the id because the file that it represents is now closed
+   id = 0;
+}
+
 //--------------------------------------------------------------------------
 // Function:	H5File::throwException
 ///\brief	Throws file exception - initially implemented for CommonFG

c++/src/H5File.h

@@ -30,6 +30,9 @@ class H5_DLLCPP H5File : public IdComponent, public CommonFG {
 	   const FileCreatPropList& create_plist = FileCreatPropList::DEFAULT,
 	   const FileAccPropList& access_plist = FileAccPropList::DEFAULT );
 
+        // Close this file.
+        virtual void close();
+
 	// Gets the access property list of this file.
 	FileAccPropList getAccessPlist() const;
 

c++/src/H5Group.cpp

@@ -141,6 +141,23 @@ DataSpace Group::getRegion(void *ref, H5R_type_t ref_type) const
    return(dataspace);
 }
 
+//--------------------------------------------------------------------------
+// Function:	Group::close
+///\brief	Closes this group.
+///\exception	H5::GroupIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void Group::close()
+{
+   herr_t ret_value = H5Gclose( id );
+   if( ret_value < 0 )
+   {
+      throw GroupIException("Group::close", "H5Gclose failed");
+   }
+   // reset the id because the group that it represents is now closed
+   id = 0;
+}
+
 //--------------------------------------------------------------------------
 // Function:	Group::throwException
 ///\brief	Throws H5::GroupIException.

c++/src/H5Group.h

@@ -22,6 +22,9 @@ namespace H5 {
 
 class H5_DLLCPP Group : public H5Object, public CommonFG {
    public:
+        // Close this group.
+        virtual void close();
+
 	// Retrieves the type of object that an object reference points to.
 	H5G_obj_t getObjType(void *ref, H5R_type_t ref_type) const;
 

c++/src/H5Object.cpp

@@ -268,6 +268,35 @@ void H5Object::removeAttr( const string& name ) const
    removeAttr( name.c_str() );
 }
 
+//--------------------------------------------------------------------------
+// Function:	H5Object::renameAttr
+///\brief	Renames the named attribute from this object.
+///\param	oldname - IN: Name of the attribute to be renamed
+///\param	newname - IN: New name ame of the attribute
+///\exception	H5::AttributeIException
+// Programmer	Binh-Minh Ribler - Mar, 2005
+//--------------------------------------------------------------------------
+void H5Object::renameAttr(const char* oldname, const char* newname) const
+{
+   herr_t ret_value = H5Arename(id, oldname, newname);
+   if (ret_value < 0)
+   {
+      throw AttributeIException("H5Object::renameAttr", "H5Arename failed");
+   }
+}
+
+//--------------------------------------------------------------------------
+// Function:	H5Object::renameAttr
+///\brief	This is an overloaded member function, provided for convenience.
+///		It differs from the above function in that it takes 
+///		a reference to an \c std::string for the names.
+// Programmer	Binh-Minh Ribler - Mar, 2005
+//--------------------------------------------------------------------------
+void H5Object::renameAttr(const string& oldname, const string& newname) const
+{
+   renameAttr (oldname.c_str(), newname.c_str());
+}
+
 //--------------------------------------------------------------------------
 // Function:	H5Object::flush
 ///\brief	Flushes all buffers associated with a file to disk.

c++/src/H5Object.h

@@ -76,6 +76,10 @@ class H5_DLLCPP H5Object : public IdComponent {
 	void removeAttr( const char* name ) const;
 	void removeAttr( const string& name ) const;
 
+	// Renames the attribute to a new name.
+	void renameAttr(const char* oldname, const char* newname) const;
+	void renameAttr(const string& oldname, const string& newname) const;
+
 	// Copy constructor: makes copy of an H5Object object.
 	H5Object(const H5Object& original);
 

c++/src/H5PropList.cpp

@@ -160,6 +160,27 @@ void PropList::copyProp( PropList& dest, PropList& src, const string& name ) con
    copyProp( dest, src, name.c_str());
 }
 
+//--------------------------------------------------------------------------
+// Function:	PropList::close
+///\brief	Closes the property list if it is not a default one.
+///\exception	H5::PropListIException
+// Programmer	Binh-Minh Ribler - Mar 9, 2005
+//--------------------------------------------------------------------------
+void PropList::close()
+{
+   if( id != H5P_NO_CLASS ) // not a constant, should call H5Pclose
+   {
+      herr_t ret_value = H5Pclose( id );
+      if( ret_value < 0 )
+      {
+         throw PropListIException("PropList::close", "H5Pclose failed");
+      }
+      // reset the id because the property list that it represents is now closed
+      id = 0;
+   }
+   else
+      throw PropListIException("PropList::close", "Cannot close a constant");
+}
 
 //--------------------------------------------------------------------------
 // Function:	PropList::getClass

c++/src/H5PropList.h

@@ -35,6 +35,9 @@ class H5_DLLCPP PropList : public IdComponent {
 	// Compares this property list or class against the given list or class.
 	bool operator==(const PropList& rhs) const;
 
+        // Close this property list.
+        virtual void close();
+
 	// Close a property list class.
 	void closeClass() const;