Adding a C++ wrapper

Description:
    - Added a wrapper for H5Ovisit2 to class H5Object
        // Recursively visit elements reachable from this object.
        void visit(H5_index_t idx_type, H5_iter_order_t order, visit_operator_t user_op, void *op_data, unsigned int fields);
    - Fixed various typos in documentation
    - Removed a pair of [] in a delete statement for a non-array pointer.
Platforms tested:
    Linux/64 (jelly)
    Linux/64 (platypus)
    Darwin (osx1011test)

5 files changed, 99 insertions, 23 deletions

diff --git a/c++/src/H5CppDoc.h b/c++/src/H5CppDoc.h
index c1711bc..5e80408 100644
--- a/c++/src/H5CppDoc.h
+++ b/c++/src/H5CppDoc.h
@@ -54,6 +54,7 @@
  * \section install_sec Installation
  *
  * The HDF5 C++ API is included with the HDF5 source code.
+ * 
  * Please refer to the release_docs/INSTALL file under the top directory 
  * of the HDF5 source code for information about installing, building, 
  * and testing the C++ API.
diff --git a/c++/src/H5LaccProp.h b/c++/src/H5LaccProp.h
index 70890b3..ec5e54f 100644
--- a/c++/src/H5LaccProp.h
+++ b/c++/src/H5LaccProp.h
@@ -12,9 +12,6 @@
  * help@hdfgroup.org.                                                        *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-// Class LinkAccPropList represents the HDF5 file access property list and
-// inherits from DataType.
-
 #ifndef __H5LinkAccPropList_H
 #define __H5LinkAccPropList_H
 
@@ -22,15 +19,15 @@ namespace H5 {
 
 /*! \class LinkAccPropList
     \brief Class LinkAccPropList inherits from PropList and provides
-    wrappers for the HDF5 file access property list.
+    wrappers for the HDF5 link access property list.
 */
 // Inheritance: PropList -> IdComponent
 class H5_DLLCPP LinkAccPropList : public PropList {
    public:
-        ///\brief Default file access property list.
+        ///\brief Default link access property list.
         static const LinkAccPropList& DEFAULT;
 
-        // Creates a file access property list.
+        // Creates a link access property list.
         LinkAccPropList();
 
         ///\brief Returns this class name.
@@ -39,7 +36,7 @@ class H5_DLLCPP LinkAccPropList : public PropList {
         // Copy constructor: same as the original LinkAccPropList.
         LinkAccPropList(const LinkAccPropList& original);
 
-        // Creates a copy of an existing file access property list
+        // Creates a copy of an existing link access property list
         // using the property list id.
         LinkAccPropList (const hid_t plist_id);
 
diff --git a/c++/src/H5LcreatProp.h b/c++/src/H5LcreatProp.h
index 12cb479..f6e10bf 100644
--- a/c++/src/H5LcreatProp.h
+++ b/c++/src/H5LcreatProp.h
@@ -12,9 +12,6 @@
  * help@hdfgroup.org.                                                        *
  * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 
-// Class LinkCreatPropList represents the HDF5 file access property list and
-// inherits from DataType.
-
 #ifndef __H5LinkCreatPropList_H
 #define __H5LinkCreatPropList_H
 
@@ -22,15 +19,15 @@ namespace H5 {
 
 /*! \class LinkCreatPropList
     \brief Class LinkCreatPropList inherits from PropList and provides
-    wrappers for the HDF5 file access property list.
+    wrappers for the HDF5 link creation property list.
 */
 // Inheritance: PropList -> IdComponent
 class H5_DLLCPP LinkCreatPropList : public PropList {
    public:
-        ///\brief Default file access property list.
+        ///\brief Default link creation property list.
         static const LinkCreatPropList& DEFAULT;
 
-        // Creates a file access property list.
+        // Creates a link creation property list.
         LinkCreatPropList();
 
         ///\brief Returns this class name.
@@ -39,7 +36,7 @@ class H5_DLLCPP LinkCreatPropList : public PropList {
         // Copy constructor: same as the original LinkCreatPropList.
         LinkCreatPropList(const LinkCreatPropList& original);
 
-        // Creates a copy of an existing file access property list
+        // Creates a copy of an existing link creation property list
         // using the property list id.
         LinkCreatPropList (const hid_t plist_id);
 
diff --git a/c++/src/H5Object.cpp b/c++/src/H5Object.cpp
index 1c22efe..8d3334b 100644
--- a/c++/src/H5Object.cpp
+++ b/c++/src/H5Object.cpp
@@ -40,9 +40,8 @@
 namespace H5 {
 
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
-// userAttrOpWrpr simply interfaces between the user's function and the
-// C library function H5Aiterate2; used to resolve the different prototype
-// problem.  May be moved to Iterator later.
+// userAttrOpWrpr interfaces between the user's function and the
+// C library function H5Aiterate2
 extern "C" herr_t userAttrOpWrpr(hid_t loc_id, const char *attr_name,
     const H5A_info_t *ainfo, void *op_data)
 {
@@ -52,6 +51,17 @@ extern "C" herr_t userAttrOpWrpr(hid_t loc_id, const char *attr_name,
     return 0;
 }
 
+// userVisitOpWrpr interfaces between the user's function and the
+// C library function H5Ovisit2
+extern "C" herr_t userVisitOpWrpr(hid_t obj_id, const char *attr_name,
+    const H5O_info_t *obj_info, void *op_data)
+{
+    H5std_string s_attr_name = H5std_string(attr_name);
+    UserData4Visit* myData = reinterpret_cast<UserData4Visit *> (op_data);
+    int status = myData->op(*myData->obj, s_attr_name, obj_info, myData->opData);
+    return status;
+}
+
 //--------------------------------------------------------------------------
 // Function:    H5Object default constructor (protected)
 // Programmer   Binh-Minh Ribler - 2000
@@ -197,8 +207,6 @@ Attribute H5Object::openAttribute(const unsigned int idx) const
 ///\par Description
 ///             The signature of user_op is
 ///             void (*)(H5::H5Location&, H5std_string, void*).
-///             For information, please refer to the H5Aiterate2 API in
-///             the HDF5 C Reference Manual.
 // Programmer   Binh-Minh Ribler - 2000
 //--------------------------------------------------------------------------
 int H5Object::iterateAttrs(attr_operator_t user_op, unsigned *_idx, void *op_data)
@@ -228,6 +236,61 @@ int H5Object::iterateAttrs(attr_operator_t user_op, unsigned *_idx, void *op_dat
 }
 
 //--------------------------------------------------------------------------
+// Function:    H5Object::visit
+///\brief       Recursively visits all HDF5 objects accessible from this object.
+///\param       idx_type - IN: Type of index; valid values include:
+///             \li \c H5_INDEX_NAME
+///             \li \c H5_INDEX_CRT_ORDER
+///\param       order - IN: Order in which index is traversed; valid values include:
+///             \li \c H5_ITER_DEC
+///             \li \c H5_ITER_INC
+///             \li \c H5_ITER_NATIVE
+///\param       user_op  - IN: Callback function passing data regarding the
+///                            object to the calling application
+///\param       *op_data - IN: User-defined pointer to data required by the
+///                            application for its processing of the object
+///\param       fields   - IN: Flags specifying the fields to be retrieved
+///                            to the callback op via the H5O_info_t argument.
+///             \li \c H5O_INFO_BASIC      fileno, addr, type, and rc fields
+///             \li \c H5O_INFO_TIME       atime, mtime, ctime, and btime fields
+///             \li \c H5O_INFO_NUM_ATTRS  num_attrs field
+///             \li \c H5O_INFO_HDR        hdr field
+///             \li \c H5O_INFO_META_SIZE  meta_size field
+///             \li \c H5O_INFO_ALL        H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE
+///\return
+///             \li On success:
+///                 \li the return value of the first operator that returns a positive value
+///                 \li zero if all members were processed with no operator returning non-zero
+///             \li On failure:
+///                 \li an exception Exception will be thrown if something went
+///                     wrong within the library or the operator failed
+///\exception   H5::Exception
+///\par Description
+///             For information, please refer to the H5Ovisit2 API in the HDF5
+///             C Reference Manual.
+// Programmer   Binh-Minh Ribler - Feb, 2019
+//--------------------------------------------------------------------------
+void H5Object::visit(H5_index_t idx_type, H5_iter_order_t order, visit_operator_t user_op, void *op_data, unsigned int fields)
+{
+    // Store the user's function and data
+    UserData4Visit* userData = new UserData4Visit;
+    userData->opData = op_data;
+    userData->op = user_op;
+    userData->obj = this;
+
+    // Call the C API passing in op wrapper and info
+    herr_t ret_value = H5Ovisit2(getId(), idx_type, order, userVisitOpWrpr, static_cast<void *>(userData), fields);
+
+    // Release memory
+    delete userData;
+
+    // Throw exception if H5Ovisit2 failed, which could be a failure in
+    // the library or in the call back operator
+    if (ret_value < 0)
+        throw Exception(inMemFunc("visit"), "H5Ovisit2 failed");
+}
+
+//--------------------------------------------------------------------------
 // Function:    H5Object::objVersion
 ///\brief       Returns the header version of this HDF5 object.
 ///\return      Object version, which can have the following values:
diff --git a/c++/src/H5Object.h b/c++/src/H5Object.h
index 10b3865..4a4e909 100644
--- a/c++/src/H5Object.h
+++ b/c++/src/H5Object.h
@@ -40,16 +40,30 @@ namespace H5 {
 // Inheritance: H5Location -> IdComponent
 
 // Define the operator function pointer for H5Aiterate().
-typedef void (*attr_operator_t)(H5Object& loc/*in*/,
-                                 const H5std_string attr_name/*in*/,
-                                 void *operator_data/*in,out*/);
+typedef void (*attr_operator_t)(H5Object& loc,
+                                 const H5std_string attr_name,
+                                 void *operator_data);
+
+// Define the operator function pointer for H5Ovisit2().
+typedef int (*visit_operator_t)(H5Object& obj,
+                                 const H5std_string attr_name,
+                                 const H5O_info_t *oinfo,
+                                 void *operator_data);
 
 // User data for attribute iteration
 class UserData4Aiterate {
     public:
         attr_operator_t op;
         void* opData;
-        H5Object* location;
+        H5Object* location; // Consider changing to H5Location
+};
+
+// User data for visit iteration
+class UserData4Visit {
+    public:
+        visit_operator_t op;
+        void* opData;
+        H5Object* obj;
 };
 
 class H5_DLLCPP H5Object : public H5Location {
@@ -71,6 +85,9 @@ class H5_DLLCPP H5Object : public H5Location {
         // Iterate user's function over the attributes of this object.
         int iterateAttrs(attr_operator_t user_op, unsigned* idx = NULL, void* op_data = NULL);
 
+        // Recursively visit elements reachable from this object.
+        void visit(H5_index_t idx_type, H5_iter_order_t order, visit_operator_t user_op, void *op_data, unsigned int fields);
+
         // Returns the object header version of an object
         unsigned objVersion() const;
 
@@ -98,6 +115,7 @@ class H5_DLLCPP H5Object : public H5Location {
         ssize_t getObjName(H5std_string& obj_name, size_t len = 0) const;
         H5std_string getObjName() const;
 
+
 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 
    protected: