add fetch_existing, deprecate fetch_child (#528)

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 #### General 
 - Added support for children with names that include `/`. Since slashes are part of Conduit's hierarchal path mechanism, you must use explicit methods (add_child(), child(), etc) to create and access children with these types of names. These names are also supported in all basic i/o cases (JSON, YAML, Conduit Binary).
 - Added Node::child and Schema::child methods, which provide access to existing children by name.
+- Added Node::fetch_existing and Schema::fetch_existing methods, which provide access to existing paths or error when given a bad path.
 - Added Node::add_child() and Node::remove_child() to support direct operatrions and cases where names have `/`s.
 - Added a set of conduit::utils::log::remove_* filtering functions, which process conduit log/info nodes and strip out the requested information (useful for focusing the often verbose output in log/info nodes).
 
@@ -23,6 +24,10 @@ and this project aspires to adhere to [Semantic Versioning](https://semver.org/s
 #### Relay
 - Use H5F_ACC_RDONLY in relay::io::is_hdf5_file to avoid errors when checking files that already have open HDF5 handles.
 
+### Changed
+
+#### General 
+- Node::fetch_child and Schema::fetch_child are deprecated in favor of the more clearly named Node::fetch_existing and Schema::fetch_existing. fetch_child variants still exist, but will be removed in a future release.
 
 ## [0.5.1] - Released 2020-01-18
 

src/docs/sphinx/glossary.rst

@@ -76,7 +76,7 @@ Used for Node instances in *Object* role interface. In the Object role, a Node h
  - Node::remove(string)
 
  - Schema::fetch(string)
- - Schema::fetch_child(string)
+ - Schema::fetch_existing(string)
  - Schema::fetch_ptr(string)
  - Schema::operator=(string)
  - Schema::has_path(string)

src/docs/sphinx/t_conduit_docs_tutorial_errors_out.txt

@@ -15,7 +15,7 @@ Running main() from gtest_main.cc
  error_handlers
 [INFO] An info message
 [WARNING!] Node::as_float32() const -- DataType float64 at path my_value does not equal expected DataType float32
-[ERROR!] Cannot const fetch_child, Node(my_value) is not an object
+[ERROR!] Cannot const fetch_existing, Node(my_value) is not an object
 [/Users/harrison37/Work/conduit/src/tests/docs/t_conduit_docs_tutorial_errors.cpp : 137]
  error_handlers
 [       OK ] conduit_tutorial.error_handlers (1 ms)

src/libs/blueprint/conduit_blueprint_zfparray.cpp

@@ -114,7 +114,7 @@ bool verify(const conduit::Node &n,
     }
     else
     {
-        const Node &n_header = n.fetch_child(ZFP_HEADER_FIELD_NAME);
+        const Node &n_header = n.fetch_existing(ZFP_HEADER_FIELD_NAME);
 
         // compressed-array headers consist of uint8 words
         if(!n_header.dtype().is_uint8()) {
@@ -130,7 +130,7 @@ bool verify(const conduit::Node &n,
     }
     else
     {
-        const Node &compressed_data = n.fetch_child(ZFP_COMPRESSED_DATA_FIELD_NAME);
+        const Node &compressed_data = n.fetch_existing(ZFP_COMPRESSED_DATA_FIELD_NAME);
 
         if(!compressed_data.dtype().is_unsigned_integer()) {
             log::error(info, proto_name, "ZFP compressed-data node's dtype is incompatible with the compiled ZFP bitstream word size");

src/libs/conduit/c/conduit_node.h

@@ -89,6 +89,10 @@ CONDUIT_API void          conduit_node_destroy(conduit_node *cnode);
 CONDUIT_API conduit_node *conduit_node_fetch(conduit_node *cnode,
                                              const char *path);
 
+//-----------------------------------------------------------------------------
+CONDUIT_API conduit_node *conduit_node_fetch_existing(conduit_node *cnode,
+                                                      const char *path);
+
 //-----------------------------------------------------------------------------
 CONDUIT_API conduit_node *conduit_node_append(conduit_node *cnode);
 

src/libs/conduit/c/conduit_node_c.cpp

@@ -101,6 +101,14 @@ conduit_node_fetch(conduit_node *cnode,
     return c_node(cpp_node(cnode)->fetch_ptr(path));
 }
 
+//-----------------------------------------------------------------------------
+conduit_node *
+conduit_node_fetch_existing(conduit_node *cnode,
+                            const char *path)
+{
+    return c_node(&cpp_node(cnode)->fetch_existing(path));
+}
+
 //-----------------------------------------------------------------------------
 conduit_node *
 conduit_node_append(conduit_node *cnode)

src/libs/conduit/conduit_node.cpp

@@ -12018,12 +12018,12 @@ Node::child(const std::string &name)
 
 //---------------------------------------------------------------------------//
 const Node&
-Node::fetch_child(const std::string &path) const
+Node::fetch_existing(const std::string &path) const
 {
-    // const fetch_child w/ path requires object role
+    // const fetch_existing w/ path requires object role
     if(!dtype().is_object())
     {
-        CONDUIT_ERROR("Cannot fetch_child, Node(" << this->path()
+        CONDUIT_ERROR("Cannot fetch_existing, Node(" << this->path()
                       << ") is not an object");
     }
 
@@ -12034,19 +12034,19 @@ Node::fetch_child(const std::string &path) const
     // cull empty paths
     if(p_curr == "")
     {
-        return this->fetch_child(p_next);
+        return this->fetch_existing(p_next);
     }
 
     // check for parent
     if(p_curr == "..")
     {
         if(m_parent == NULL)
         {
-            CONDUIT_ERROR("Cannot fetch_child from NULL parent" << path);
+            CONDUIT_ERROR("Cannot fetch_existing from NULL parent" << path);
         }
         else
         {
-            return m_parent->fetch_child(p_next);
+            return m_parent->fetch_existing(p_next);
         }
     }
 
@@ -12055,7 +12055,7 @@ Node::fetch_child(const std::string &path) const
     {
         // `child_index` will error if p_curr is invalid
         size_t idx = (size_t)m_schema->child_index(p_curr);
-        return m_children[idx]->fetch_child(p_next);
+        return m_children[idx]->fetch_existing(p_next);
     }
     // is direct child
     else
@@ -12067,12 +12067,12 @@ Node::fetch_child(const std::string &path) const
 
 //---------------------------------------------------------------------------//
 Node&
-Node::fetch_child(const std::string &path)
+Node::fetch_existing(const std::string &path)
 {
-    // fetch_child w/ path requires object role
+    // fetch_existing w/ path requires object role
     if(!dtype().is_object())
     {
-        CONDUIT_ERROR("Cannot fetch_child, Node(" << this->path()
+        CONDUIT_ERROR("Cannot fetch_existing, Node(" << this->path()
                       << ") is not an object");
     }
 
@@ -12083,19 +12083,19 @@ Node::fetch_child(const std::string &path)
     // cull empty paths
     if(p_curr == "")
     {
-        return this->fetch_child(p_next);
+        return this->fetch_existing(p_next);
     }
 
     // check for parent
     if(p_curr == "..")
     {
         if(m_parent == NULL)
         {
-            CONDUIT_ERROR("Cannot fetch_child from NULL parent" << path);
+            CONDUIT_ERROR("Cannot fetch_existing from NULL parent" << path);
         }
         else
         {
-            return m_parent->fetch_child(p_next);
+            return m_parent->fetch_existing(p_next);
         }
     }
 
@@ -12115,10 +12115,24 @@ Node::fetch_child(const std::string &path)
     }
     else
     {
-        return m_children[idx]->fetch_child(p_next);
+        return m_children[idx]->fetch_existing(p_next);
     }
 }
 
+
+//---------------------------------------------------------------------------//
+Node&
+Node::fetch_child(const std::string &path)
+{
+    return fetch_existing(path);
+}
+//---------------------------------------------------------------------------//
+const Node&
+Node::fetch_child(const std::string &path) const
+{
+    return fetch_existing(path);
+}
+
 //---------------------------------------------------------------------------//
 Node&
 Node::fetch(const std::string &path)
@@ -12190,7 +12204,7 @@ Node::fetch(const std::string &path)
 const Node&
 Node::fetch(const std::string &path) const
 {
-    return fetch_child(path);
+    return fetch_existing(path);
 }
 
 

src/libs/conduit/conduit_node.hpp

@@ -3560,6 +3560,13 @@ class CONDUIT_API Node
     Node             &fetch(const std::string &path);
     const Node       &fetch(const std::string &path) const;
 
+    /// the `fetch_existing' methods don't modify map structure, if a path
+    /// doesn't exist they will throw an exception
+    Node             &fetch_existing(const std::string &path);
+    const Node       &fetch_existing(const std::string &path) const;
+
+    /// DEPRECATED: `fetch_child` is deprecated in favor of `fetch_existing`
+    ///
     /// the `fetch_child' methods don't modify map structure, if a path
     /// doesn't exist they will throw an exception
     Node             &fetch_child(const std::string &path);

src/libs/conduit/conduit_schema.cpp

@@ -762,7 +762,7 @@ Schema::child(const std::string &name) const
 
 //---------------------------------------------------------------------------//
 Schema&
-Schema::fetch_child(const std::string &path)
+Schema::fetch_existing(const std::string &path)
 {
     // fetch w/ path forces OBJECT_ID
     if(m_dtype.id() != DataType::OBJECT_ID)
@@ -783,7 +783,7 @@ Schema::fetch_child(const std::string &path)
         }
         else
         {
-            return m_parent->fetch_child(p_next);
+            return m_parent->fetch_existing(p_next);
         }
     }
 
@@ -793,14 +793,14 @@ Schema::fetch_child(const std::string &path)
     }
     else
     {
-        return children()[idx]->fetch_child(p_next);
+        return children()[idx]->fetch_existing(p_next);
     }
 }
 
 
 //---------------------------------------------------------------------------//
 const Schema &
-Schema::fetch_child(const std::string &path) const
+Schema::fetch_existing(const std::string &path) const
 {
     // fetch w/ path forces OBJECT_ID
     if(m_dtype.id() != DataType::OBJECT_ID)
@@ -814,7 +814,7 @@ Schema::fetch_child(const std::string &path) const
     if(p_curr == "..")
     {
         if(m_parent != NULL) // TODO: check for erro (no parent)
-           return m_parent->fetch_child(p_next);
+           return m_parent->fetch_existing(p_next);
     }
 
     size_t idx = (size_t) child_index(p_curr);
@@ -825,10 +825,24 @@ Schema::fetch_child(const std::string &path) const
     }
     else
     {
-        return children()[idx]->fetch_child(p_next);
+        return children()[idx]->fetch_existing(p_next);
     }
 }
 
+//---------------------------------------------------------------------------//
+Schema&
+Schema::fetch_child(const std::string &path)
+{
+    return fetch_existing(path);
+}
+
+//---------------------------------------------------------------------------//
+const Schema &
+Schema::fetch_child(const std::string &path) const
+{
+    return fetch_existing(path);
+}
+
 //---------------------------------------------------------------------------//
 index_t
 Schema::child_index(const std::string &name) const
@@ -960,7 +974,7 @@ Schema::fetch(const std::string &path)
 const Schema &
 Schema::fetch(const std::string &path) const
 {
-    return fetch_child(path);
+    return fetch_existing(path);
 }
 
 //---------------------------------------------------------------------------//
@@ -982,7 +996,7 @@ Schema::fetch_ptr(const std::string &path) const
 const Schema &
 Schema::operator[](const std::string &path) const
 {
-    return fetch_child(path);
+    return fetch_existing(path);
 }
 
 //---------------------------------------------------------------------------//

src/libs/conduit/conduit_schema.hpp

@@ -262,6 +262,14 @@ class CONDUIT_API Schema
 /// Object interface methods
 //
 //-----------------------------------------------------------------------------
+
+    /// the `fetch_existing' methods don't modify map structure, if a path
+    /// doesn't exist they will throw an exception
+    Schema           &fetch_existing(const std::string &path);
+    const Schema     &fetch_existing(const std::string &path) const;
+
+    /// DEPRECATED: `fetch_child` is deprecated in favor of `fetch_existing`
+    ///
     /// the `fetch_child' methods don't modify map structure, if a path
     /// doesn't exist they will throw an exception
     Schema           &fetch_child(const std::string &path);

src/libs/conduit/fortran/conduit_fortran.F90

@@ -170,6 +170,16 @@ function c_conduit_node_fetch(cnode, path) result(res) &
          type(C_PTR) :: res
      end function c_conduit_node_fetch
 
+     !--------------------------------------------------------------------------
+     function c_conduit_node_fetch_existing(cnode, path) result(res) &
+              bind(C, name="conduit_node_fetch_existing")
+          use iso_c_binding
+          implicit none
+          type(C_PTR), value, intent(IN) :: cnode
+          character(kind=C_CHAR), intent(IN) :: path(*)
+          type(C_PTR) :: res
+      end function c_conduit_node_fetch_existing
+
      !--------------------------------------------------------------------------
      function conduit_node_append(cnode) result(res) &
               bind(C, name="conduit_node_append")
@@ -1205,6 +1215,17 @@ function conduit_node_fetch(cnode, path) result(res)
         res = c_conduit_node_fetch(cnode, trim(path) // C_NULL_CHAR)
     end function conduit_node_fetch
 
+    !--------------------------------------------------------------------------
+    function conduit_node_fetch_existing(cnode, path) result(res)
+        use iso_c_binding
+        implicit none
+        type(C_PTR), value, intent(IN) :: cnode
+        character(*), intent(IN) :: path
+        type(C_PTR) :: res
+        !---
+        res = c_conduit_node_fetch_existing(cnode, trim(path) // C_NULL_CHAR)
+    end function conduit_node_fetch_existing
+
     !--------------------------------------------------------------------------
     function conduit_node_has_child(cnode, name) result(res)
         use iso_c_binding

src/libs/conduit/fortran/conduit_fortran_obj.f90

@@ -60,6 +60,7 @@ module conduit_obj
 
         !----------------------------------------------------------------------
         procedure :: fetch  => conduit_node_obj_fetch
+        procedure :: fetch_existing  => conduit_node_obj_fetch_existing
         procedure :: append => conduit_node_obj_append
         procedure :: child_by_index => conduit_node_obj_child
         procedure :: child_by_name  => conduit_node_obj_child_by_name
@@ -459,6 +460,16 @@ function conduit_node_obj_fetch(obj, path) result(res)
         res%cnode = conduit_node_fetch(obj%cnode, trim(path) // C_NULL_CHAR)
      end function conduit_node_obj_fetch
 
+    !--------------------------------------------------------------------------
+    function conduit_node_obj_fetch_existing(obj, path) result(res)
+        use iso_c_binding
+        implicit none
+        class(node) :: obj
+        character(*) :: path
+        type(node) :: res
+        res%cnode = conduit_node_fetch_existing(obj%cnode, trim(path) // C_NULL_CHAR)
+    end function conduit_node_obj_fetch_existing
+
     !--------------------------------------------------------------------------
     function conduit_node_obj_append(obj) result(res)
         use iso_c_binding