Add get_value_or() (#485)

* added get_value_or() in basic_node

* added api reference page for get_value_or()

* updated README

Author: fktn-k

README.md

@@ -16,14 +16,14 @@ fkYAML is a C++ header-only library to deserialize, serialize and build YAML doc
 It is also carefully desinged and tested to work with various compilers, C++ standards and platforms.  
 So, if you want portability & development speed-up, fkYAML is the way to go.  
 You can add YAML support into your projects by just including the header file(s).  
-This simple example deserializes a YAML string into a document, make simple modifications, and finally serializes the modified documentation to a YAML string.  
+This simple example (1) deserializes a YAML string into a document, (2) modifies the documentation, and finally (3) serializes the modified documentation to a YAML string.  
 ```cpp
 #include <iostream>
 #include <string>
 #include <fkYAML/node.hpp>
 
 int main() {
-    // 1. deserialize a YAML string into a document.
+    // 1. Deserialize a YAML string into a document.
     //    The input can be other container types or their iterators.
     //    `deserialize` accepts `FILE*`, `std::istream` as well.
     std::string yaml = R"(
@@ -40,7 +40,7 @@ works on:
     node["maintainer"] = "fktn-k";
     node.at("works on").as_seq().emplace_back("Windows");
 
-    // 3. serialize the modified document to a YAML string and save it.
+    // 3. Serialize the modified document to a YAML string and save it.
     std::ofstream ofs("out.yaml");
     ofs << node;
 

docs/docs/api/basic_node/get_value_or.md

@@ -0,0 +1,63 @@
+<small>Defined in header [`<fkYAML/node.hpp>`](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node.hpp)</small>
+
+# <small>fkyaml::basic_node::</small>get_value_or
+
+```cpp
+template <typename T, typename U>
+T get_value_or(U&& default_value) const noexcept;
+```
+
+This function tries to convert a [`fkyaml::basic_node`](./index.md) to `T`.  
+Visit the documentation for the [get_value](./get_value.md) function for supported types since this function internally calls it.  
+If the conversion fails, this function returns `default_value` instead of throwing an exception as the [`get_value`](./get_value.md) function does.  
+
+Just as the [`get_value`](./get_value.md) function, this function also makes a copy of the value.  
+If the copying costs too much, or if you need an address of the original value, then you should call one of the following functions instead.  
+
+* [`as_seq`](as_seq.md)
+* [`as_map`](as_map.md)
+* [`as_bool`](as_bool.md)
+* [`as_int`](as_int.md)
+* [`as_float`](as_float.md)
+* [`as_str`](as_str.md)
+
+## **Template Parameters**
+
+***T***
+:   A compatible value type which might be cv-qualified or a reference type.  
+
+***U***
+:   The default value type from which `T` (the 1st overload) or `BasicNodeType` (the 2nd overload) must be constructible.  
+    This is likely to be `const T&` or `T&&`.  
+
+***BasicNodeType***
+:   A basic_node template instance type.  
+
+## **Return Value**
+
+A value converted from the [basic_node](./index.md) object if the conversion succeeded, `default_value` otherwise.
+
+## **Examples**
+
+??? Example
+
+    ```cpp
+    --8<-- "apis/basic_node/get_value_or.cpp:9"
+    ```
+
+    output:
+    ```bash
+    --8<-- "apis/basic_node/get_value_or.output"
+    ```
+
+## **See Also**
+
+* [basic_node](index.md)
+* [get_value](get_value.md)
+* [as_seq](as_seq.md)
+* [as_map](as_map.md)
+* [as_bool](as_bool.md)
+* [as_int](as_int.md)
+* [as_float](as_float.md)
+* [as_str](as_str.md)
+* [node_value_converter::from_node](../node_value_converter/from_node.md)

docs/docs/api/basic_node/index.md

@@ -96,23 +96,24 @@ This class provides features to handle YAML nodes.
 | [is_string](is_string.md)             | checks if a basic_node has a string node value.                    |
 
 ### Conversions
-| Name                                      |          | Description                                                             |
-| ----------------------------------------- | -------- | ----------------------------------------------------------------------- |
-| [deserialize](deserialize.md)             | (static) | deserializes the first YAML document into a basic_node.                 |
-| [deserialize_docs](deserialize_docs.md)   | (static) | deserializes all YAML documents into basic_node objects.                |
-| [operator>>](extraction_operator.md)      |          | deserializes an input stream into a basic_node.                         |
-| [serialize](serialize.md)                 | (static) | serializes a basic_node into a YAML formatted string.                   |
-| [serialize_docs](serialize_docs.md)       | (static) | serializes basic_node objects into a YAML formatted string.             |
-| [operator<<](insertion_operator.md)       |          | serializes a basic_node into an output stream.                          |
-| [get_value](get_value.md)                 |          | converts a basic_node into a target type.                               |
-| [get_value_inplace](get_value_inplace.md) |          | converts a basic_node into a target type and write it to a destination. |
-| [as_seq](as_seq.md)                       |          | get reference to the sequence node value.                               |
-| [as_map](as_map.md)                       |          | get reference to the mapping node value.                                |
-| [as_bool](as_bool.md)                     |          | get reference to the boolean node value.                                |
-| [as_int](as_int.md)                       |          | get reference to the integer node value.                                |
-| [as_float](as_float.md)                   |          | get reference to the float node value.                                  |
-| [as_str](as_str.md)                       |          | get reference to the string node value.                                 |
-| [get_value_ref](get_value_ref.md)         |          | **(DEPRECATED)** converts a basic_node into reference to a target type. |
+| Name                                      |          | Description                                                                                       |
+| ----------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| [deserialize](deserialize.md)             | (static) | deserializes the first YAML document into a basic_node.                                           |
+| [deserialize_docs](deserialize_docs.md)   | (static) | deserializes all YAML documents into basic_node objects.                                          |
+| [operator>>](extraction_operator.md)      |          | deserializes an input stream into a basic_node.                                                   |
+| [serialize](serialize.md)                 | (static) | serializes a basic_node into a YAML formatted string.                                             |
+| [serialize_docs](serialize_docs.md)       | (static) | serializes basic_node objects into a YAML formatted string.                                       |
+| [operator<<](insertion_operator.md)       |          | serializes a basic_node into an output stream.                                                    |
+| [get_value](get_value.md)                 |          | converts a basic_node into a target type.                                                         |
+| [get_value_inplace](get_value_inplace.md) |          | converts a basic_node into a target type and write it to a destination.                           |
+| [get_value_or](get_value_or.md)           |          | tries to convert a basic_node into a target type.<br>returns a default value if conversion fails. |
+| [as_seq](as_seq.md)                       |          | get reference to the sequence node value.                                                         |
+| [as_map](as_map.md)                       |          | get reference to the mapping node value.                                                          |
+| [as_bool](as_bool.md)                     |          | get reference to the boolean node value.                                                          |
+| [as_int](as_int.md)                       |          | get reference to the integer node value.                                                          |
+| [as_float](as_float.md)                   |          | get reference to the float node value.                                                            |
+| [as_str](as_str.md)                       |          | get reference to the string node value.                                                           |
+| [get_value_ref](get_value_ref.md)         |          | **(DEPRECATED)** converts a basic_node into reference to a target type.                           |
 
 ### Iterators
 | Name                      | Description                                                                                                |

docs/docs/index.md

@@ -16,14 +16,14 @@ fkYAML is a C++ header-only library to deserialize, serialize and build YAML doc
 It is also carefully desinged and tested to work with various compilers, C++ standards and platforms.  
 So, if you want portability & development speed-up, fkYAML is the way to go.  
 You can add YAML support into your projects by just including the header file(s).  
-This simple example deserializes a YAML string into a document, make simple modifications, and finally serializes the modified documentation to a YAML string.  
+This simple example (1) deserializes a YAML string into a document, (2) modifies the documentation, and finally (3) serializes the modified documentation to a YAML string.  
 ```cpp
 #include <iostream>
 #include <string>
 #include <fkYAML/node.hpp>
 
 int main() {
-    // 1. deserialize a YAML string into a document.
+    // 1. Deserialize a YAML string into a document.
     //    The input can be other container types or their iterators.
     //    `deserialize` accepts `FILE*`, `std::istream` as well.
     std::string yaml = R"(
@@ -40,7 +40,7 @@ works on:
     node["maintainer"] = "fktn-k";
     node.at("works on").as_seq().emplace_back("Windows");
 
-    // 3. serialize the modified document to a YAML string and save it.
+    // 3. Serialize the modified document to a YAML string and save it.
     std::ofstream ofs("out.yaml");
     ofs << node;
 

docs/mkdocs.yml

@@ -142,6 +142,7 @@ nav:
     - get_type: api/basic_node/get_type.md
     - get_value: api/basic_node/get_value.md
     - get_value_inplace: api/basic_node/get_value_inplace.md
+    - get_value_or: api/basic_node/get_value_or.md
     - get_yaml_version_type: api/basic_node/get_yaml_version_type.md
     - has_anchor_name: api/basic_node/has_anchor_name.md
     - has_tag_name: api/basic_node/has_tag_name.md

examples/apis/basic_node/get_value_or.cpp

@@ -0,0 +1,65 @@
+//  _______   __ __   __  _____   __  __  __
+// |   __| |_/  |  \_/  |/  _  \ /  \/  \|  |     fkYAML: A C++ header-only YAML library (supporting code)
+// |   __|  _  < \_   _/|  ___  |    _   |  |___  version 0.4.2
+// |__|  |_| \__|  |_|  |_|   |_|___||___|______| https://github.com/fktn-k/fkYAML
+//
+// SPDX-FileCopyrightText: 2023-2025 Kensuke Fukutani <fktn.dev@gmail.com>
+// SPDX-License-Identifier: MIT
+
+#include <iostream>
+#include <string>
+#include <tuple>
+#include <unordered_map>
+#include <vector>
+#include <fkYAML/node.hpp>
+
+int main() {
+    // try get sequence node values
+    fkyaml::node seq = {true, false};
+
+    // successful case
+    std::vector<bool> vec_def {false, true};
+    auto bool_vec = seq.get_value_or<std::vector<bool>>(vec_def);
+    for (auto b : bool_vec) {
+        std::cout << std::boolalpha << b << std::endl;
+    }
+
+    // error case
+    auto tpl_def = std::make_tuple<int, bool, std::string>(0, false, "default");
+    auto tpl = seq.get_value_or<std::tuple<int, bool, std::string>>(std::move(tpl_def));
+    std::cout << std::get<0>(tpl) << ", ";
+    std::cout << std::get<1>(tpl) << ", ";
+    std::cout << std::get<2>(tpl) << "\n\n";
+
+    // try to get mapping node values
+    fkyaml::node map = {
+        {0, "foo"},
+        {1, "bar"},
+        {2, "baz"},
+    };
+    std::unordered_map<uint32_t, std::string> umap_def {{0, "defalt"}};
+    auto umap = map.get_value_or<std::unordered_map<uint32_t, std::string>>(std::move(umap_def));
+    for (auto& p : umap) {
+        std::cout << p.first << " : " << p.second << std::endl;
+    }
+    std::cout << std::endl;
+
+    // try to get scalar node values.
+    fkyaml::node scalar = 1.23;
+
+    // get the node value (value gets copied).
+    auto dbl_val = scalar.get_value_or<double>(0.);
+    auto str_val = scalar.get_value_or<std::string>("default");
+
+    std::cout << dbl_val << std::endl;
+    std::cout << str_val << std::endl;
+
+    // Numeric scalar value will be converted to target numeric types inside get_value_or().
+    auto bool_val = scalar.get_value_or<bool>(false); // 1.23 -> true
+    auto int_val = scalar.get_value_or<int>(0);       // 1.23 -> 1
+
+    std::cout << std::boolalpha << bool_val << std::endl;
+    std::cout << int_val << std::endl;
+
+    return 0;
+}

examples/apis/basic_node/get_value_or.output

@@ -0,0 +1,12 @@
+true
+false
+0, false, default
+
+2 : baz
+1 : bar
+0 : foo
+
+1.23
+default
+true
+1

include/fkYAML/node.hpp

@@ -1299,24 +1299,25 @@ class basic_node {
     /// @brief Get the node value object converted into a given type.
     /// @note This function requires T objects to be default constructible. Also, T cannot be either a reference,
     /// pointer or C-style array type.
-    /// @tparam T A compatible value type which might be cv-qualified.
-    /// @tparam ValueType A compatible value type with cv-qualifiers removed by default.
-    /// @return A compatible native data value converted from the basic_node object.
+    /// @tparam T A compatible value type which may be cv-qualified.
+    /// @tparam ValueType A compatible value type (T without cv-qualifiers by default).
+    /// @return A value converted from this basic_node object.
     /// @sa https://fktn-k.github.io/fkYAML/api/basic_node/get_value/
     template <
         typename T, typename ValueType = detail::remove_cv_t<T>,
-        detail::enable_if_t<std::is_default_constructible<ValueType>::value, int> = 0>
+        detail::enable_if_t<
+            detail::conjunction<std::is_default_constructible<ValueType>, detail::negation<std::is_pointer<T>>>::value,
+            int> = 0>
     T get_value() const noexcept(
         noexcept(std::declval<const basic_node&>().template get_value_impl<ValueType>(std::declval<ValueType&>()))) {
         // emit a compile error if T is either a reference, pointer or C-style array type.
         static_assert(
             !std::is_reference<T>::value,
             "get_value() cannot be called with reference types. "
             "You might want to call one of as_seq(), as_map(), as_bool(), as_int(), as_float() or as_str().");
-        static_assert(!std::is_pointer<T>::value, "get_value() cannot be called with pointer types.");
         static_assert(
             !std::is_array<T>::value,
-            "get_value() cannot be called with C-style array types. you might want to call get_value_inplace().");
+            "get_value() cannot be called with C-style array types. You might want to call get_value_inplace().");
 
         auto ret = ValueType();
         resolve_reference().get_value_impl(ret);
@@ -1333,6 +1334,47 @@ class basic_node {
         resolve_reference().get_value_impl(value_ref);
     }
 
+    /// @brief Get the node value object converted to a given type. If the conversion fails, this function returns a
+    /// given default value instead.
+    /// @note This function requires T to be default constructible. Also, T cannot be either a reference, pointer or
+    /// C-style array type.
+    /// @tparam T A compatible value type which may be cv-qualified.
+    /// @tparam U A default value type from which T must be constructible.
+    /// @param default_value The default value returned if conversion fails.
+    /// @return A value converted from this basic_node object if conversion succeeded, the given default value
+    /// otherwise.
+    /// @sa https://fktn-k.github.io/fkYAML/api/basic_node/get_value_or/
+    template <
+        typename T, typename U,
+        detail::enable_if_t<
+            detail::conjunction<
+                std::is_constructible<T, U>, std::is_default_constructible<T>,
+                detail::negation<std::is_pointer<T>>>::value,
+            int> = 0>
+    T get_value_or(U&& default_value) const noexcept {
+        static_assert(
+            !std::is_reference<T>::value,
+            "get_value_or() cannot be called with reference types. "
+            "You might want to call one of as_seq(), as_map(), as_bool(), as_int(), as_float() or as_str().");
+        static_assert(
+            !std::is_array<T>::value,
+            "get_value_or() cannot be called with C-style array types. You might want to call get_value_inplace().");
+
+        // TODO:
+        // Ideally, there should be no exception thrown in this kind of function. However, achieving that would require
+        // a lot of refactoring and/or some API changes, especially `from_node` interface definition. So, try-catch is
+        // used instead for now.
+        try {
+            return get_value<T>();
+        }
+        catch (const std::exception& /*unused*/) {
+            // Any exception derived from std::exception is interpreted as a conversion failure in some way
+            // since user-defined from_node function may throw a different object from a fkyaml::type_error.
+            // and std::exception is usually the base class of user-defined exception types.
+            return std::forward<U>(default_value);
+        }
+    }
+
     /// @brief Explicit reference access to the internally stored YAML node value.
     /// @tparam ReferenceType Reference type to the target YAML node value.
     /// @return Reference to the internally stored YAML node value.