find.hpp

# find.hpp #

This function searches for a value in a `toml::value` and performs type conversion if necessary.

> `toml::value` can change the type it stores, and `toml::find` accommodates these types. Technically, all functions use `toml::basic_value<TC>`. However, for simplicity, we refer to it as `toml::value` in explanations unless a distinction is necessary. In the documentation, if the template parameter `TC` changes the type, assume that types like `toml::value::integer_type` will also change accordingly.

# `toml::find` #

## Overview #

`toml::find` uses template arguments for the type you want to retrieve and function arguments for the key of the value you want to find.

    template<typename T, typename TC, typename ... Keys>
    T find(const basic_value<TC>& v, Keys ... keys);

The supported types for `T` and the behavior of the conversion are the same as for `toml::get`.

If `T` is not specified, a `toml::value` will be returned.

Keys can be of type `toml::value::key_type` or `std::size_t`. When multiple keys are provided, the function will search recursively through sub-tables or arrays. If a `toml::value::key_type` is given, `toml::value` is interpreted as a `toml::table`; if a `std::size_t` is given, `toml::value` is interpreted as a `toml::array`.

### Note on Recursive Search #

TOML allows for bare keys as well as quoted keys (enclosed in `"` or `'`). Using a quoted key like `"foo.bar" = "baz"` means no sub-table is constructed, and the key is `"foo.bar"`. To handle such patterns, toml11 does not split keys containing `.` and searches using the full string.

Consider the following TOML file:

    [foo]
    [foo.bar]
    baz = "hoge"

    ["foo.bar"]
    baz = "fuga"

The corresponding usage of `toml::find` is shown below:

    const auto input = toml::parse("input.toml");
    const auto baz1 = toml::find<std::string>(input, "foo", "bar", "baz"); // hoge
    const auto baz2 = toml::find<std::string>(input, "foo.bar",    "baz"); // fuga

cf. toml.io/en/v1.0.0#keys

## `toml::find(value, key)` #

Searches for `key` in `value` as if `value` were a `toml::table`, then converts using `toml::get`.

    template<typename T, typename TC>
    /* Equivalent to toml::get<T>(const value&) */ find(
        const basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);

    template<typename T, typename TC>
    /* Equivalent to toml::get<T>(value&) */ find(
        basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);

    template<typename T, typename TC>
    /* Equivalent to toml::get<T>(value&&) */ find(
        basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);

If `T` is not specified, the function returns a `toml::value` without conversion.

    template<typename TC>
    basic_value<TC> const& find(
        basic_value<TC> const& v, const typename basic_value<TC>::key_type& ky);

    template<typename TC>
    basic_value<TC>& find(
        basic_value<TC>& v, const typename basic_value<TC>::key_type& ky);

    template<typename TC>
    basic_value<TC> find(
        basic_value<TC>&& v, const typename basic_value<TC>::key_type& ky);

### Exceptions #

If the `toml::value` does not contain a `table`, a `toml::type_error` is thrown.

If the contained `table` does not have the specified element, a `std::out_of_range` is thrown.

If the specified element cannot be converted to `T` (i.e., `toml::get` fails), a `toml::type_error` is thrown.

## `toml::find(value, index)` #

Accesses the `index`-th element of `value` as if `value` were a `toml::array`, then converts using `toml::get`.

    template<typename T, typename TC>
    /* Equivalent to toml::get<T>(const value&) */ find(
        const basic_value<TC>& v, const std::size_t index);

    template<typename T, typename TC>
    /* Equivalent to toml::get<T>(value&) */ find(
        basic_value<TC>& v, const std::size_t index);

    template<typename T, typename TC>
    /* Equivalent to toml::get<T>(value&&) */ find(
        basic_value<TC>&& v, const std::size_t index);

If `T` is not specified, the function returns a `toml::value` without conversion.

    template<typename TC>
    basic_value<TC> const& find(basic_value<TC> const& v, const std::size_t ky);

    template<typename TC>
    basic_value<TC>& find(basic_value<TC>& v, const std::size_t ky);

    template<typename TC>
    basic_value<TC> find(basic_value<TC>&& v, const std::size_t ky);

### Exceptions #

If the `toml::value` does not contain an `array`, a `toml::type_error` is thrown.

If the contained `array` does not have the specified number of elements, a `std::out_of_range` is thrown.

If the specified element cannot be converted to `T` (i.e., `toml::get` fails), a `toml::type_error` is thrown.

## `toml::find(value, keys...)` #

    template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
    /* Equivalent to toml::get<T>(const value&) */ find(
        const basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);

    template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
    /* Equivalent to toml::get<T>(value&) */ find(
        basic_value<TC>& v, const K1& k1, const K2& k2, const Ks& ... ks);

    template<typename T, typename TC, typename K1, typename K2, typename ... Ks>
    /* Equivalent to toml::get<T>(value&&) */ find(
        basic_value<TC>&& v, const K1& k1, const K2& k2, const Ks& ... ks);

This function calls `toml::find` recursively.

The failure conditions and the exceptions thrown are the same as those for `toml::find`.

# `toml::find_or(value, key, fallback)` #

    template<typename T, typename TC, typename Key>
    T find_or(const basic_value<TC>& v, const Key& key, T&& opt);

The `find_or` function takes a default value to avoid throwing an exception when the search fails.

The default value must be of the same type as the return type `T`. Therefore, unlike `toml::find<T>`, `find_or` infers the type `T`.

You can specify `T` explicitly with `find_or<T>`, but this always returns a new value. To obtain a reference, do not specify `T`.

## When `T` is `basic_value` #

    template<typename TC, typename K>
    basic_value<TC>& find_or(basic_value<TC>& v, const K& key, basic_value<TC>& opt) noexcept

    template<typename TC, typename K>
    basic_value<TC> const& find_or(const basic_value<TC>& v, const K& key, const basic_value<TC>& opt) noexcept

Searches for the corresponding value and returns it without conversion. Because no conversion is needed, a reference can be returned.

If the value is not found, the default value is returned.

## When `T` is `toml::value::{some_type}` #

    template<typename T, typename TC, typename K>
    T& find_or(basic_value<TC>& v, const K& key, T& opt) noexcept

    template<typename T, typename TC, typename K>
    T const& find_or(const basic_value<TC>& v, const K& key, const T& opt) noexcept

Searches for the corresponding value and returns it without conversion. Because no conversion is needed, a reference can be returned.

If the value is not found or if a different type is stored, the default value is returned.

## When `T` is `const char*` #

    template<typename T, typename TC, typename K>
    T find_or(const basic_value<TC>& v, const K& key, T opt)

Searches for the corresponding value and returns it as a `std::string`.

Since the fallback is constructed from `const char*` to `std::string`, a reference cannot be returned in case of failure.

## When `T` is any other type #

    template<typename T, typename TC, typename K>
    T find_or(const basic_value<TC>& v, const K& key, T opt);

Searches for the corresponding value and converts it to `T` before returning it.

Because conversion is performed, a reference cannot be returned.

## When multiple keys are provided #

    template<typename Value, typename K1, typename K2, typename K3, typename ... Ks>
    auto find_or(Value&& v, const K1& k1, const K2& k2, K3&& k3, Ks&& ... keys) noexcept
     -> decltype(find_or(v, k2, std::forward<K3>(k3), std::forward<Ks>(keys)...))

Interprets the last element in the key sequence as the default value and applies `find_or` recursively.

If the inferred type of `T` is `toml::value` or `toml::value::some_type`, a reference can be returned.

If `T` is explicitly specified, conversion is always performed.

# Related #

- get.hpp
- value.hpp