From 7d3bfaaaa31ad4ead22a282f09f40502147ecd01 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Thu, 20 May 2004 15:52:36 -0500 Subject: [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: --- c++/src/H5Attribute.cpp | 164 +++++++++++++++++++++++++++++++++++++++--------- c++/src/H5Attribute.h | 6 +- 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 } -- cgit v0.12