From 53114fe05593c5ec19858759724ddfed5b4f9310 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Sat, 22 May 2004 14:14:40 -0500 Subject: [svn-r8568] Purpose: Add documentation and a missing function - incrementally check-in (Note: these files supposed to be checked in with my checkin on May 19, but were accidentally left out. -> same log message) Description: Added wrapper for H5Tget_nmembers to H5EnumType.*; it was accidentally left out. Also, added doxygen documentation and removed outdated comments. Platforms: SunOS 5.7 (arabica) Linux 2.4 (eirene) Windows 2000 --- c++/src/H5EnumType.cpp | 183 ++++++++++++++++++++++++++++++++++++++----------- c++/src/H5EnumType.h | 3 + 2 files changed, 147 insertions(+), 39 deletions(-) diff --git a/c++/src/H5EnumType.cpp b/c++/src/H5EnumType.cpp index edbc1bc..dae2447 100644 --- a/c++/src/H5EnumType.cpp +++ b/c++/src/H5EnumType.cpp @@ -33,20 +33,48 @@ namespace H5 { #endif -// Creates an empty enumeration datatype based on a native signed -// integer type. -EnumType::EnumType( size_t size ) : DataType( H5T_ENUM, size ) {} - -// Default constructor +//-------------------------------------------------------------------------- +// Function: EnumType default constructor +///\brief Default constructor: Creates a stub datatype +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType::EnumType() : DataType() {} -// Creates a enumeration datatype using an existing id +//-------------------------------------------------------------------------- +// Function: EnumType overloaded constructor +///\brief Creates an EnumType 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 +//-------------------------------------------------------------------------- EnumType::EnumType( const hid_t existing_id ) : DataType( existing_id ) {} -// Copy constructor: makes a copy of the original EnumType object. +//-------------------------------------------------------------------------- +// Function: EnumType copy constructor +///\brief Copy constructor: makes a copy of the original EnumType object. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType::EnumType( const EnumType& original ) : DataType( original ) {} -// Gets the enum datatype of the specified dataset +//-------------------------------------------------------------------------- +// Function: EnumType overloaded constructor +///\brief Creates an empty enumeration datatype given a size, in bytes. +///\param size - IN: Number of bytes in the datatype to create +///\exception H5::DataTypeIException +// Description +// The DataType constructor calls the C API H5Tcreate to create +// the enum datatype. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +EnumType::EnumType( size_t size ) : DataType( H5T_ENUM, size ) {} + +//-------------------------------------------------------------------------- +// Function: EnumType overloaded constructor +///\brief Gets the enum datatype of the specified dataset. +///\param dataset - IN: Dataset that this enum datatype associates with +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType::EnumType( const DataSet& dataset ) : DataType() { // Calls C function H5Dget_type to get the id of the datatype @@ -59,7 +87,13 @@ EnumType::EnumType( const DataSet& dataset ) : DataType() } } -// Creates a new enum datatype based on an integer datatype +//-------------------------------------------------------------------------- +// Function: EnumType overloaded constructor +///\brief Creates a new enum datatype based on an integer datatype. +///\param data_type - IN: Base datatype +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType::EnumType( const IntType& data_type ) : DataType() { // Calls C function H5Tenum_create to get the id of the datatype @@ -72,11 +106,14 @@ EnumType::EnumType( const IntType& data_type ) : DataType() } } -// Inserts a new member to this enumeration datatype. -void EnumType::insert( const string& name, void *value ) const -{ - insert( name.c_str(), value ); -} +//-------------------------------------------------------------------------- +// Function: EnumType::insert +///\brief Inserts a new member to this enumeration datatype. +///\param name - IN: Name of the new member +///\param value - IN: Pointer to the value of the new member +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void EnumType::insert( const char* name, void *value ) const { // Calls C routine H5Tenum_insert to insert the new enum datatype member. @@ -87,7 +124,27 @@ void EnumType::insert( const char* name, void *value ) const } } -// Returns the symbol name corresponding to a specified member of an enumeration datatype. +//-------------------------------------------------------------------------- +// Function: EnumType::insert +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function only in the type of +/// argument \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void EnumType::insert( const string& name, void *value ) const +{ + insert( name.c_str(), value ); +} + +//-------------------------------------------------------------------------- +// Function: EnumType::nameOf +///\brief Returns the symbol name corresponding to a specified member +/// of this enumeration datatype. +///\param value - IN: Pointer to the value of the enum datatype +///\param size - IN: Size for the name +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- string EnumType::nameOf( void *value, size_t size ) const { char* name_C = new char[size+1]; // temporary C-string for C API @@ -102,16 +159,19 @@ string EnumType::nameOf( void *value, size_t size ) const } // otherwise, create the string to hold the datatype name and return it string name = string( name_C ); - delete name_C; + delete [] name_C; return( name ); } -// Retrieves the value corresponding to a member of an enumeration -// datatype, given the member's name. -void EnumType::valueOf( const string& name, void *value ) const -{ - valueOf( name.c_str(), value ); -} +//-------------------------------------------------------------------------- +// Function: EnumType::valueOf +///\brief Retrieves the value corresponding to a member of this +/// enumeration datatype, given the member's name. +///\param name - IN: Name of the queried member +///\param value - OUT: Pointer to the retrieved value +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void EnumType::valueOf( const char* name, void *value ) const { // Calls C routine H5Tenum_valueof to get the enum datatype value @@ -122,20 +182,28 @@ void EnumType::valueOf( const char* name, void *value ) const } } -/*------------------------------------------------------------------------- - * Function: getMemberIndex - * - * Purpose: Returns the index of a member in an enumeration data type. - * Members are stored in no particular order with numbers 0 - * through N-1, where N is the value returned by the member - * function getNmembers. - * - * Return: Success: index of the member if exists. - * Failure: DataTypeIException - * - * BMR - May 16, 2002 - *------------------------------------------------------------------------- - */ +//-------------------------------------------------------------------------- +// Function: EnumType::valueOf +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function only in the type of +/// argument \a name. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void EnumType::valueOf( const string& name, void *value ) const +{ + valueOf( name.c_str(), value ); +} + +//-------------------------------------------------------------------------- +// Function: EnumType::getMemberIndex +///\brief Returns the index of a member in this enumeration datatype. +///\param name - IN: Name of the queried member +///\return Index of the member if it exists. Index will have the value +/// between 0 and \c N-1, where \c N is the value returned by the +/// member function \c EnumType::getNmembers. +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - May 16, 2002 +//-------------------------------------------------------------------------- int EnumType::getMemberIndex(const char *name) const { int member_index = H5Tget_member_index(id, name); @@ -146,13 +214,46 @@ int EnumType::getMemberIndex(const char *name) const } return( member_index ); } + +//-------------------------------------------------------------------------- +// Function: EnumType::getMemberIndex +///\brief This is an overloaded member function, provided for convenience. +/// It differs from the above function only in the type of +/// argument \a name. +// Programmer Binh-Minh Ribler - May 16, 2002 +//-------------------------------------------------------------------------- int EnumType::getMemberIndex(const string& name) const { return(EnumType::getMemberIndex(name.c_str())); } -// Retrieves the value of a member in this enumeration datatype, given the -// member's index. +//-------------------------------------------------------------------------- +// Function: EnumType::getNmembers +///\brief Returns the number of members in this enumeration datatype. +///\return Number of members +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - May, 2004 +//-------------------------------------------------------------------------- +int EnumType::getNmembers() const +{ + int num_members = H5Tget_nmembers( id ); + if( num_members < 0 ) + { + throw DataTypeIException("CompType::getNmembers", + "H5Tget_nmembers returns negative number of members"); + } + return( num_members ); +} + +//-------------------------------------------------------------------------- +// Function: EnumType::getMemberIndex +///\brief Retrieves the value of a member in this enumeration datatype, +/// given the member's index. +///\param memb_no - IN: Index of the queried member +///\param value - OUT: Pointer to the retrieved value +///\exception H5::DataTypeIException +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- void EnumType::getMemberValue( int memb_no, void *value ) const { // Call C routine H5Tget_member_value to get the datatype member's value @@ -163,7 +264,11 @@ void EnumType::getMemberValue( int memb_no, void *value ) const } } -// Default destructor +//-------------------------------------------------------------------------- +// Function: EnumType destructor +///\brief Properly terminates access to this enum datatype. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- EnumType::~EnumType() {} #ifndef H5_NO_NAMESPACE diff --git a/c++/src/H5EnumType.h b/c++/src/H5EnumType.h index efeee26..cca253a 100644 --- a/c++/src/H5EnumType.h +++ b/c++/src/H5EnumType.h @@ -59,6 +59,9 @@ class H5_DLLCPP EnumType : public DataType { int getMemberIndex(const char* name) const; int getMemberIndex(const string& name) const; + // Returns the number of members in this enumeration datatype. + int getNmembers () const; + // Returns the value of an enumeration datatype member void getMemberValue( int memb_no, void *value ) const; -- cgit v0.12