From 370e6f3f56bafa13c19eaa292a16929a8b918120 Mon Sep 17 00:00:00 2001 From: Binh-Minh Ribler Date: Tue, 15 Oct 2013 00:31:20 -0500 Subject: [svn-r24291] Description: - Added a lot of documentation to classes for Reference Manual. - Fixed some format inconsistencies Platforms tested: Linux/ppc64 (ostrich) Linux/32 2.6 (jam) Linux/64 2.6 (koala)/PGI compilers --- c++/src/H5AbstractDs.h | 13 +++++++----- c++/src/H5ArrayType.h | 7 ++++--- c++/src/H5AtomType.h | 12 ++++++----- c++/src/H5Attribute.h | 10 +++++++++ c++/src/H5CommonFG.h | 10 +++++---- c++/src/H5CompType.h | 7 ++++--- c++/src/H5CppDoc.h | 22 ++++++++++---------- c++/src/H5DataSet.h | 21 ++++++++++++------- c++/src/H5DataSpace.h | 6 +++--- c++/src/H5DataType.cpp | 43 ++++---------------------------------- c++/src/H5DataType.h | 13 ++++++++---- c++/src/H5DcreatProp.h | 4 ++++ c++/src/H5DxferProp.h | 4 ++++ c++/src/H5EnumType.h | 1 + c++/src/H5Exception.h | 13 ++++++++---- c++/src/H5FaccProp.h | 2 +- c++/src/H5FcreatProp.h | 2 +- c++/src/H5File.cpp | 30 +++++++++++++-------------- c++/src/H5File.h | 18 +++++++++------- c++/src/H5FloatType.h | 1 + c++/src/H5Group.cpp | 12 +---------- c++/src/H5Group.h | 11 +++++++--- c++/src/H5IdComponent.h | 12 +++++++---- c++/src/H5IntType.h | 1 + c++/src/H5Library.h | 6 ++++++ c++/src/H5Location.cpp | 18 ++++++++-------- c++/src/H5Location.h | 26 +++++++++++++---------- c++/src/H5Object.h | 6 ++++++ c++/src/H5PredType.cpp | 14 ++----------- c++/src/H5PredType.h | 45 ++++++++++++++++++++++------------------ c++/src/H5PropList.h | 1 + c++/src/H5StrType.h | 1 + c++/src/H5VarLenType.h | 4 +--- c++/test/tfile.cpp | 55 ++++++++++++++++++++++++------------------------- 34 files changed, 237 insertions(+), 214 deletions(-) diff --git a/c++/src/H5AbstractDs.h b/c++/src/H5AbstractDs.h index 6635f78..01d05b8 100644 --- a/c++/src/H5AbstractDs.h +++ b/c++/src/H5AbstractDs.h @@ -14,11 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class AbstractDs is an abstract base class, from which Attribute and -// DataSet inherit. It provides the services that are common to both -// Attribute and DataSet. It also inherits from H5Object and passes down -// the services that H5Object provides. - #ifndef __AbstractDs_H #define __AbstractDs_H @@ -33,6 +28,14 @@ class FloatType; class IntType; class StrType; class VarLenType; + +/*! \class AbstractDs + \brief AbstractDs is an abstract base class, inherited by Attribute + and DataSet. + + It provides a collection of services that are common to both Attribute + and DataSet. AbstractDs inherits from H5Object. +*/ class H5_DLLCPP AbstractDs { public: // Gets a copy the datatype of that this abstract dataset uses. diff --git a/c++/src/H5ArrayType.h b/c++/src/H5ArrayType.h index d2e3c29..511126e 100644 --- a/c++/src/H5ArrayType.h +++ b/c++/src/H5ArrayType.h @@ -14,9 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class ArrayType inherits from DataType and provides wrappers for the -// HDF5 C's Array Datatypes. - #ifndef __H5ArrayType_H #define __H5ArrayType_H @@ -24,6 +21,10 @@ namespace H5 { #endif +/*! \class ArrayType + \brief Class ArrayType inherits from DataType and provides wrappers for + the HDF5's Array Datatypes. +*/ class H5_DLLCPP ArrayType : public DataType { public: // Constructor that creates a new array data type based on the diff --git a/c++/src/H5AtomType.h b/c++/src/H5AtomType.h index e8d6513..792312a 100644 --- a/c++/src/H5AtomType.h +++ b/c++/src/H5AtomType.h @@ -14,11 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class AtomType is a base class, from which IntType, FloatType, StrType, -// and PredType inherit. It provides the services that are common to these -// subclasses. It also inherits from DataType and passes down the -// services that are common to all the datatypes. - #ifndef __H5AtomType_H #define __H5AtomType_H @@ -26,6 +21,13 @@ namespace H5 { #endif +/*! \class AtomType + \brief AtomType is a base class, inherited by IntType, FloatType, + StrType, and PredType. + + AtomType provides operations on HDF5 atomic datatypes. It also inherits + from DataType. +*/ class H5_DLLCPP AtomType : public DataType { public: // Returns the byte order of an atomic datatype. diff --git a/c++/src/H5Attribute.h b/c++/src/H5Attribute.h index 2d01205..dbfbbb2 100644 --- a/c++/src/H5Attribute.h +++ b/c++/src/H5Attribute.h @@ -21,6 +21,14 @@ namespace H5 { #endif +/*! \class Attribute + \brief Class Attribute operates on HDF5 attributes. + + An attribute has many characteristics similar to a dataset, thus both + Attribute and DataSet are derivatives of AbstractDs. Attribute also + inherits from IdComponent because an attribute is an HDF5 component that + is identified by an identifier. +*/ class H5_DLLCPP Attribute : public AbstractDs, public IdComponent { public: // Closes this attribute. @@ -74,8 +82,10 @@ class H5_DLLCPP Attribute : public AbstractDs, public IdComponent { virtual ~Attribute(); protected: +#ifndef DOXYGEN_SHOULD_SKIP_THIS // Sets the attribute id. virtual void p_setId(const hid_t new_id); +#endif // DOXYGEN_SHOULD_SKIP_THIS private: hid_t id; // HDF5 attribute id diff --git a/c++/src/H5CommonFG.h b/c++/src/H5CommonFG.h index 1748d1d..2f10e8e 100644 --- a/c++/src/H5CommonFG.h +++ b/c++/src/H5CommonFG.h @@ -14,10 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// CommonFG is a protocol class. Its existence is simply to provide the -// common services that are provided by H5File and Group. The file or -// group in the context of this class is referred to as 'location'. - #ifndef __CommonFG_H #define __CommonFG_H @@ -29,6 +25,12 @@ class Group; class H5File; class ArrayType; class VarLenType; + +/*! \class CommonFG + \brief \i CommonFG is an abstract base class of H5File and H5Group. + + It provides common operations of H5File and H5Group. +*/ class H5_DLLCPP CommonFG { public: // Creates a new group at this location which can be a file diff --git a/c++/src/H5CompType.h b/c++/src/H5CompType.h index 16ae839..3d6a62f 100644 --- a/c++/src/H5CompType.h +++ b/c++/src/H5CompType.h @@ -14,9 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class CompType inherits from DataType and provides accesses to a compound -// datatype. - #ifndef __H5CompType_H #define __H5CompType_H @@ -24,6 +21,10 @@ namespace H5 { #endif +/*! \class CompType + \brief CompType is a derivative of a DataType and operates on HDF5 + compound datatypes. +*/ class H5_DLLCPP CompType : public DataType { public: // Default constructor diff --git a/c++/src/H5CppDoc.h b/c++/src/H5CppDoc.h index baeca64..f3ed040 100644 --- a/c++/src/H5CppDoc.h +++ b/c++/src/H5CppDoc.h @@ -37,17 +37,17 @@ * closely represent the interfaces of the HDF5 APIs, as followed: * * \verbatim - HDF5 C APIs C++ Classes - ----------- ----------- - Attribute Interface (H5A) Attribute - Datasets Interface (H5D) DataSet - Error Interface (H5E) Exception - File Interface (H5F) H5File - Group Interface (H5G) Group - Identifier Interface (H5I) IdComponent - Property List Interface (H5P) PropList and subclasses - Dataspace Interface (H5S) DataSpace - Datatype Interface (H5T) DataType and subclasses + HDF5 C APIs C++ Classes + ----------- ----------- + Attribute Interface (H5A) Attribute + Datasets Interface (H5D) DataSet + Error Interface (H5E) Exception + File Interface (H5F) H5File + Group Interface (H5G) Group + Identifier Interface (H5I) IdComponent + Property List Interface (H5P) PropList and subclasses + Dataspace Interface (H5S) DataSpace + Datatype Interface (H5T) DataType and subclasses \endverbatim * \section install_sec Installation * diff --git a/c++/src/H5DataSet.h b/c++/src/H5DataSet.h index a3a6a76..92c651c 100644 --- a/c++/src/H5DataSet.h +++ b/c++/src/H5DataSet.h @@ -14,8 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class DataSet inherits from AbstractDs and provides accesses to a dataset. - #ifndef __H5DataSet_H #define __H5DataSet_H @@ -23,6 +21,13 @@ namespace H5 { #endif +/*! \class DataSet + \brief Class DataSet operates on HDF5 datasets. + + An datasets has many characteristics similar to an attribute, thus both + Attribute and DataSet are derivatives of AbstractDs. DataSet also + inherits from H5Object because a dataset is an HDF5 object. +*/ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { public: // Close this dataset. @@ -98,6 +103,12 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { // Destructor: properly terminates access to this dataset. virtual ~DataSet(); + protected: +#ifndef DOXYGEN_SHOULD_SKIP_THIS + // Sets the dataset id. + virtual void p_setId(const hid_t new_id); +#endif // DOXYGEN_SHOULD_SKIP_THIS + private: hid_t id; // HDF5 dataset id @@ -110,12 +121,6 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { // Reads variable or fixed len strings from this dataset. void p_read_fixed_len(const hid_t mem_type_id, const hid_t mem_space_id, const hid_t file_space_id, const hid_t xfer_plist_id, H5std_string& strg) const; void p_read_variable_len(const hid_t mem_type_id, const hid_t mem_space_id, const hid_t file_space_id, const hid_t xfer_plist_id, H5std_string& strg) const; - - protected: -#ifndef DOXYGEN_SHOULD_SKIP_THIS - // Sets the dataset id. - virtual void p_setId(const hid_t new_id); -#endif // DOXYGEN_SHOULD_SKIP_THIS }; #ifndef H5_NO_NAMESPACE } diff --git a/c++/src/H5DataSpace.h b/c++/src/H5DataSpace.h index 1ea7188..05ee70c 100644 --- a/c++/src/H5DataSpace.h +++ b/c++/src/H5DataSpace.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class DataSpace operates on HDF5 dataspaces. class H5_DLLCPP DataSpace : public IdComponent { public: // Default DataSpace objects @@ -118,15 +119,14 @@ class H5_DLLCPP DataSpace : public IdComponent { // Destructor: properly terminates access to this dataspace. virtual ~DataSpace(); - private: - hid_t id; // HDF5 dataspace id - protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS // Sets the dataspace id. virtual void p_setId(const hid_t new_id); #endif // DOXYGEN_SHOULD_SKIP_THIS + private: + hid_t id; // HDF5 dataspace id }; #ifndef H5_NO_NAMESPACE } diff --git a/c++/src/H5DataType.cpp b/c++/src/H5DataType.cpp index be05623..00aa5f4 100644 --- a/c++/src/H5DataType.cpp +++ b/c++/src/H5DataType.cpp @@ -95,7 +95,7 @@ DataType::DataType( const H5T_class_t type_class, size_t size ) : H5Object() // Function: DataType overload constructor - dereference ///\brief Given a reference, ref, to an hdf5 group, creates a /// DataType object -///\param h5file - IN: Location referenced object is in +///\param loc - IN: Location referenced object is in ///\param ref - IN: Reference pointer ///\param ref_type - IN: Reference type - default to H5R_OBJECT ///\exception H5::ReferenceException @@ -106,8 +106,6 @@ DataType::DataType( const H5T_class_t type_class, size_t size ) : H5Object() //-------------------------------------------------------------------------- DataType::DataType(const H5Location& loc, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0) { - /* H5Location::dereference(loc, ref, ref_type, plist); - */ id = H5Location::p_dereference(loc.getId(), ref, ref_type, plist, "constructor - by dereference"); } @@ -127,13 +125,6 @@ DataType::DataType(const H5Location& loc, const void* ref, H5R_type_t ref_type, DataType::DataType(const Attribute& attr, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0) { id = H5Location::p_dereference(attr.getId(), ref, ref_type, plist, "constructor - by dereference"); - /* try { - id = p_dereference(attr.getId(), ref, ref_type, plist); - } catch (ReferenceException deref_error) { - throw ReferenceException("DataType constructor - located by an Attribute", - deref_error.getDetailMsg()); - } - */ } //-------------------------------------------------------------------------- @@ -268,38 +259,12 @@ void DataType::p_commit(hid_t loc_id, const char* name) // Function: DataType::commit ///\brief Commits a transient datatype to a file, creating a new /// named datatype -///\param loc - IN: A file -///\param name - IN: Name of the datatype -///\exception H5::DataTypeIException -// Programmer Binh-Minh Ribler - 2000 -//-------------------------------------------------------------------------- -void DataType::commit(H5File& loc, const char* name) -{ - p_commit(loc.getLocId(), name); -} - -//-------------------------------------------------------------------------- -// Function: DataType::commit -///\brief This is an overloaded member function, provided for convenience. -/// It differs from the above function only in the type of the -/// argument \a name. -// Programmer Binh-Minh Ribler - 2000 -//-------------------------------------------------------------------------- -void DataType::commit(H5File& loc, const H5std_string& name) -{ - p_commit(loc.getLocId(), name.c_str()); -} - -//-------------------------------------------------------------------------- -// Function: DataType::commit -///\brief Commits a transient datatype to a file, creating a new -/// named datatype -///\param loc - IN: Either a group, dataset, named datatype, or attribute. +///\param loc - IN: A location (file, dataset, datatype, or group) ///\param name - IN: Name of the datatype ///\exception H5::DataTypeIException // Programmer Binh-Minh Ribler - Jan, 2007 //-------------------------------------------------------------------------- -void DataType::commit(H5Object& loc, const char* name) +void DataType::commit(H5Location& loc, const char* name) { p_commit(loc.getId(), name); } @@ -311,7 +276,7 @@ void DataType::commit(H5Object& loc, const char* name) /// argument \a name. // Programmer Binh-Minh Ribler - 2000 //-------------------------------------------------------------------------- -void DataType::commit(H5Object& loc, const H5std_string& name) +void DataType::commit(H5Location& loc, const H5std_string& name) { p_commit(loc.getId(), name.c_str()); } diff --git a/c++/src/H5DataType.h b/c++/src/H5DataType.h index 104eed4..c5c8a7d 100644 --- a/c++/src/H5DataType.h +++ b/c++/src/H5DataType.h @@ -21,6 +21,13 @@ namespace H5 { #endif +/*! \class DataType + \brief Class DataType provides generic operations on HDF5 datatypes. + + DataType inherits from H5Object because a named datatype is an HDF5 + object and is a base class of ArrayType, AtomType, CompType, EnumType, + and VarLenType. +*/ class H5_DLLCPP DataType : public H5Object { public: // Creates a datatype given its class and size @@ -47,10 +54,8 @@ class H5_DLLCPP DataType : public H5Object { // Commits a transient datatype to a file; this datatype becomes // a named datatype which can be accessed from the location. - void commit( H5File& loc, const char* name); - void commit( H5File& loc, const H5std_string& name); - void commit( H5Object& loc, const char* name); - void commit( H5Object& loc, const H5std_string& name); + void commit(H5Location& loc, const char* name); + void commit(H5Location& loc, const H5std_string& name); // Determines whether this datatype is a named datatype or // a transient datatype. diff --git a/c++/src/H5DcreatProp.h b/c++/src/H5DcreatProp.h index 385bc61..7434b9b 100644 --- a/c++/src/H5DcreatProp.h +++ b/c++/src/H5DcreatProp.h @@ -21,6 +21,10 @@ namespace H5 { #endif +/*! \class DSetCreatPropList + \brief Class DSetCreatPropList represents the dataset creation property + list. +*/ class H5_DLLCPP DSetCreatPropList : public PropList { public: // Default dataset creation property list. diff --git a/c++/src/H5DxferProp.h b/c++/src/H5DxferProp.h index b136ba4..3c2a616 100644 --- a/c++/src/H5DxferProp.h +++ b/c++/src/H5DxferProp.h @@ -21,6 +21,10 @@ namespace H5 { #endif +/*! \class DSetMemXferPropList + \brief Class DSetMemXferPropList represents the dataset memory and + transfer property list. +*/ class H5_DLLCPP DSetMemXferPropList : public PropList { public: static const DSetMemXferPropList DEFAULT; diff --git a/c++/src/H5EnumType.h b/c++/src/H5EnumType.h index 71e36c3..fe36e8b 100644 --- a/c++/src/H5EnumType.h +++ b/c++/src/H5EnumType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class EnumType operates on HDF5 enum datatypes. class H5_DLLCPP EnumType : public DataType { public: diff --git a/c++/src/H5Exception.h b/c++/src/H5Exception.h index 8b12abc..30fe537 100644 --- a/c++/src/H5Exception.h +++ b/c++/src/H5Exception.h @@ -28,6 +28,11 @@ namespace H5 { #endif #endif +/*! \class Exception + \brief Exception provides wrappers of HDF5 error handling functions. + + Many classes are derived from Exception for specific HDF5 C interfaces. +*/ class H5_DLLCPP Exception { public: // Creates an exception with a function name where the failure occurs @@ -78,13 +83,13 @@ class H5_DLLCPP Exception { // virtual Destructor virtual ~Exception(); - private: - H5std_string detail_message; - H5std_string func_name; - protected: // Default value for detail_message static const char DEFAULT_MSG[]; + + private: + H5std_string detail_message; + H5std_string func_name; }; class H5_DLLCPP FileIException : public Exception { diff --git a/c++/src/H5FaccProp.h b/c++/src/H5FaccProp.h index 040b3e9..5b56f6e 100644 --- a/c++/src/H5FaccProp.h +++ b/c++/src/H5FaccProp.h @@ -21,7 +21,7 @@ namespace H5 { #endif -// class for file access properties +//! Class FileAccPropList represents the HDF5 file access property list. class H5_DLLCPP FileAccPropList : public PropList { public: static const FileAccPropList DEFAULT; diff --git a/c++/src/H5FcreatProp.h b/c++/src/H5FcreatProp.h index b11be62..4fe51a9 100644 --- a/c++/src/H5FcreatProp.h +++ b/c++/src/H5FcreatProp.h @@ -21,7 +21,7 @@ namespace H5 { #endif -// class for file access properties +//! Class FileCreatPropList represents the HDF5 file create property list. class H5_DLLCPP FileCreatPropList : public PropList { public: // Default file creation property list. diff --git a/c++/src/H5File.cpp b/c++/src/H5File.cpp index 77dd7be..615c1cb 100644 --- a/c++/src/H5File.cpp +++ b/c++/src/H5File.cpp @@ -163,7 +163,7 @@ H5File::H5File(const H5File& original) : H5Location(original) } //-------------------------------------------------------------------------- -// Function: H5File::isHdf5 +// Function: H5File::isHdf5 (static) ///\brief Determines whether a file in HDF5 format. (Static) ///\param name - IN: Name of the file ///\return true if the file is in HDF5 format, and false, otherwise @@ -186,7 +186,7 @@ bool H5File::isHdf5(const char* name) } //-------------------------------------------------------------------------- -// Function: H5File::isHdf5 +// Function: H5File::isHdf5 (static) ///\brief This is an overloaded member function, provided for convenience. /// It takes an \c H5std_string for \a name. (Static) ///\param name - IN: Name of the file - \c H5std_string @@ -274,19 +274,6 @@ void H5File::reOpen() } //-------------------------------------------------------------------------- -// Function: H5File::reopen -// Purpose: Reopens this file. -// Exception H5::FileIException -// Description -// This function is replaced by the above function reOpen. -// Programmer Binh-Minh Ribler - 2000 -//-------------------------------------------------------------------------- -void H5File::reopen() -{ - H5File::reOpen(); -} - -//-------------------------------------------------------------------------- // Function: H5File::getCreatePlist ///\brief Returns the creation property list of this file ///\return FileCreatPropList object @@ -537,6 +524,19 @@ hid_t H5File::getId() const #ifndef DOXYGEN_SHOULD_SKIP_THIS //-------------------------------------------------------------------------- +// Function: H5File::reopen +// Purpose: Reopens this file. +// Exception H5::FileIException +// Description +// This function is replaced by the above function reOpen. +// Programmer Binh-Minh Ribler - 2000 +//-------------------------------------------------------------------------- +void H5File::reopen() +{ + H5File::reOpen(); +} + +//-------------------------------------------------------------------------- // Function: H5File::p_setId (protected) ///\brief Sets the identifier of this object to a new value. /// diff --git a/c++/src/H5File.h b/c++/src/H5File.h index 830dda0..5fdbcdc 100644 --- a/c++/src/H5File.h +++ b/c++/src/H5File.h @@ -21,6 +21,11 @@ namespace H5 { #endif +/*! \class H5File + \brief Class H5File represents an HDF5 file. + + It inherits from H5Location and CommonFG. +*/ class H5_DLLCPP H5File : public H5Location, public CommonFG { public: // Creates or opens an HDF5 file. @@ -94,6 +99,12 @@ class H5_DLLCPP H5File : public H5Location, public CommonFG { // H5File destructor. virtual ~H5File(); + protected: +#ifndef DOXYGEN_SHOULD_SKIP_THIS + // Sets the HDF5 file id. + virtual void p_setId(const hid_t new_id); +#endif // DOXYGEN_SHOULD_SKIP_THIS + private: hid_t id; // HDF5 file id @@ -101,13 +112,6 @@ class H5_DLLCPP H5File : public H5Location, public CommonFG { // constructors taking a string or a char* void p_get_file( const char* name, unsigned int flags, const FileCreatPropList& create_plist, const FileAccPropList& access_plist ); - protected: -#ifndef DOXYGEN_SHOULD_SKIP_THIS - // Sets the HDF5 file id. - virtual void p_setId(const hid_t new_id); - -#endif // DOXYGEN_SHOULD_SKIP_THIS - }; #ifndef H5_NO_NAMESPACE } diff --git a/c++/src/H5FloatType.h b/c++/src/H5FloatType.h index 06148d6..06a5450 100644 --- a/c++/src/H5FloatType.h +++ b/c++/src/H5FloatType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class FloatType operates on HDF5 floating point datatype. class H5_DLLCPP FloatType : public AtomType { public: // Creates a floating-point type using a predefined type diff --git a/c++/src/H5Group.cpp b/c++/src/H5Group.cpp index 6299ea3..5d5b124 100644 --- a/c++/src/H5Group.cpp +++ b/c++/src/H5Group.cpp @@ -90,7 +90,7 @@ Group::Group(const hid_t existing_id) : H5Object() //-------------------------------------------------------------------------- // Function: Group overload constructor - dereference ///\brief Given a reference, ref, to an hdf5 group, creates a Group object -///\param obj - IN: Specifying location referenced object is in +///\param loc - IN: Specifying location referenced object is in ///\param ref - IN: Reference pointer ///\param ref_type - IN: Reference type - default to H5R_OBJECT ///\exception H5::ReferenceException @@ -101,8 +101,6 @@ Group::Group(const hid_t existing_id) : H5Object() //-------------------------------------------------------------------------- Group::Group(const H5Location& loc, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0) { - /* H5Location::dereference(loc, ref, ref_type, plist); - */ id = H5Location::p_dereference(loc.getId(), ref, ref_type, plist, "constructor - by dereference"); } @@ -118,14 +116,6 @@ Group::Group(const H5Location& loc, const void* ref, H5R_type_t ref_type, const Group::Group(const Attribute& attr, const void* ref, H5R_type_t ref_type, const PropList& plist) : H5Object(), id(0) { id = H5Location::p_dereference(attr.getId(), ref, ref_type, plist, "constructor - by dereference"); -/* - try { - id = p_dereference(attr.getId(), ref, ref_type, plist); - } catch (ReferenceException deref_error) { - throw ReferenceException("Group constructor - located by an Attribute", - deref_error.getDetailMsg()); - } -*/ } //-------------------------------------------------------------------------- diff --git a/c++/src/H5Group.h b/c++/src/H5Group.h index a5e324c..78f5f17 100644 --- a/c++/src/H5Group.h +++ b/c++/src/H5Group.h @@ -21,6 +21,11 @@ namespace H5 { #endif +/*! \class Group + \brief Class Group represents an HDF5 group. + + It inherits many operations from H5Location and CommonFG. +*/ class H5_DLLCPP Group : public H5Object, public CommonFG { public: // Close this group. @@ -56,14 +61,14 @@ class H5_DLLCPP Group : public H5Object, public CommonFG { // Creates a copy of an existing group using its id. Group( const hid_t group_id ); - private: - hid_t id; // HDF5 group id - protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS // Sets the group id. virtual void p_setId(const hid_t new_id); #endif // DOXYGEN_SHOULD_SKIP_THIS + + private: + hid_t id; // HDF5 group id }; #ifndef H5_NO_NAMESPACE } diff --git a/c++/src/H5IdComponent.h b/c++/src/H5IdComponent.h index 5a61947..ca9352d 100644 --- a/c++/src/H5IdComponent.h +++ b/c++/src/H5IdComponent.h @@ -17,13 +17,18 @@ #ifndef __IdComponent_H #define __IdComponent_H -// IdComponent represents an HDF5 object that has an identifier. - #ifndef H5_NO_NAMESPACE namespace H5 { #endif class DataSpace; +/*! \class IdComponent + \brief Class IdComponent provides wrappers of the C functions that + operate on an HDF5 identifier. + + In most cases, the C library handles these operations and an application + rarely needs them. +*/ class H5_DLLCPP IdComponent { public: // Increment reference counter. @@ -76,11 +81,10 @@ class H5_DLLCPP IdComponent { virtual ~IdComponent(); protected: -#ifndef DOXYGEN_SHOULD_SKIP_THIS - // Default constructor. IdComponent(); +#ifndef DOXYGEN_SHOULD_SKIP_THIS // Gets the name of the file, in which an HDF5 object belongs. H5std_string p_get_file_name() const; diff --git a/c++/src/H5IntType.h b/c++/src/H5IntType.h index 02efb64..95fa642 100644 --- a/c++/src/H5IntType.h +++ b/c++/src/H5IntType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class IntType operates on HDF5 integer datatype. class H5_DLLCPP IntType : public AtomType { public: // Creates a integer type using a predefined type diff --git a/c++/src/H5Library.h b/c++/src/H5Library.h index c92a943..e5365f9 100644 --- a/c++/src/H5Library.h +++ b/c++/src/H5Library.h @@ -29,6 +29,12 @@ namespace H5 { // calling H5close #endif // DOXYGEN_SHOULD_SKIP_THIS +/*! \class H5Library + \brief Class H5Library operates the HDF5 library globably. + + It is not neccessary to construct an instance of H5Library to use the + methods. +*/ class H5_DLLCPP H5Library { public: #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/c++/src/H5Location.cpp b/c++/src/H5Location.cpp index 22db85c..b413a17 100644 --- a/c++/src/H5Location.cpp +++ b/c++/src/H5Location.cpp @@ -565,9 +565,9 @@ void H5Location::p_reference(void* ref, const char* name, hid_t space_id, H5R_ty ///\param ref_type - IN: Type of reference to query, valid values are: /// \li \c H5R_OBJECT - Reference is an object reference. /// \li \c H5R_DATASET_REGION - Reference is a dataset region -/// reference. - this is the default +/// reference. (default) ///\exception H5::ReferenceException -///\notes This method is more suitable for a dataset region reference. +///\note This method is more suitable for a dataset region reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const char* name, const DataSpace& dataspace, H5R_type_t ref_type) const @@ -591,9 +591,9 @@ void H5Location::reference(void* ref, const char* name, const DataSpace& dataspa ///\param ref_type - IN: Type of reference to query, valid values are: /// \li \c H5R_OBJECT - Reference is an object reference. /// \li \c H5R_DATASET_REGION - Reference is a dataset region -/// reference. - this is the default +/// reference. (default) ///\exception H5::ReferenceException -///\notes This method is more suitable for a dataset region reference. +///\note This method is more suitable for a dataset region reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const H5std_string& name, const DataSpace& dataspace, H5R_type_t ref_type) const @@ -614,10 +614,10 @@ void H5Location::reference(void* ref, const H5std_string& name, const DataSpace& ///\param ref - IN: Reference pointer ///\param name - IN: Name of the object to be referenced ///\param ref_type - IN: Type of reference to query, valid values are: -/// \li \c H5R_OBJECT - Reference is an object reference. +/// \li \c H5R_OBJECT - Reference is an object reference (default) /// \li \c H5R_DATASET_REGION - Reference is a dataset region ///\exception H5::ReferenceException -///\notes This method is more suitable for an object reference. +///\note This method is more suitable for an object reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const char* name, H5R_type_t ref_type) const @@ -638,9 +638,9 @@ void H5Location::reference(void* ref, const char* name, H5R_type_t ref_type) con ///\param ref - IN: Reference pointer ///\param name - IN: Name of the object to be referenced - \c H5std_string ///\param ref_type - IN: Type of reference to query, valid values are: -/// \li \c H5R_OBJECT - Reference is an object reference. +/// \li \c H5R_OBJECT - Reference is an object reference (default) /// \li \c H5R_DATASET_REGION - Reference is a dataset region -///\notes This method is more suitable for an object reference. +///\note This method is more suitable for an object reference. // Programmer Binh-Minh Ribler - May, 2004 //-------------------------------------------------------------------------- void H5Location::reference(void* ref, const H5std_string& name, H5R_type_t ref_type) const @@ -684,7 +684,7 @@ hid_t H5Location::p_dereference(hid_t loc_id, const void* ref, H5R_type_t ref_ty //-------------------------------------------------------------------------- // Function: H5Location::dereference ///\brief Dereferences a reference into an HDF5 object, given an HDF5 object. -///\param obj - IN: Object specifying the location of the referenced object +///\param loc - IN: Location of the referenced object ///\param ref - IN: Reference pointer ///\param ref_type - IN: Reference type ///\exception H5::ReferenceException diff --git a/c++/src/H5Location.h b/c++/src/H5Location.h index 4ea13cd..bbe86fc 100644 --- a/c++/src/H5Location.h +++ b/c++/src/H5Location.h @@ -19,10 +19,6 @@ #include "H5Classes.h" // constains forward class declarations -// H5Location is an abstract class. It provides a collection of wrappers -// of C functions which take location IDs. Most of these were in H5Object -// but are now moved here for H5File's access. - #ifndef H5_NO_NAMESPACE namespace H5 { #endif @@ -34,15 +30,23 @@ typedef void (*attr_operator_t)( H5Location& loc/*in*/, const H5std_string attr_name/*in*/, void *operator_data/*in,out*/); -class UserData4Aiterate { // user data for attribute iteration +//! User data for attribute iteration +class UserData4Aiterate { public: attr_operator_t op; void* opData; H5Location* location; }; -// An H5Location can be a file, group, dataset, or committed datatype. +/*! \class H5Location + \brief H5Location is an abstract base class, added in version 1.8.12. + It provides a collection of wrappers for the C functions that take a + location identifier to specify the HDF5 object. The location identifier + can be either file, group, dataset, or named datatype. +*/ +// Most of these methods were in H5Object but are now moved here because +// a location can be a file, group, dataset, or named datatype. -BMR, 2013-10-1 class H5_DLLCPP H5Location : public IdComponent { public: // Creates an attribute for the specified object at this location @@ -112,7 +116,7 @@ class H5_DLLCPP H5Location : public IdComponent { void reference(void* ref, const char* name, H5R_type_t ref_type = H5R_OBJECT) const; void reference(void* ref, const H5std_string& name, - H5R_type_t ref_type = H5R_DATASET_REGION) const; + H5R_type_t ref_type = H5R_OBJECT) const; void reference(void* ref, const char* name, const DataSpace& dataspace, H5R_type_t ref_type = H5R_DATASET_REGION) const; void reference(void* ref, const H5std_string& name, const DataSpace& dataspace, @@ -130,8 +134,7 @@ class H5_DLLCPP H5Location : public IdComponent { virtual hid_t getId() const = 0; protected: -#ifndef DOXYGEN_SHOULD_SKIP_THIS - // Default constructor, + // Default constructor H5Location(); // Creates a copy of an existing object giving the location id. @@ -140,6 +143,7 @@ class H5_DLLCPP H5Location : public IdComponent { // Copy constructor. H5Location(const H5Location& original); +#ifndef DOXYGEN_SHOULD_SKIP_THIS // Creates a reference to an HDF5 object or a dataset region. void p_reference(void* ref, const char* name, hid_t space_id, H5R_type_t ref_type) const; @@ -154,11 +158,11 @@ class H5_DLLCPP H5Location : public IdComponent { // Retrieves the type of object that an object reference points to. H5O_type_t p_get_ref_obj_type(void *ref, H5R_type_t ref_type) const; +#endif // DOXYGEN_SHOULD_SKIP_THIS + // Noop destructor. virtual ~H5Location(); -#endif // DOXYGEN_SHOULD_SKIP_THIS - }; /* end class H5Location */ #ifndef H5_NO_NAMESPACE diff --git a/c++/src/H5Object.h b/c++/src/H5Object.h index 3f9c343..5c2ef98 100644 --- a/c++/src/H5Object.h +++ b/c++/src/H5Object.h @@ -38,6 +38,12 @@ namespace H5 { #endif +/*! \class H5Object + \brief Class H5Object is a bridge between H5Location and DataSet, DataType, + and Group. + + All the wrappers in H5Object were moved to H5Location. +*/ class H5_DLLCPP H5Object : public H5Location { public: #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/c++/src/H5PredType.cpp b/c++/src/H5PredType.cpp index 27cfd3a..6dbee98 100644 --- a/c++/src/H5PredType.cpp +++ b/c++/src/H5PredType.cpp @@ -272,22 +272,12 @@ PredType& PredType::operator=( const PredType& rhs ) #ifndef DOXYGEN_SHOULD_SKIP_THIS // These dummy functions do not inherit from DataType - they'll // throw an DataTypeIException if invoked. -void PredType::commit( H5File& loc, const char* name ) +void PredType::commit(H5Location& loc, const char* name ) { throw DataTypeIException("PredType::commit", "Error: Attempted to commit a predefined datatype. Invalid operation!" ); } -void PredType::commit( H5File& loc, const H5std_string& name ) -{ - commit( loc, name.c_str()); -} - -void PredType::commit( H5Object& loc, const char* name ) -{ - throw DataTypeIException("PredType::commit", "Error: Attempted to commit a predefined datatype. Invalid operation!" ); -} - -void PredType::commit( H5Object& loc, const H5std_string& name ) +void PredType::commit(H5Location& loc, const H5std_string& name ) { commit( loc, name.c_str()); } diff --git a/c++/src/H5PredType.h b/c++/src/H5PredType.h index 65e1c07..a8ec0b8 100644 --- a/c++/src/H5PredType.h +++ b/c++/src/H5PredType.h @@ -14,11 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// PredType holds the definition of all the HDF5 predefined datatypes. -// These types can only be made copy of, not created by H5Tcreate or -// closed by H5Tclose. They are treated as constants. -///////////////////////////////////////////////////////////////////// - #ifndef __H5PredType_H #define __H5PredType_H @@ -36,6 +31,13 @@ namespace H5 { #define H5CPP_EXITED -3 // -3 is less likely to be used elsewhere #endif // DOXYGEN_SHOULD_SKIP_THIS +/*! \class PredType + \brief Class PredType holds the definition of all the HDF5 predefined + datatypes. + + These types can only be made copy of, not created by H5Tcreate or + closed by H5Tclose. They are treated as constants. +*/ class H5_DLLCPP PredType : public AtomType { public: ///\brief Returns this class name. @@ -228,21 +230,18 @@ class H5_DLLCPP PredType : public AtomType { static const PredType NATIVE_UINT_FAST64; #endif /* H5_SIZEOF_UINT_FAST64_T */ -#ifndef DOXYGEN_SHOULD_SKIP_THIS - // These dummy functions do not inherit from DataType - they'll - // throw a DataTypeIException if invoked. - void commit( H5File& loc, const H5std_string& name ); - void commit( H5File& loc, const char* name ); - void commit( H5Object& loc, const H5std_string& name ); - void commit( H5Object& loc, const char* name ); - bool committed(); -#endif // DOXYGEN_SHOULD_SKIP_THIS - - private: - // Added this to work around the atexit/global destructor problem. - // It'll help to terminate the library after other PredType instances - // are closed. -BMR, Mar 30, 2012 - static const PredType AtExit; + /*! \brief This dummy function do not inherit from DataType - it will + throw a DataTypeIException if invoked. + */ + void commit(H5Location& loc, const H5std_string& name ); + /*! \brief This dummy function do not inherit from DataType - it will + throw a DataTypeIException if invoked. + */ + void commit(H5Location& loc, const char* name ); + /*! \brief This dummy function do not inherit from DataType - it will + throw a DataTypeIException if invoked. + */ + bool committed(); protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS @@ -254,6 +253,12 @@ class H5_DLLCPP PredType : public AtomType { #endif // DOXYGEN_SHOULD_SKIP_THIS + private: + // Added this to work around the atexit/global destructor problem. + // It'll help to terminate the library after other PredType instances + // are closed. -BMR, Mar 30, 2012 + static const PredType AtExit; + }; #ifndef H5_NO_NAMESPACE } diff --git a/c++/src/H5PropList.h b/c++/src/H5PropList.h index b2c50d4..f26201d 100644 --- a/c++/src/H5PropList.h +++ b/c++/src/H5PropList.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class PropList provides operations for generic property lists. class H5_DLLCPP PropList : public IdComponent { public: // Default property list diff --git a/c++/src/H5StrType.h b/c++/src/H5StrType.h index 251b0b8..8b3a773 100644 --- a/c++/src/H5StrType.h +++ b/c++/src/H5StrType.h @@ -21,6 +21,7 @@ namespace H5 { #endif +//! Class StrType operates on HDF5 string datatypes. class H5_DLLCPP StrType : public AtomType { public: // Creates a string type using a predefined type diff --git a/c++/src/H5VarLenType.h b/c++/src/H5VarLenType.h index caa347a..40c597f 100644 --- a/c++/src/H5VarLenType.h +++ b/c++/src/H5VarLenType.h @@ -14,9 +14,6 @@ * access to either file, you may request a copy from help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -// Class VarLenType inherits from DataType and provides wrappers for -// the HDF5 C's Variable-length Datatypes. - #ifndef __H5VarLenType_H #define __H5VarLenType_H @@ -24,6 +21,7 @@ namespace H5 { #endif +//! VarLenType operates on the HDF5 C's Variable-length Datatypes. class H5_DLLCPP VarLenType : public DataType { public: // Constructor that creates a variable-length datatype based diff --git a/c++/test/tfile.cpp b/c++/test/tfile.cpp index 65b8e57..965065a 100644 --- a/c++/test/tfile.cpp +++ b/c++/test/tfile.cpp @@ -108,16 +108,10 @@ static void test_file_create() // Create file FILE1 file1 = new H5File (FILE1, H5F_ACC_EXCL); - // try to create the same file with H5F_ACC_TRUNC. This should fail - // because file1 is the same file and is currently open. - -/* These three are failing with new/PGI compiler, HDFFV-8067 - The line "H5File file2 (FILE1, H5F_ACC_TRUNC); // should throw E" - Results in this message: - "terminate called without an active exception - Command terminated by signal 6" - Commenting it out until it's fixed LK 20120626. -*/ + // Try to create the same file with H5F_ACC_TRUNC. This should fail + // because file1 is the same file and is currently open. Skip it on + // OpenVMS because it creates another version of the file. +#ifndef H5_HAVE_FILE_VERSIONS try { H5File file2 (FILE1, H5F_ACC_TRUNC); // should throw E @@ -126,6 +120,7 @@ static void test_file_create() } catch( FileIException E ) // catch truncating existing file {} // do nothing, FAIL expected +#endif // H5_HAVE_FILE_VERSIONS // Close file1 delete file1; @@ -141,11 +136,14 @@ static void test_file_create() } catch( FileIException E ) // catching creating existing file {} // do nothing, FAIL expected + // Test create with H5F_ACC_TRUNC. This will truncate the existing file. file1 = new H5File (FILE1, H5F_ACC_TRUNC); - // Try to truncate first file again. This should fail because file1 - // is the same file and is currently open. + // Try to create first file again. This should fail because file1 + // is the same file and is currently open. Skip it on OpenVMS because + // it creates another version of the file. +#ifndef H5_HAVE_FILE_VERSIONS try { H5File file2 (FILE1, H5F_ACC_TRUNC); // should throw E @@ -156,7 +154,7 @@ static void test_file_create() {} // do nothing, FAIL expected // Try with H5F_ACC_EXCL. This should fail too because the file already - // exists. + // exists. Skip it on OpenVMS because it creates another version of the file. try { H5File file3 (FILE1, H5F_ACC_EXCL); // should throw E @@ -165,6 +163,7 @@ static void test_file_create() } catch( FileIException E ) // catching H5F_ACC_EXCL on existing file {} // do nothing, FAIL expected +#endif /*H5_HAVE_FILE_VERSIONS*/ // Get the file-creation template FileCreatPropList tmpl1 = file1->getCreatePlist(); @@ -387,7 +386,7 @@ static void test_file_size() // Check if it's reasonable. It's 0 now. if (free_space < 0 || free_space > 4*KB) - issue_fail_msg("test_file_size()", __LINE__, __FILE__, "getFreeSpace returned unreasonable value"); + issue_fail_msg("test_file_size()", __LINE__, __FILE__, "getFreeSpace returned unreasonable value"); PASSED(); } // end of try block @@ -433,54 +432,54 @@ typedef struct s1_t { static void test_file_name() { - // Output message about test being performed + // Output message about test being performed. SUBTEST("File Name"); H5std_string file_name; try { - // Create a file using default properties + // Create a file using default properties. H5File file4(FILE4, H5F_ACC_TRUNC); - // Get file name from the file instance + // Get file name from the file instance. file_name = file4.getFileName(); verify_val(file_name, FILE4, "H5File::getFileName", __LINE__, __FILE__); - // Create a group in the root group + // Create a group in the root group. Group group(file4.createGroup(GROUPNAME, 0)); - // Get and verify file name via a group + // Get and verify file name via a group. file_name = group.getFileName(); verify_val(file_name, FILE4, "Group::getFileName", __LINE__, __FILE__); - // Create the data space + // Create the data space. hsize_t dims[RANK] = {NX, NY}; DataSpace space(RANK, dims); - // Create a new dataset + // Create a new dataset. DataSet dataset(file4.createDataSet (DSETNAME, PredType::NATIVE_INT, space)); - // Get and verify file name via a dataset + // Get and verify file name via a dataset. file_name = dataset.getFileName(); verify_val(file_name, FILE4, "DataSet::getFileName", __LINE__, __FILE__); - // Create an attribute for the dataset + // Create an attribute for the dataset. Attribute attr(dataset.createAttribute(DATTRNAME, PredType::NATIVE_INT, space)); - // Get and verify file name + // Get and verify file name via an attribute. file_name = attr.getFileName(); verify_val(file_name, FILE4, "Attribute::getFileName", __LINE__, __FILE__); - // Create a compound datatype + // Create a compound datatype. CompType comp_type (sizeof(s1_t)); - // Insert fields + // Insert fields. comp_type.insertMember("a", HOFFSET(s1_t, a), PredType::NATIVE_INT); comp_type.insertMember("b", HOFFSET(s1_t, b), PredType::NATIVE_FLOAT); - // Save it on file + // Save it on file. comp_type.commit(file4, DTYPENAME); - // Get and verify file name + // Get and verify file name via a committed datatype. comp_type.getFileName(); verify_val(file_name, FILE4, "CompType::getFileName", __LINE__, __FILE__); PASSED(); -- cgit v0.12