summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-20 20:52:36 (GMT)
committerBinh-Minh Ribler <bmribler@hdfgroup.org>2004-05-20 20:52:36 (GMT)
commit7d3bfaaaa31ad4ead22a282f09f40502147ecd01 (patch)
tree375bcc610f260903d990d09b720c1e13e31a5697
parentf1bc8e830e46a23705d5ec5eee2fbc02cc8467ae (diff)
downloadhdf5-7d3bfaaaa31ad4ead22a282f09f40502147ecd01.zip
hdf5-7d3bfaaaa31ad4ead22a282f09f40502147ecd01.tar.gz
hdf5-7d3bfaaaa31ad4ead22a282f09f40502147ecd01.tar.bz2
[svn-r8554] Purpose:
Add documentation and an overloaded function - incrementally check-in Description: Added Attribute::getName that takes no argument for user's convenience. Also added Doxygen documentation to existing functions in H5Attribute.cpp. Platforms: SunOS 5.7 (arabica) Linux 2.4 (eirene) Windows 2000 Misc. update:
-rw-r--r--c++/src/H5Attribute.cpp164
-rw-r--r--c++/src/H5Attribute.h6
2 files changed, 140 insertions, 30 deletions
diff --git a/c++/src/H5Attribute.cpp b/c++/src/H5Attribute.cpp
index 5c9dfb3..c6c67a9 100644
--- a/c++/src/H5Attribute.cpp
+++ b/c++/src/H5Attribute.cpp
@@ -35,14 +35,39 @@
namespace H5 {
#endif
-// Copy constructor: makes a copy of the original object; simply invokes
-// the base class copy constructor.
+//--------------------------------------------------------------------------
+// Function: Attribute default constructor
+///\brief Default constructor: Creates a stub attribute
+// Programmer Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+Attribute::Attribute() : AbstractDs() {}
+
+//--------------------------------------------------------------------------
+// Function: Attribute copy constructor
+///\brief Copy constructor: makes a copy of the original Attribute object.
+///\param original - IN: Original Attribute object to copy
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
Attribute::Attribute( const Attribute& original ) : AbstractDs( original ) {}
-// Creates a copy of an existing attribute using an id
+//--------------------------------------------------------------------------
+// Function: Attribute overloaded constructor
+///\brief Creates an Attribute object using the id of an existing
+/// attribute.
+///\param existing_id - IN: Id of an existing attribute
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
Attribute::Attribute( const hid_t attr_id ) : AbstractDs( attr_id ) {}
-// Writes data to this attribute.
+//--------------------------------------------------------------------------
+// Function: Attribute::write
+///\brief Writes data to this attribute.
+///\param mem_type - IN: Attribute datatype (in memory)
+///\param buf - IN: Data to be written
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void Attribute::write( const DataType& mem_type, const void *buf ) const
{
herr_t ret_value = H5Awrite( id, mem_type.getId(), buf );
@@ -52,6 +77,15 @@ void Attribute::write( const DataType& mem_type, const void *buf ) const
}
}
+//--------------------------------------------------------------------------
+// Function: Attribute::write
+///\brief This is an overloaded member function, provided for convenience.
+/// It writes a \a std::string to this attribute.
+///\param mem_type - IN: Attribute datatype (in memory)
+///\param strg - IN: Data to be written
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - Apr, 2003
+//--------------------------------------------------------------------------
void Attribute::write( const DataType& mem_type, const string& strg ) const
{
// Convert string to C-string
@@ -65,7 +99,32 @@ void Attribute::write( const DataType& mem_type, const string& strg ) const
}
}
-// Reads data from this attribute.
+//--------------------------------------------------------------------------
+// Function: Attribute::read
+///\brief Reads data from this attribute.
+///\param mem_type - IN: Attribute datatype (in memory)
+///\param buf - OUT: Buffer for read data
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
+void Attribute::read( const DataType& mem_type, void *buf ) const
+{
+ herr_t ret_value = H5Aread( id, mem_type.getId(), buf );
+ if( ret_value < 0 )
+ {
+ throw AttributeIException("Attribute::read", "H5Aread failed");
+ }
+}
+
+//--------------------------------------------------------------------------
+// Function: Attribute::read
+///\brief This is an overloaded member function, provided for convenience.
+/// It reads a \a std::string from this attribute.
+///\param mem_type - IN: Attribute datatype (in memory)
+///\param strg - IN: Buffer for read string
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - Apr, 2003
+//--------------------------------------------------------------------------
void Attribute::read( const DataType& mem_type, string& strg ) const
{
size_t size = mem_type.getSize();
@@ -79,17 +138,13 @@ void Attribute::read( const DataType& mem_type, string& strg ) const
delete strg_C;
}
-// Reads data from this attribute.
-void Attribute::read( const DataType& mem_type, void *buf ) const
-{
- herr_t ret_value = H5Aread( id, mem_type.getId(), buf );
- if( ret_value < 0 )
- {
- throw AttributeIException("Attribute::read", "H5Aread failed");
- }
-}
-
-// Gets a copy of the dataspace for this attribute.
+//--------------------------------------------------------------------------
+// Function: Attribute::getSpace
+///\brief Gets a copy of the dataspace for this attribute.
+///\return Dataspace instance
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
DataSpace Attribute::getSpace() const
{
// Calls C function H5Aget_space to get the id of the dataspace
@@ -107,10 +162,15 @@ DataSpace Attribute::getSpace() const
}
}
-// This private member function calls the C API to get the generic datatype
-// of the datatype that is used by this attribute. This function is used
-// by the overloaded functions getDataType defined in AbstractDs for the
-// generic datatype and specific sub-types.
+//--------------------------------------------------------------------------
+// Function: Attribute::p_getType (private)
+// Purpose Gets the datatype of this attribute.
+// Return Id of the datatype
+// Exception H5::AttributeIException
+// Description
+// This private function is used in AbstractDs.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
hid_t Attribute::p_getType() const
{
hid_t type_id = H5Aget_type( id );
@@ -122,7 +182,15 @@ hid_t Attribute::p_getType() const
}
}
-// Gets the name of this attribute, returning its length.
+//--------------------------------------------------------------------------
+// Function: Attribute::getName
+///\brief Gets the name of this attribute, returning its length.
+///\param buf_size - IN: Desired length of the name
+///\param attr_name - OUT: Buffer for the name string
+///\return Length of the attribute name
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - Nov, 2001
+//--------------------------------------------------------------------------
ssize_t Attribute::getName( size_t buf_size, string& attr_name ) const
{
char* name_C = new char[buf_size+1]; // temporary C-string for C API
@@ -141,7 +209,16 @@ ssize_t Attribute::getName( size_t buf_size, string& attr_name ) const
return( name_size );
}
-// Gets the name of this attribute, returning the name, not the length.
+//--------------------------------------------------------------------------
+// Function: Attribute::getName
+///\brief This is an overloaded member function, provided for convenience.
+/// It differs from the above function in that it returns the
+/// attribute's name, not the length.
+///\return Name of the attribute
+///\param buf_size - IN: Desired length of the name
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
string Attribute::getName( size_t buf_size ) const
{
string attr_name;
@@ -150,8 +227,37 @@ string Attribute::getName( size_t buf_size ) const
// let caller catch exception if any
}
-// This private function calls the C API H5Aclose to close this attribute.
-// Used by the IdComponent::reset.
+//--------------------------------------------------------------------------
+// Function: Attribute::getName
+///\brief This is an overloaded member function, provided for convenience.
+/// It differs from the above functions in that it doesn't take
+/// any arguments and returns the attribute's name.
+///\return Name of the attribute
+///\exception H5::AttributeIException
+// Programmer Binh-Minh Ribler - May, 2004
+//--------------------------------------------------------------------------
+string Attribute::getName() const
+{
+ // Try with 256 characters for the name first, if the name's length
+ // returned is more than that then, read the name again with the
+ // appropriate space allocation
+ string attr_name;
+ ssize_t name_size = getName(255, attr_name);
+ if (name_size >= 256)
+ name_size = getName(name_size, attr_name);
+ return( attr_name );
+ // let caller catch exception if any
+}
+
+//--------------------------------------------------------------------------
+// Function: Attribute::p_close (private)
+///\brief Closes this attribute.
+///\exception H5::AttributeIException
+///\note
+/// This function will be obsolete because its functionality
+/// is recently handled by the C library layer. - May, 2004
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
void Attribute::p_close() const
{
herr_t ret_value = H5Aclose( id );
@@ -161,11 +267,11 @@ void Attribute::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: Attribute destructor
+///\brief Properly terminates access to this attribute.
+// Programmer Binh-Minh Ribler - 2000
+//--------------------------------------------------------------------------
Attribute::~Attribute()
{
// The attribute id will be closed properly
diff --git a/c++/src/H5Attribute.h b/c++/src/H5Attribute.h
index 7053f8c..a027fc3 100644
--- a/c++/src/H5Attribute.h
+++ b/c++/src/H5Attribute.h
@@ -36,11 +36,12 @@ class H5_DLLCPP Attribute : public AbstractDs {
// 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
+ string getName() const; // returns name, no argument
// do not inherit iterateAttrs from H5Object
int iterateAttrs() { return 0; }
- // Used by the API to appropriately close a attribute
+ // Used by the API to appropriately close an attribute
virtual void p_close() const;
// Creates a copy of an existing attribute using the attribute id
@@ -57,6 +58,9 @@ class H5_DLLCPP Attribute : public AbstractDs {
// defined in AbstractDs for generic datatype and specific
// sub-types
virtual hid_t p_getType() const;
+
+ // Default constructor
+ Attribute();
};
#ifndef H5_NO_NAMESPACE
}