diff --git a/LICENSE.txt b/LICENSE.txt index a736ba15..50eaec62 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Kensuke Fukutani +Copyright (c) 2023-2024 Kensuke Fukutani Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index adf16d50..028d2bf2 100644 --- a/README.md +++ b/README.md @@ -184,7 +184,7 @@ Note that, since fkYAML deserializes scalars into native booleans or integers du This project is distributed under the [MIT License](https://opensource.org/license/mit/): -Copyright (c) 2023 Kensuke Fukutani +Copyright (c) 2023-2024 Kensuke Fukutani Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/examples/ex_basic_node_constructor_7.cpp b/docs/examples/ex_basic_node_constructor_7.cpp index 831533de..fe6b141a 100644 --- a/docs/examples/ex_basic_node_constructor_7.cpp +++ b/docs/examples/ex_basic_node_constructor_7.cpp @@ -10,7 +10,12 @@ #include int main() { - fkyaml::node n({true, false}); + // create a sequence. + fkyaml::node n = {true, false}; std::cout << n << std::endl; + + // create a mapping. + fkyaml::node n2 = {{"foo", 1024}}; + std::cout << n2 << std::endl; return 0; } diff --git a/docs/examples/ex_basic_node_constructor_7.output b/docs/examples/ex_basic_node_constructor_7.output index 70c48721..ee41427a 100644 --- a/docs/examples/ex_basic_node_constructor_7.output +++ b/docs/examples/ex_basic_node_constructor_7.output @@ -1,3 +1,5 @@ - true - false +foo: 1024 + diff --git a/docs/examples/ex_basic_node_constructor_8.output b/docs/examples/ex_basic_node_constructor_8.output deleted file mode 100644 index ee41427a..00000000 --- a/docs/examples/ex_basic_node_constructor_8.output +++ /dev/null @@ -1,5 +0,0 @@ -- true -- false - -foo: 1024 - diff --git a/docs/examples/ex_basic_node_constructor_8.cpp b/docs/examples/ex_basic_node_move_assignment_operator.cpp similarity index 70% rename from docs/examples/ex_basic_node_constructor_8.cpp rename to docs/examples/ex_basic_node_move_assignment_operator.cpp index e0482113..b8d17c5b 100644 --- a/docs/examples/ex_basic_node_constructor_8.cpp +++ b/docs/examples/ex_basic_node_move_assignment_operator.cpp @@ -10,10 +10,12 @@ #include int main() { - fkyaml::node n = {true, false}; - std::cout << n << std::endl; + fkyaml::node n = true; + fkyaml::node n2 = 123; + n = std::move(n2); + + std::cout << std::boolalpha << n.is_integer() << std::endl; + std::cout << n.get_value() << std::endl; - fkyaml::node n2 = {{"foo", 1024}}; - std::cout << n2 << std::endl; return 0; } diff --git a/docs/examples/ex_basic_node_move_assignment_operator.output b/docs/examples/ex_basic_node_move_assignment_operator.output new file mode 100644 index 00000000..892bea09 --- /dev/null +++ b/docs/examples/ex_basic_node_move_assignment_operator.output @@ -0,0 +1,2 @@ +true +123 diff --git a/docs/mkdocs/Makefile b/docs/mkdocs/Makefile index 22a9776f..3a459bba 100644 --- a/docs/mkdocs/Makefile +++ b/docs/mkdocs/Makefile @@ -7,6 +7,13 @@ serve: build venv/bin/mkdocs serve # install a Python virtual environment +# requirements.txt was generated by running the following commands. +# ``` +# python3 -m venv venv +# venv/bin/pip install --upgrade pip +# venv/bin/pip install mkdocs-material mkdocs-git-revision-date-localized-plugin +# venv/bin/pip freeze > ./requirements.txt +# ``` install-venv: requirements.txt python3 -m venv venv venv/bin/pip install --upgrade pip diff --git a/docs/mkdocs/docs/api/basic_node/add_anchor_name.md b/docs/mkdocs/docs/api/basic_node/add_anchor_name.md index 6154a3a7..b0784638 100644 --- a/docs/mkdocs/docs/api/basic_node/add_anchor_name.md +++ b/docs/mkdocs/docs/api/basic_node/add_anchor_name.md @@ -15,7 +15,9 @@ If the basic_node has already had any anchor name, the new anchor name overwrite ***`anchor_name`*** [in] : An anchor name. This should not be empty. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_add_anchor_name.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/add_tag_name.md b/docs/mkdocs/docs/api/basic_node/add_tag_name.md index 55965862..e865e951 100644 --- a/docs/mkdocs/docs/api/basic_node/add_tag_name.md +++ b/docs/mkdocs/docs/api/basic_node/add_tag_name.md @@ -15,7 +15,9 @@ If the basic_node has already had any tag name, the new tag name overwrites the ***`tag_name`*** [in] : A tag name. This should not be empty. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_add_tag_name.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/alias_of.md b/docs/mkdocs/docs/api/basic_node/alias_of.md index 2c091381..e0db2d26 100644 --- a/docs/mkdocs/docs/api/basic_node/alias_of.md +++ b/docs/mkdocs/docs/api/basic_node/alias_of.md @@ -7,23 +7,25 @@ static basic_node alias_of(const basic_node& anchor); ``` Creates an alias YAML node from an anchor node. +If the given anchor node does not have any non-empty anchor name, an [`fkyaml::exception`](../exception/index.md) will be thrown. ## **Parameters** ***anchor*** [in] : A basic_node object with an anchor name. - This node must have some anchor name. + This node must have a non-empty anchor name. ## **Return Value** -An alias YAML node which is created from the given anchor node. -If the given anchor node does not have any non-empty anchor name, an [`fkyaml::exception`](../exception/index.md) will be thrown. +An alias node which refers to the given anchor node. !!! Note If this API throws an exception, the internally stored YAML node value in the given anchor node stays intact. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_alias_of.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/at.md b/docs/mkdocs/docs/api/basic_node/at.md index 041fa9fc..c63d30ff 100644 --- a/docs/mkdocs/docs/api/basic_node/at.md +++ b/docs/mkdocs/docs/api/basic_node/at.md @@ -3,77 +3,61 @@ # fkyaml::basic_node::at ```cpp -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -basic_node& at(KeyType&& key); // (1) - -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -const basic_node& at(KeyType&& key) const; // (2) - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -basic_node& at(KeyType&& key); // (3) - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -const basic_node& at(KeyType&& key) const; // (4) +// (1) +template +basic_node& at(KeyType&& key); + +template +const basic_node& at(KeyType&& key) const; + +// (2) +template +basic_node& at(BasicNodeType&& key); + +template +const basic_node& at(BasicNodeType&& key) const; ``` -Access to a YAML node element with either an index (for sequences) or a key (for mappings). -Before accessing the element, this function checks the bounds in the case of a sequence or the existence of a key in the case of a mapping. -This function therefore costs a bit more than [`basic_node::operator[]()`](operator[].md) function due to the extra checks. -Furthermore, this function may throw the following exceptions: +Access to an element in a container node with either an index or key value. +This function must be called on a container node, or a [`fkyaml::type_error`](../exception/type_error.md) would be thrown. -* [`fkyaml::type_error`](../exception/type_error.md) - * if the queried node is neither a sequence nor a mapping, or - * if the queried node is a sequence but the given `key` is not an integer. -* [`fkyaml::out_of_range`](../exception/out_of_range.md) - * if the given key does not exist in the queried mapping, or - * if the given index exceeds the size of the queried sequence. +The input parameter `key` must be either a [`basic_node`](index.md) object or an object of a compatible type, i.e., a type with which a [`basic_node`](index.md) object can be constructible. +Note that the overload (1) internally constructs a temporal [`basic_node`](index.md) object. +So, if you use the same key multiple times, for example, in a for loop, consider creating a [`basic_node`](index.md) as a key first for better performance. -## Overload (1), (2) +Furthermore, unlike the [`operator[]`](operator[].md), this function executes one of the following checks depending on the target node value type. -```cpp -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -basic_node& at(KeyType&& key); // (1) - -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -const basic_node& at(KeyType&& key) const; // (2) -``` +* For sequence nodes + * Whether `key` is of an integeral type (e.g., `int`, `size_t`) or an integer node. + If not, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. + * Whether the value of `key` is more than or equal to the size of the queried sequence. + If not, a [`fkyaml::out_of_range`](../exception/out_of_range.md) will be thrown. +* For mapping nodes + * Whether a given key exists in the target container. + If not, [`fkyaml::out_of_range`](../exception/out_of_range.md) will be thrown. + +This function therefore costs a bit more than [`operator[]`](operator[].md) due to the above extra checks. -Accesses to an element in the YAML sequence/mapping node with the given key object of a compatible type with the [`basic_node`](index.md) class, i.e., a type with which a [`basic_node`](index.md) object is constructible. -These overloads internally construct a [`basic_node`](index.md) object with `key`. +## **Template Parameters** +***KeyType*** +: A compatible key type. + +***BasicNodeType*** +: A basic_node template instance type. + +## **Parameters** -### **Parameters** +***`key`*** [in] +: A key to a target element in the sequence/mapping node. -***`index`*** [in] -: An index/key for an element in the YAML sequence/mapping node. +## **Return Value** -### **Return Value** +(Constant) reference to the node value which is associated with the given key. -Reference, or constant reference, to the YAML node object associated with the given index/key. +## **Examples** -???+ Example +??? Example "Access an element with compatible keys" ```cpp --8<-- "examples/ex_basic_node_at_compatible_type.cpp:9" @@ -84,37 +68,7 @@ Reference, or constant reference, to the YAML node object associated with the gi --8<-- "examples/ex_basic_node_at_compatible_type.output" ``` -## Overload (3), (4) - -```cpp -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -basic_node& at(KeyType&& key); // (3) - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -const basic_node& at(KeyType&& key) const; // (4) -``` - -Accesses to an element in the YAML sequence/mapping node with the given [`basic_node`](index.md) key object. -Unlike the overloads (1) and (2) above, these overloads do not internally construct a [`basic_node`](index.md) object. -So, these overloads works more effectively when some key objects are used multiple times, for instance, in a for-loop. - -### **Template Parameters** - -***KeyType*** -: A key type which is a kind of the [`basic_node`](index.md) template class. - -### **Parameters** - -***`key`*** [in] -: An index/key for an element in the YAML sequence/mapping node. - -### **Return Value** - -Reference, or constant reference, to the YAML node object associated with the given index/key. - -???+ Example +??? Example "Access an element with `basic_node` keys" ```cpp --8<-- "examples/ex_basic_node_at_basic_node.cpp:9" @@ -128,8 +82,6 @@ Reference, or constant reference, to the YAML node object associated with the gi ## **See Also** * [basic_node](index.md) -* [size](size.md) -* [contains](contains.md) * [operator[]](operator[].md) * [operator<<](insertion_operator.md) * [out_of_range](../exception/out_of_range.md) diff --git a/docs/mkdocs/docs/api/basic_node/begin.md b/docs/mkdocs/docs/api/basic_node/begin.md index 5c71383b..376aac37 100644 --- a/docs/mkdocs/docs/api/basic_node/begin.md +++ b/docs/mkdocs/docs/api/basic_node/begin.md @@ -8,16 +8,18 @@ const_iterator begin() const; const_iterator cbegin() const; ``` -Returns an iterator to the first element of a container node. -Throws a [`fkyaml::type_error`](../exception/type_error.md) if a basic_node is neither a sequence nor mapping node. +Returns a (constant) iterator to the first element of a container node. +If a basic_node is neither a sequence nor mapping, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. ![Image from https://en.cppreference.com/w/cpp/iterator/begin](../../img/range-begin-end.svg) -### **Return Value** +## **Return Value** -An iterator to the first element of a container node. +A (constant) iterator to the first element of a container node. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_begin.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/boolean_type.md b/docs/mkdocs/docs/api/basic_node/boolean_type.md index d22eead8..dd38164b 100644 --- a/docs/mkdocs/docs/api/basic_node/boolean_type.md +++ b/docs/mkdocs/docs/api/basic_node/boolean_type.md @@ -6,17 +6,19 @@ using boolean_type = BooleanType; ``` -The type used to store boolean node values. +The type used to store boolean values. The YAML specification describes a boolean as a type which differentiates the following literals: * true, True, TRUE -> `true` * false, False, FALSE -> `false` -To store boolean objects in [`basic_node`](index.md) class, the type is defined by the template parameter `BooleanType` which chooses the type to use for boolean objects. -If not explicitly specified, the default type `bool` will be chosen. -With the decided type, boolean objects are stored directly inside a [`basic_node`](index.md). +The actual type is defined by the template parameter `BooleanType`. +If not explicitly specified, the default type `bool` is defined. +With the decided type, boolean values are stored directly inside a [`basic_node`](index.md). -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_boolean_type.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/constructor.md b/docs/mkdocs/docs/api/basic_node/constructor.md index b9f42a3e..bc2ca0e7 100644 --- a/docs/mkdocs/docs/api/basic_node/constructor.md +++ b/docs/mkdocs/docs/api/basic_node/constructor.md @@ -13,36 +13,108 @@ basic_node(const basic_node& rhs); // (4) basic_node(basic_node&& rhs) noexcept; // (5) -template < - typename CompatibleType, typename U = detail::remove_cv_ref_t, - detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::disjunction>>::value, - int> = 0> +template > basic_node(CompatibleType&& val) noexcept( noexcept(ConverterType::to_node(std::declval(), std::declval()))); // (6) -template < - typename NodeRefStorageType, - detail::enable_if_t::value, int> = 0> -basic_node(const NodeRefStorageType& node_ref_storage) noexcept; // (7) - -basic_node(initializer_list_t init); // (8) +basic_node(initializer_list_t init); // (7) ``` Constructs a new basic_node from a variety of data sources. -Available overloads are described down below. +Available overloads are: + +1. Constructs a basic_node with a null value. + The resulting basic_node has the [`node_type::NULL_OBJECT`](../node_type.md) type. +2. Constructs a basic_node with the given type. + The resulting basic_node has a default value for the given type. + + | `type` | default value | + | --------------------- | ---------------- | + | node_type::SEQUENCE | (empty sequence) | + | node_type::MAPPING | (empty mapping) | + | node_type::NULL_VALUE | `#!cpp nullptr` | + | node_type::BOOLEAN | `#!cpp false` | + | node_type::INTEGER | `#!cpp 0` | + | node_type::FLOAT | `#!cpp 0.0` | + | node_type::STRING | (empty string) | + +3. Constructs a basic_node with the given type. + The resulting basic_node has a default value for the given type. + Default values are the same as those in the above table. + + !!! warning "Deprecation" + + The overload(2) `#!cpp basic_node(const node_type);` replaces the overload(3) `#!cpp basic_node(const node_t);` which has been deprecated in version 0.3.12. It will be removed in a future version. Please replace calls like + + ```cpp + fkyaml::node n(fkyaml::node::node_t::MAPPING); + ``` + + with + + ```cpp + fkyaml::node n(fkyaml::node_type::MAPPING); + ``` + +4. Copy constructs a basic_node with an existing basic_node. +5. Move constructs a basic_node with an existing basic_node. + The existing basic_node will be the same as a default-constructed basic_node at the end of this constructor. +6. Constructs a basic_node with a value of a compatible type (see below). + The resulting basic_node has the value of `val` and the type which is associated with `CompatibleType`. + Template parameter `CompatibleType` includes, but not limited to, the following types: + * sequences: + * [`sequence_type`](sequence_type.md) + * mappings + * [`mapping_type`](mapping_type.md) + * null + * [`std::nullptr_t`](https://en.cppreference.com/w/cpp/types/nullptr_t) + * booleans + * [`boolean_type`](boolean_type.md) + * integers + * [`integer_type`](integer_type.md) + * all integral types except `bool` such as `int`, `uint32_t` or `size_t`. + * floating point values + * [`float_number_type`](float_number_type.md) + * `float`, `double` or `long double` + * strings + * [`string_type`](string_type.md) + * types with which [`string_type`](string_type.md) is constructible such as `char[]`, `char*` or [`std::string_view`](https://en.cppreference.com/w/cpp/string/basic_string_view) (since C++17) + + You can add types to meet your needs by implementing custom `to_node()` functions. See [`node_value_converter`](../node_value_converter/to_node.md) for details. +7. Constructs a basic_node with a initializer_list_t object. + The resulting basic_node has the value of a container (sequence or mapping) which has the contents of `init`. + Basically, `init` is considered to be a sequence. + If `init` contains a sequence where each element contains 2 basic_node objects, however, such a sequence is interpreted as a mapping. + + !!! Note "initializer lists which have a single element" + + `#!cpp fkyaml::node n {true};` will create a sequence of 1 boolean value, not a boolean value alone. This is because [overload resolution in C++ prioritizes a constructor with a single initializer list argument is prioritized to the others](https://en.cppreference.com/w/cpp/language/overload_resolution). In such cases, change the code to `#! fkyaml::node n(true);` instead. + +## **Template Parameters** + +***CompatibleType*** +: A type such that `ConverterType` has a `to_node` function. + +***U*** +: A type referred to by `ValueType` with its topmost cv-qualifiers removed. + +## **Parameters** -## Overload (1) +***`type`*** [in] +: the type of the value to create -```cpp -basic_node() = default; -``` -Default constructor. Constructs a basic_node with a null value. -The resulting basic_node has the [`node_t::NULL_OBJECT`](node_t.md) type. +***`rhs`*** [in] +: the basic_node object to copy/move the value from -???+ Example +***`val`*** [in] +: the value of a compatible type. + +***`init`*** [in] +: initializer list of basic_node objects + +## **Examples** + +??? Example "Overload(1): create a default value" ```cpp --8<-- "examples/ex_basic_node_constructor_1.cpp:9" @@ -53,20 +125,7 @@ The resulting basic_node has the [`node_t::NULL_OBJECT`](node_t.md) type. --8<-- "examples/ex_basic_node_constructor_1.output" ``` -## Overload (2) - -```cpp -explicit basic_node(const node_type type); -``` -Constructs a basic_node with the given type. -The resulting basic_node has a default value for the given type. - -### **Parameters** - -***`type`*** [in] -: A YAML node type. - -???+ Example +??? Example "Overload(2): create an empty value with a given type" ```cpp --8<-- "examples/ex_basic_node_constructor_2.cpp:9" @@ -77,35 +136,7 @@ The resulting basic_node has a default value for the given type. --8<-- "examples/ex_basic_node_constructor_2.output" ``` -## Overload (3) - -```cpp -explicit basic_node(const node_t type); -``` - -!!! warning "Deprecation" - - The constructor `#!cpp basic_node(const node_type)` replaces the constructor `#!cpp basic_node(const node_t)` which has been deprecated in version 0.3.12. It will be removed in version 0.4.0. Please replace calls like - - ```cpp - fkyaml::node n(fkyaml::node::node_t::MAPPING); - ``` - - with - - ```cpp - fkyaml::node n(fkyaml::node_type::MAPPING); - ``` - -Constructs a basic_node with the given type. -The resulting basic_node has a default value for the given type. - -### **Parameters** - -***`type`*** [in] -: A YAML node type. - -???+ Example +??? Example "Overload(3): create an empty value with a given type (deprecated)" ```cpp --8<-- "examples/ex_basic_node_constructor_3.cpp:9" @@ -116,20 +147,7 @@ The resulting basic_node has a default value for the given type. --8<-- "examples/ex_basic_node_constructor_3.output" ``` -## Overload (4) - -```cpp -basic_node(const basic_node& rhs); -``` -Copy constructor. Copies the internal data of `rhs` into the resulting basic_node. -The resulting basic_node has the same type and value as `rhs`. - -### **Parameters** - -***`rhs`*** [in] -: A basic_node object to be copied with. - -???+ Example +??? Example "Overload(4): copy construct a basic_node object" ```cpp --8<-- "examples/ex_basic_node_constructor_4.cpp:9" @@ -140,21 +158,7 @@ The resulting basic_node has the same type and value as `rhs`. --8<-- "examples/ex_basic_node_constructor_4.output" ``` -## Overload (5) - -```cpp -basic_node(basic_node&& rhs) noexcept; -``` -Move constructor. Move the internal data of `rhs` into the resulting basic_node. -The resulting basic_node has the same type and value as `rhs`. -The value of the argument `rhs` after calling this move constructor, will be the same as a default-constructed basic_node. - -### **Parameters** - -***`rhs`*** [in] -: A basic_node object to be moved from. - -???+ Example +??? Example "Overload(5): move construct a basic_node object" ```cpp --8<-- "examples/ex_basic_node_constructor_5.cpp:9" @@ -165,36 +169,7 @@ The value of the argument `rhs` after calling this move constructor, will be the --8<-- "examples/ex_basic_node_constructor_5.output" ``` -## Overload (6) - -```cpp -template < - typename CompatibleType, typename U = detail::remove_cv_ref_t, - detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::disjunction>>::value, - int> = 0> -basic_node(CompatibleType&& val) noexcept( - noexcept(ConverterType::to_node(std::declval(), std::declval()))); // (5) -``` -Constructs a basic_node with a value of a compatible type. -The resulting basic_node has the value of `val` and the type which is associated with `CompatibleType`. - -### **Template Parameters** - -***`CompatibleType`*** -: Type of native data which is compatible with node values. - -***`U`*** -: Type of compatible native data without cv-qualifiers and reference. - -### **Parameters** - -***`val`*** [in] -: The value of a compatible type. - -???+ Example +??? Example "Overload(6): create a basic_node object with compatible types" ```cpp --8<-- "examples/ex_basic_node_constructor_6.cpp:9" @@ -205,34 +180,7 @@ The resulting basic_node has the value of `val` and the type which is associated --8<-- "examples/ex_basic_node_constructor_6.output" ``` -## Overload (7) - -```cpp -template < - typename NodeRefStorageType, - detail::enable_if_t::value, int> = 0> -basic_node(const NodeRefStorageType& node_ref_storage) noexcept; -``` -Constructs a basic_node with a node_ref_storage. -The resulting basic_node has the value of the referenced basic_node by `node_ref_storage`. - -!!! Warning - - This constructor is mainly for the one with std::initializer_list, and the argument type is too detailed to be used from outside the fkYAML library. - So, this overload might become unavailable in the future major version. - Please refrain from intentionally using this overload, and use the overload with std::initializer_list instead. - -### **Template Parameters** - -***`NodeRefStorageType`*** -: Type of basic_node with reference. - -### **Parameters** - -***`node_ref_storage`*** [in] -: A node_ref_storage template class object. - -???+ Example +??? Example "Overload(7): create a basic_node object from an initializer list" ```cpp --8<-- "examples/ex_basic_node_constructor_7.cpp:9" @@ -242,32 +190,6 @@ The resulting basic_node has the value of the referenced basic_node by `node_ref ```bash --8<-- "examples/ex_basic_node_constructor_7.output" ``` - -## Overload (8) - -```cpp -basic_node(initializer_list_t init); -``` -Constructs a basic_node with a initializer_list_t object. -The resulting basic_node has the value of a container (sequence or mapping) which has the contents of `init`. -Basically, the basic_node objects in `init` are considered as a sequence node. -If `init` contains a sequence of basic_node objects in which the number of basic_node objects is 2 and the first has the type of `node_t::STRING`, however, such a sequence is reinterpreted as a mapping node. - -### **Parameters** - -***`init`*** [in] -: A initializer list of basic_node objects. - -???+ Example - - ```cpp - --8<-- "examples/ex_basic_node_constructor_8.cpp:9" - ``` - - output: - ```bash - --8<-- "examples/ex_basic_node_constructor_8.output" - ``` --- ## **See Also** diff --git a/docs/mkdocs/docs/api/basic_node/contains.md b/docs/mkdocs/docs/api/basic_node/contains.md index 662bd0dc..1f04a430 100644 --- a/docs/mkdocs/docs/api/basic_node/contains.md +++ b/docs/mkdocs/docs/api/basic_node/contains.md @@ -3,38 +3,38 @@ # fkyaml::basic_node::contains ```cpp -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>>, - detail::is_node_compatible_type>>::value, - int> = 0> -bool contains(KeyType&& key) const; // (1) A compatible key object with basic_node type - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -bool contains(KeyType&& key) const; // (2) A basic_node object +template +bool contains(KeyType&& key) const; // (1) + +template +bool contains(BasicNodeType&& key) const; // (2) ``` -Checks if the YAML node has the given key. -If the node value is not a mapping, this API will throw an [`fkyaml::type_error`](../exception/type_error.md). -The `KeyType` can be a compatible type with [`fkyaml::basic_node`](index.md) or a kind of [`fkyaml::basic_node`](index.md) template class. +Checks if the YAML node has the given key in the queried mapping. +If the node value is not a mapping, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. + +The input parameter `key` must be either a [`basic_node`](index.md) obejct or an object of a compatible type, i.e., a type with which a [`basic_node`](index.md) object can be constructible. +Note that the overload (1) internally constructs a temporal [`basic_node`](index.md) object. +So, if you use the same key multiple times, for example, in a for loop, consider creating a [`basic_node`](index.md) as a key first for better performance. ## **Template Parameters** ***KeyType*** -: A type which is compatible with or a kind of [`fkyaml::basic_node`](index.md). +: A type with which a [`basic_node`](index.md) object can be constructible. + +***BasicNodeType*** +: A basic_node template instance type. ## **Parameters** ***`key`*** [in] -: A key to the target value in the YAML mapping node value. +: A key to check existence in the queried mapping. ## **Return Value** -`true` if the YAML node is a mapping and has the given key, `false` otherwise. +`true` if the key exists in the queried mapping, `false` otherwise. -???+ Example +??? Example ```cpp --8<-- "examples/ex_basic_node_contains.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/deserialize.md b/docs/mkdocs/docs/api/basic_node/deserialize.md index 599a644e..c81cea62 100644 --- a/docs/mkdocs/docs/api/basic_node/deserialize.md +++ b/docs/mkdocs/docs/api/basic_node/deserialize.md @@ -7,74 +7,58 @@ template static basic_node deserialize(InputType&& input); // (1) template -static basic_node deserialize(ItrType&& begin, ItrType&& end); // (2) +static basic_node deserialize(ItrType begin, ItrType end); // (2) ``` Deserializes from compatible inputs. Note that this function deserializes only the first YAML document in the given input and ignore the rest. -Use this function when the input consists of a single YAML document or only the first one needs to be deserialized. +Use this function when the input consists of a single YAML document or only the first needs to be deserialized. Otherwise, use the [`deserialize_docs()`](deserialize_docs.md) function instead. Throws a [`fkyaml::exception`](../exception/index.md) if the deserialization process detects an error from the input. !!! note "Supported Unicode Encodings" fkYAML supports UTF-8, UTF-16 and UTF-32 encodings for input characters. - As the YAML specification shows [(here)](https://yaml.org/spec/1.2.2/#52-character-encodings), all input streams must begin with either a byte order mark(BOM) or an ASCII character, which will allow the encoding to be deduced by the pattern of the first few bytes of the input sequence. - If an input fails to meet the above requirement, the input is interpreted as a UTF-8 encoded character sequence starting without a BOM. - If a stream with `char` as a character type is used (including FILE pointers), the encoding will be automatically detected in the deserialization process, while an array/container of `char16_t` and `char32_t` denotes that its contents are encoded in the UTF-16BE/LE and UTF-32BE/LE format, respectively. - Furthermore, a byte order mark (BOM) can be put only at the beginning of an input sequence. - The deserialization process internally converts input characters into the UTF-8 encoded ones if they are encoded in the UTF-16 or UTF-32 format. + As the YAML specification shows [here](https://yaml.org/spec/1.2.2/#52-character-encodings), all input streams must begin with either a byte order mark(BOM) or an ASCII character, which will allow the encoding to be deduced by the pattern of the first few bytes. + If an input does not start either of them, the input is considered to be encoded in the UTF-8 encoding starting with no BOM. + Furthermore, allowed encoding types differ depending on the type of input characters. If a deduced encoding type is not allowed for the type, a [fkyaml::exception] will be thrown. -!!! note "Supported newline codes" + | type | allowed encodings | + | ---------------------------------------------------------------------------- | --------------------- | + | [`char`](https://en.cppreference.com/w/cpp/keyword/char) | UTF-8, UTF-16, UTF-32 | + | [`char8_t`](https://en.cppreference.com/w/cpp/keyword/char8_t) (since C++20) | UTF-8 | + | [`char16_t`](https://en.cppreference.com/w/cpp/keyword/char16_t) | UTF-16 | + | [`char32_t`](https://en.cppreference.com/w/cpp/keyword/char32_t) | UTF-32 | - fkYAML supports LF (Unix style) and CR+LF (Windows style) as line break formats. - Inside the deserialization processes, however, fkYAML normalizes them into line feeds (LF, `0x0A`) just as described in the YAML specification (see the ["5.4. Line Break Characters"](https://yaml.org/spec/1.2.2/#54-line-break-characters) section). - Currently, there is no way to restore the original line break style in the serialization processes. - -## Overload (1) +!!! note "Supported line break formats" -```cpp -template -static basic_node deserialize(InputType&& input); -``` + fkYAML supports LF (Unix style) and CR+LF (Windows style) as line break formats. + Inside the deserialization processes, fkYAML normalizes them into line feeds (LF, `0x0A`). + In other words, if an input uses the Windows style as its line break format, there happens a copy of the input contents. So, the Unix style is recommended for better performance. + Currently, there is no way to restore the original line break style. -### **Template Parameters** +## **Template Parameters** ***`InputType`*** -: Type of a compatible input, for instance: +: the type of a compatible input, for instance: * an `std::istream` object * a `FILE` pointer (must not be `nullptr`) * a C-style array of characters (`char`, `char16_t` or `char32_t`. See the "Supported Unicode Encodings" above.) * char[N], char16_t[N], or char32_t[N] (N is the size of an array) - * a container `obj` with which `begin(obj)` and `end(obj)` produces a valid pair of iterators + * a container with which `begin(input)` and `end(input)` produces a valid pair of iterators * std::basic_string, std::array, std::string_view (with C++17 or better) and the likes. -### **Parameters** - -***`input`*** [in] -: An input source in the YAML format. - -### **Return Value** - -The resulting `basic_node` object deserialized from the input source. - -## Overload (2) - -```cpp -template -static basic_node deserialize(ItrType&& begin, ItrType&& end); -``` - -### **Template Parameters** - ***`ItrType`*** : Type of a compatible iterator, for instance: * a pair of iterators such as return values of `std::string::begin()` and `std::string::end()` * a pair of pointers such as `ptr` and `ptr + len` -### **Parameters** +## **Parameters** + +***`input`*** [in] +: An input source such as streams or arrays. ***`begin`*** [in] : An iterator to the first element of an input sequence @@ -82,13 +66,13 @@ static basic_node deserialize(ItrType&& begin, ItrType&& end); ***`end`*** [in] : An iterator to the past-the-last element of an input sequence -### **Return Value** +## **Return Value** -The resulting `basic_node` object deserialized from the pair of iterators. +The resulting `basic_node` object of deserialization. -## Examples +## **Examples** -???+ Example "Example (a character array)" +??? Example "Example (a character array)" ```cpp --8<-- "examples/ex_basic_node_deserialize_char_array.cpp:9" @@ -99,7 +83,7 @@ The resulting `basic_node` object deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_char_array.output" ``` -???+ Example "Example (a std::string object)" +??? Example "Example (a std::string object)" ```cpp --8<-- "examples/ex_basic_node_deserialize_string.cpp:9" @@ -110,7 +94,7 @@ The resulting `basic_node` object deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_string.output" ``` -???+ Example "Example (a FILE pointer)" +??? Example "Example (a FILE pointer)" ```yaml title="input.yaml" --8<-- "examples/input.yaml" @@ -125,7 +109,7 @@ The resulting `basic_node` object deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_file_pointer.output" ``` -???+ Example "Example (a pair of iterators)" +??? Example "Example (a pair of iterators)" ```cpp --8<-- "examples/ex_basic_node_deserialize_iterators.cpp:9" @@ -136,7 +120,7 @@ The resulting `basic_node` object deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_iterators.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [deserialize_docs](deserialize_docs.md) diff --git a/docs/mkdocs/docs/api/basic_node/deserialize_docs.md b/docs/mkdocs/docs/api/basic_node/deserialize_docs.md index d47a8cb0..2e654c1b 100644 --- a/docs/mkdocs/docs/api/basic_node/deserialize_docs.md +++ b/docs/mkdocs/docs/api/basic_node/deserialize_docs.md @@ -13,69 +13,34 @@ static std::vector deserialize_docs(ItrType&& begin, ItrType&& end); Deserializes from compatible inputs. Unlike the [`deserialize()`](deserialize.md) function, this function deserializes all YAML documents in the input into [`fkyaml::basic_node`](index.md) objects. Prefer this function when your input may contain more than one YAML documents and all of them must be processed. -Otherwise, use the [`deserialize()`](deserialize.md) function which is optimized for processing single YAML documents. +Otherwise, use the [`deserialize()`](deserialize.md) function which is optimized for processing a single YAML document. Throws a [`fkyaml::exception`](../exception/index.md) if the deserialization process detects an error from the input. -!!! note "Supported Unicode Encodings" +Since this function shares a large portion of internal implementation with the [`deserialize()`](deserialize.md) function, supported unicode encodings and line break formats are the same. Refer to its documentation for details. - fkYAML supports UTF-8, UTF-16 and UTF-32 encodings for input characters. - As the YAML specification shows [(here)](https://yaml.org/spec/1.2.2/#52-character-encodings), all input streams must begin with either a byte order mark(BOM) or an ASCII character, which will allow the encoding to be deduced by the pattern of the first few bytes of the input sequence. - If an input fails to meet the above requirement, the input is interpreted as a UTF-8 encoded character sequence starting without a BOM. - If a stream with `char` as a character type is used (including FILE pointers), the encoding will be automatically detected in the deserialization process, while an array/container of `char16_t` and `char32_t` denotes that its contents are encoded in the UTF-16BE/LE and UTF-32BE/LE format, respectively. - Furthermore, a byte order mark (BOM) can be put only at the beginning of an input sequence. - The deserialization process internally converts input characters into the UTF-8 encoded ones if they are encoded in the UTF-16 or UTF-32 format. - -!!! note "Supported newline codes" - - fkYAML supports LF (Unix style) and CR+LF (Windows style) as line break formats. - Inside the deserialization processes, however, fkYAML normalizes them into line feeds (LF, `0x0A`) just as described in the YAML specification (see the ["5.4. Line Break Characters"](https://yaml.org/spec/1.2.2/#54-line-break-characters) section). - Currently, there is no way to restore the original line break style in the serialization processes. - -## Overload (1) - -```cpp -template -static std::vector deserialize_docs(InputType&& input); -``` - -### **Template Parameters** +## **Template Parameters** ***`InputType`*** -: Type of a compatible input, for instance: +: the type of a compatible input, for instance: * an `std::istream` object * a `FILE` pointer (must not be `nullptr`) * a C-style array of characters (`char`, `char16_t` or `char32_t`. See the "Supported Unicode Encodings" above.) * char[N], char16_t[N], or char32_t[N] (N is the size of an array) - * a container `obj` with which `begin(obj)` and `end(obj)` produces a valid pair of iterators + * a container with which `begin(input)` and `end(input)` produces a valid pair of iterators * std::basic_string, std::array, std::string_view (with C++17 or better) and the likes. -### **Parameters** - -***`input`*** [in] -: An input source in the YAML format. - -### **Return Value** - -The resulting `basic_node` objects deserialized from the input source. - -## Overload (2) - -```cpp -template -static std::vector deserialize_docs(ItrType&& begin, ItrType&& end); -``` - -### **Template Parameters** - ***`ItrType`*** : Type of a compatible iterator, for instance: * a pair of iterators such as return values of `std::string::begin()` and `std::string::end()` * a pair of pointers such as `ptr` and `ptr + len` -### **Parameters** +## **Parameters** + +***`input`*** [in] +: An input source such as streams or arrays. ***`begin`*** [in] : An iterator to the first element of an input sequence @@ -83,13 +48,13 @@ static std::vector deserialize_docs(ItrType&& begin, ItrType&& end); ***`end`*** [in] : An iterator to the past-the-last element of an input sequence -### **Return Value** +## **Return Value** -The resulting `basic_node` objects deserialized from the pair of iterators. +The resulting `basic_node` objects of deserialization. -## Examples +## **Examples** -???+ Example "Example (a character array)" +??? Example "Example (a character array)" ```cpp --8<-- "examples/ex_basic_node_deserialize_docs_char_array.cpp:9" @@ -100,7 +65,7 @@ The resulting `basic_node` objects deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_docs_char_array.output" ``` -???+ Example "Example (a std::string object)" +??? Example "Example (a std::string object)" ```cpp --8<-- "examples/ex_basic_node_deserialize_docs_string.cpp:9" @@ -111,7 +76,7 @@ The resulting `basic_node` objects deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_docs_string.output" ``` -???+ Example "Example (a FILE pointer)" +??? Example "Example (a FILE pointer)" ```yaml title="input_multi.yaml" --8<-- "examples/input_multi.yaml" @@ -126,7 +91,7 @@ The resulting `basic_node` objects deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_docs_file_pointer.output" ``` -???+ Example "Example (a pair of iterators)" +??? Example "Example (a pair of iterators)" ```cpp --8<-- "examples/ex_basic_node_deserialize_docs_iterators.cpp:9" @@ -137,7 +102,7 @@ The resulting `basic_node` objects deserialized from the pair of iterators. --8<-- "examples/ex_basic_node_deserialize_docs_iterators.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [deserialize](deserialize.md) diff --git a/docs/mkdocs/docs/api/basic_node/empty.md b/docs/mkdocs/docs/api/basic_node/empty.md index 669eb1cf..0b87f302 100644 --- a/docs/mkdocs/docs/api/basic_node/empty.md +++ b/docs/mkdocs/docs/api/basic_node/empty.md @@ -7,13 +7,15 @@ boolean empty() const; ``` Tests whether the node value is empty. -Throws a [`fkyaml::exception`](../exception/index.md) if a basic_node does not have a conatiner nor string value. +If a basic_node is neither a sequence, mapping nor string, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. -### **Return Value** +## **Return Value** `true` if the node value is empty, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_empty.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/end.md b/docs/mkdocs/docs/api/basic_node/end.md index 1b966468..c5a6996f 100644 --- a/docs/mkdocs/docs/api/basic_node/end.md +++ b/docs/mkdocs/docs/api/basic_node/end.md @@ -8,16 +8,18 @@ const_iterator end() const; const_iterator cend() const; ``` -Returns an iterator to the past-the-last element of a container node. -Throws a [`fkyaml::type_error`](../exception/type_error.md) if a basic_node is neither a sequence nor mapping node. +Returns a (constant) iterator to the past-the-last element of a container node. +If a basic_node is neither a sequence nor mapping, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. ![Image from https://en.cppreference.com/w/cpp/iterator/end](../../img/range-begin-end.svg) -### **Return Value** +## **Return Value** -An iterator to the past-the-last element of a container node. +A (constant) iterator to the past-the-last element of a container node. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_end.cpp:9" @@ -28,7 +30,7 @@ An iterator to the past-the-last element of a container node. --8<-- "examples/ex_basic_node_end.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [node](node.md) diff --git a/docs/mkdocs/docs/api/basic_node/extraction_operator.md b/docs/mkdocs/docs/api/basic_node/extraction_operator.md index a4282c4c..ef0a57e3 100644 --- a/docs/mkdocs/docs/api/basic_node/extraction_operator.md +++ b/docs/mkdocs/docs/api/basic_node/extraction_operator.md @@ -23,7 +23,9 @@ Note that the contents of the input stream must be encoded in either the UTF-8, Reference to the input stream object `is`. -???+ Example +## **Examples** + +??? Example ```yaml --8<-- "examples/input.yaml" @@ -38,7 +40,7 @@ Reference to the input stream object `is`. --8<-- "examples/ex_basic_node_extraction_operator.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [deserialize](deserialize.md) diff --git a/docs/mkdocs/docs/api/basic_node/float_number_type.md b/docs/mkdocs/docs/api/basic_node/float_number_type.md index f1654e83..f3b17221 100644 --- a/docs/mkdocs/docs/api/basic_node/float_number_type.md +++ b/docs/mkdocs/docs/api/basic_node/float_number_type.md @@ -6,17 +6,20 @@ using float_number_type = FloatNumberType; ``` -The type used to store boolean node values. -The YAML specification describes a floating point number as a type which differentiates the following literals: +The type used to store floating point values. +The YAML specification describes a floating point value as a type which differentiates the following literals: -* .inf, .Inf, .INF -> an infinite number -* .nan, .NaN, .NAN -> Not a Number +* real numbers (with scientific notation) → a floating point value +* (+/-).inf, (+/-).Inf, (+/-).INF → the positive/negative infinity +* .nan, .NaN, .NAN → Not a Number -To store floating point number objects in [`basic_node`](index.md) class, the type is defined by the template parameter `FloatNumberType` which chooses the type to use for floating point number objects. -If not explicitly specified, the default type `double` will be chosen. -With the decided type, floating point number objects are stored directly inside a [`basic_node`](index.md). +The actual type is defined by the template parameter `FloatNumberType`. +If not explicitly specified, the default type `double` is defined. +With the decided type, floating point values are stored directly inside a [`basic_node`](index.md). -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_float_number_type.cpp:9" @@ -27,6 +30,6 @@ With the decided type, floating point number objects are stored directly inside --8<-- "examples/ex_basic_node_float_number_type.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) diff --git a/docs/mkdocs/docs/api/basic_node/get_anchor_name.md b/docs/mkdocs/docs/api/basic_node/get_anchor_name.md index 58cbc669..ed8f5e04 100644 --- a/docs/mkdocs/docs/api/basic_node/get_anchor_name.md +++ b/docs/mkdocs/docs/api/basic_node/get_anchor_name.md @@ -6,16 +6,18 @@ const std::string& get_anchor_name() const; ``` -Gets the anchor name associated with the YAML node. -Some anchor name must be set before calling this API. -Calling [`has_anchor_name`](has_anchor_name.md) to see if the node has any anchor name beforehand. +Gets an anchor name associated with the YAML node. +Some anchor name must be set before calling this function. +Call [`has_anchor_name`](has_anchor_name.md) to see if the node has any anchor name beforehand. +If no anchor name has been set, an [`fkyaml::exception`](../exception/index.md) will be thrown. ## **Return Value** The anchor name associated to the node. -If no anchor name has been set, an [`fkyaml::exception`](../exception/index.md) will be thrown. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_anchor_name.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/get_tag_name.md b/docs/mkdocs/docs/api/basic_node/get_tag_name.md index 101f9704..0a50e048 100644 --- a/docs/mkdocs/docs/api/basic_node/get_tag_name.md +++ b/docs/mkdocs/docs/api/basic_node/get_tag_name.md @@ -6,16 +6,18 @@ const std::string& get_tag_name() const; ``` -Gets the tag name associated to the YAML node. +Gets a tag name associated to the YAML node. Some tag name must be set before calling this API. -Calling [`has_tag_name`](has_tag_name.md) to see if the node has any tag name beforehand. +Call [`has_tag_name`](has_tag_name.md) to see if the node has any tag name beforehand. +If no tag name has been set, an [`fkyaml::exception`](../exception/index.md) will be thrown. ## **Return Value** The tag name associated to the node. -If no tag name has been set, an [`fkyaml::exception`](../exception/index.md) will be thrown. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_tag_name.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/get_type.md b/docs/mkdocs/docs/api/basic_node/get_type.md index b8ad5cd2..8f092523 100644 --- a/docs/mkdocs/docs/api/basic_node/get_type.md +++ b/docs/mkdocs/docs/api/basic_node/get_type.md @@ -6,9 +6,9 @@ node_type get_type() const noexcept; ``` -Returns the type of the YAML node value as a value from the [`node_type`](../node_type.md) enumeration. +Returns the type of the node value. -### **Return Value** +## **Return Value** The type of the YAML node value. @@ -22,7 +22,9 @@ The type of the YAML node value. | floating point number | node_type::FLOAT | | string | node_type::STRING | -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_type.cpp:9" @@ -33,6 +35,6 @@ The type of the YAML node value. --8<-- "examples/ex_basic_node_get_type.output" ``` -### **See Also** +## **See Also** * [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/get_value.md b/docs/mkdocs/docs/api/basic_node/get_value.md index 145f4df2..2cf9930c 100644 --- a/docs/mkdocs/docs/api/basic_node/get_value.md +++ b/docs/mkdocs/docs/api/basic_node/get_value.md @@ -32,7 +32,7 @@ This function converts a [`fkyaml::basic_node`](./index.md) to either Actual conversions rely on the [`node_value_converter`](../node_value_converter/index.md)::[`from_node`](../node_value_converter/from_node.md) function. This API makes a copy of the value, and if the copying costs too much, or if you need an address of the original value, then you should call [`get_value_ref`](get_value_ref.md) instead. -???+ Note "Convert from a Sequence Node" +??? Note "Convert from a Sequence Node" This library implements conversions from a sequence node to a number of STL container types whose element type is not a key-value pair. The implementation can be used for custom container types, but they need to have both `iterator` member type and `insert()` member function. The test suite confirms successful conversions to the following types. @@ -59,7 +59,7 @@ This API makes a copy of the value, and if the copying costs too much, or if you Note that the above types cannot be converted from a non-sequence node, which results in throwing a [type_error](../exception/type_error.md). -???+ Note "Convert from a Mapping Node" +??? Note "Convert from a Mapping Node" This library implements conversions from a mapping node to STL container types whose element type is a key-value pair. The implementation can be used for custom container types, but they need to have `key_type`, `mapped_type` and `value_type` member types and `emplace()` member function. The test suite confirms successful conversions to the following types. @@ -70,7 +70,7 @@ This API makes a copy of the value, and if the copying costs too much, or if you * [std::unordered_map](https://en.cppreference.com/w/cpp/container/unordered_map) * [std::unordered_multi_map](https://en.cppreference.com/w/cpp/container/unordered_multimap) *(unordered associative containers for key-value pairs)* -???+ Note "Convert from a Null or Numeric Scalar Node" +??? Note "Convert from a Null or Numeric Scalar Node" If the YAML node value is a null, boolean, integer or floating point, this function internally executes type conversion according to the following rules which all depend on the template paramter type `T`: @@ -90,14 +90,14 @@ This API makes a copy of the value, and if the copying costs too much, or if you Note that those scalar type cannot be converted to a sequence, mapping, string scalar, which results in throwing a [`type_error`](../exception/type_error.md). -???+ Note "Convert from a String Scalar Node" +??? Note "Convert from a String Scalar Node" String scalar nodes can be converted to STL container types which can be constructible from `const fkyaml::basic_node::string_type&` (`const std::string&` by default). The test suite confirms successful conversions to the following types. * [std::string](https://en.cppreference.com/w/cpp/string/basic_string) * [std::string_view](https://en.cppreference.com/w/cpp/string/basic_string_view) (from C++17) -???+ Note "Convert as an optional value" +??? Note "Convert as an optional value" Since C++17, [std::optional](https://en.cppreference.com/w/cpp/utility/optional) can be used as `ValueType` to indicate the conversion result to be optional. In such cases, a returned [std::optional](https://en.cppreference.com/w/cpp/utility/optional) value contains a value only if the conversion was successful, or [`std::nullopt`](https://en.cppreference.com/w/cpp/utility/optional/nullopt) otherwise. @@ -118,7 +118,9 @@ This API makes a copy of the value, and if the copying costs too much, or if you A compatible native data value converted from the [basic_node](./index.md) object. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_value.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/get_value_inplace.md b/docs/mkdocs/docs/api/basic_node/get_value_inplace.md index b2aa4f96..9d010f2c 100644 --- a/docs/mkdocs/docs/api/basic_node/get_value_inplace.md +++ b/docs/mkdocs/docs/api/basic_node/get_value_inplace.md @@ -29,7 +29,7 @@ This function shares internal implementation with the [`get_value`](./get_value. Thus, all the STL container & scalar types which are supported by that function, is also supported by this function as well. See the notes there for details. -???+ Note "Difference from `get_value()`" +??? Note "Difference from `get_value()`" One crutial difference from the [`get_value`](./get_value.md) function is, this function does not require the template parameter type `T` to be [default-constructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible) since no instantiation of `T` is necessary inside the function to return the conversion result anymore. So, you might prefer this function, for example, if you already created a `T` object as a member variable and want to assign a node value to it. @@ -45,7 +45,14 @@ See the notes there for details. ***BasicNodeType*** : A basic_node template instance type. -???+ Example +### **Parameters** + +***`value_ref`*** [out] +: A storage into which the conversion result is filled. + +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_value_inplace.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/get_value_ref.md b/docs/mkdocs/docs/api/basic_node/get_value_ref.md index 9a8142e1..76ec2cc5 100644 --- a/docs/mkdocs/docs/api/basic_node/get_value_ref.md +++ b/docs/mkdocs/docs/api/basic_node/get_value_ref.md @@ -3,38 +3,40 @@ # fkyaml::basic_node::get_value_ref ```cpp -template ::value, int> = 0> -ReferenceType get_value_ref() const noexcept( - noexcept(ConverterType::from_node(std::declval(), std::declval()))); - -template < - typename ReferenceType, - detail::enable_if_t< - detail::conjunction< - std::is_reference, std::is_const>>::value, - int> = 0> +template +ReferenceType get_value_ref(); + +template ReferenceType get_value_ref() const; ``` Explicit reference access to the internally stored YAML node value. -This API makes no copies. +If the requested reference type does not match the current node value, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. + +!!! Note + + If this function throws an exception, the internally stored YAML node value stays intact. ## **Template Parameters** ***ReferenceType*** : reference type to the target YAML node value. - This must be a (const) reference type to [`sequence_type`](sequence_type.md), [`mapping_type`](mapping_type.md), [`boolean_type`](boolean_type.md), [`integer_type`](integer_type.md), [`float_number_type`](float_number_type.md) or [`string_type`](string_type.md). + It must be a (const) reference type to -## **Return Value** + * [`sequence_type`](sequence_type.md) + * [`mapping_type`](mapping_type.md) + * [`boolean_type`](boolean_type.md) + * [`integer_type`](integer_type.md) + * [`float_number_type`](float_number_type.md) + * [`string_type`](string_type.md) -Reference to the internally stored YAML node value if the requested reference type fits to the YAML node value. -A [`fkyaml::exception`](../exception/index.md) would be thrown otherwise. +## **Return Value** -!!! Note +Reference to the internally stored YAML node value. - If this API throws an exception, the internally stored YAML node value stays intact. +## **Examples** -???+ Example +??? Example ```cpp --8<-- "examples/ex_basic_node_get_value_ref.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/get_yaml_version.md b/docs/mkdocs/docs/api/basic_node/get_yaml_version.md index eabc0f9b..b54c0a04 100644 --- a/docs/mkdocs/docs/api/basic_node/get_yaml_version.md +++ b/docs/mkdocs/docs/api/basic_node/get_yaml_version.md @@ -8,7 +8,7 @@ yaml_version_t get_yaml_version() const noexcept; !!! warning "Deprecation" - The function [`#!cpp yaml_version_type get_yaml_version_type()`](set_yaml_version_type.md) replaces the function `#!cpp basic_node::yaml_version_t get_yaml_version()` which has been deprecated in version 0.3.12. It will be removed in version 0.4.0. Please replace calls like + The function [`#!cpp yaml_version_type get_yaml_version_type()`](set_yaml_version_type.md) replaces the function `#!cpp basic_node::yaml_version_t get_yaml_version()` which has been deprecated in version 0.3.12. It will be removed in a future version. Please replace calls like ```cpp fkyaml::node::yaml_version_t v = n.get_yaml_version(); @@ -19,18 +19,20 @@ yaml_version_t get_yaml_version() const noexcept; fkyaml::yaml_version_type v = n.get_yaml_version_type(); ``` -Returns the version of the YAML format applied for the `basic_node` object. +Returns the YAML specification version applied for a `basic_node`. -### **Return Value** +## **Return Value** -The version of the YAML format applied to the basic_node object. +The YAML specification version applied to a basic_node. | YAML version | Return Value | | ------------ | ----------------------- | | 1.1 | yaml_version_t::VER_1_1 | | 1.2 | yaml_version_t::VER_1_2 | -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_yaml_version.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/get_yaml_version_type.md b/docs/mkdocs/docs/api/basic_node/get_yaml_version_type.md index 122e836c..595b72af 100644 --- a/docs/mkdocs/docs/api/basic_node/get_yaml_version_type.md +++ b/docs/mkdocs/docs/api/basic_node/get_yaml_version_type.md @@ -6,18 +6,20 @@ yaml_version_type get_yaml_version_type() const noexcept; ``` -Returns the version of the YAML format applied for the `basic_node` object. +Returns the YAML specification version applied to a `basic_node`. -### **Return Value** +## **Return Value** -The version of the YAML format applied to the basic_node object. +The YAML specification version applied to a basic_node. | YAML version | Return Value | | ------------ | ------------------------------ | | 1.1 | yaml_version_type::VERSION_1_1 | | 1.2 | yaml_version_type::VERSION_1_2 | -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_get_yaml_version_type.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/has_anchor_name.md b/docs/mkdocs/docs/api/basic_node/has_anchor_name.md index d8b4c78c..71821ed4 100644 --- a/docs/mkdocs/docs/api/basic_node/has_anchor_name.md +++ b/docs/mkdocs/docs/api/basic_node/has_anchor_name.md @@ -6,13 +6,15 @@ bool has_anchor_name() const noexcept; ``` -Check if the YAML node has an anchor name. +Check if the node has an anchor name. ## **Return Value** -`true` if the YAML node has an anchor name, `false` otherwise. +`true` if the node has an anchor name, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_has_anchor_name.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/has_tag_name.md b/docs/mkdocs/docs/api/basic_node/has_tag_name.md index a353f36a..b91c32f8 100644 --- a/docs/mkdocs/docs/api/basic_node/has_tag_name.md +++ b/docs/mkdocs/docs/api/basic_node/has_tag_name.md @@ -6,13 +6,15 @@ bool has_tag_name() const noexcept; ``` -Check if the YAML node has a tag name. +Check if the node has a tag name. ## **Return Value** -`true` if the YAML node has a tag name, `false` otherwise. +`true` if the node has a tag name, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_has_tag_name.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/index.md b/docs/mkdocs/docs/api/basic_node/index.md index edce0694..9ae7aa4b 100644 --- a/docs/mkdocs/docs/api/basic_node/index.md +++ b/docs/mkdocs/docs/api/basic_node/index.md @@ -16,7 +16,7 @@ class basic_node; This class provides features to handle YAML nodes. -## Template Paramters +## **Template Paramters** | Template parameter | Description | Default | Derived type | |--------------------|--------------------------------------------------------------|----------------------------------------------------------------------|---------------------------------------------------| @@ -28,11 +28,11 @@ This class provides features to handle YAML nodes. | `StringType` | type for string node values | [std::string](https://en.cppreference.com/w/cpp/string/basic_string) | [`string_type`](string_type.md) | | `ConverterType` | type for converters between
nodes and native data types | [node_value_converter](../node_value_converter/index.md) | [`value_converter_type`](value_converter_type.md) | -## Specializations +## **Specializations** * [node](node.md) - default specialization -## Member Types +## **Member Types** ### Node Value Types | Name | Description | @@ -63,10 +63,11 @@ This class provides features to handle YAML nodes. | Name | Description | | ----------------------------------------------- | ------------------------------------------------------------------- | | [value_converter_type](value_converter_type.md) | The type used to convert between node and native data. | +| initializer_list_t | The type for initializer lists of `basic_node` values. | | [node_t](node_t.md) | **(DEPRECATED)** The type used to store the internal value type. | | [yaml_version_t](yaml_version_t.md) | **(DEPRECATED)** The type used to store the enable version of YAML. | -## Member Functions +## **Member Functions** ### Construction/Destruction | Name | | Description | diff --git a/docs/mkdocs/docs/api/basic_node/insertion_operator.md b/docs/mkdocs/docs/api/basic_node/insertion_operator.md index 33c17103..104973c5 100644 --- a/docs/mkdocs/docs/api/basic_node/insertion_operator.md +++ b/docs/mkdocs/docs/api/basic_node/insertion_operator.md @@ -6,10 +6,9 @@ inline std::ostream& operator<<(std::ostream& os, const basic_node& n); ``` -Extraction operator for basic_node template class. -Serializes YAML node values into an output stream. -This API is a wrapper of [`basic_node::serialize()`](serialize.md) function to simplify the implementation in the client code. -For more detailed descriptions, please visit the reference page for the [`basic_node::serialize()`](serialize.md) function. +Serializes a node value into an output stream. +This operator is a wrapper of the [`basic_node::serialize()`](serialize.md) function to simplify the implementation in the client code. +For details, please visit the documentation of the [`serialize()`](serialize.md) function. ## **Template Parameters** @@ -46,7 +45,9 @@ For more detailed descriptions, please visit the reference page for the [`basic_ Reference to the output stream object `os`. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_insertion_operator.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/integer_type.md b/docs/mkdocs/docs/api/basic_node/integer_type.md index 4e70c810..1e37d4a9 100644 --- a/docs/mkdocs/docs/api/basic_node/integer_type.md +++ b/docs/mkdocs/docs/api/basic_node/integer_type.md @@ -6,13 +6,15 @@ using integer_type = IntegerType; ``` -The type used to store boolean node values. +The type used to store integer values. -To store integer objects in [`basic_node`](index.md) class, the type is defined by the template parameter `IntegerType` which chooses the type to use for integer objects. -If not explicitly specified, the default type `std::int64_t` will be chosen. -With the decided type, integer objects are stored directly inside a [`basic_node`](index.md). +The actual type is defined by the template parameter `IntegerType`. +If not explicitly specified, the default type `std::int64_t` is defined. +With the decided type, integer values are stored directly inside a [`basic_node`](index.md). -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_integer_type.cpp:9" @@ -23,6 +25,6 @@ With the decided type, integer objects are stored directly inside a [`basic_node --8<-- "examples/ex_basic_node_integer_type.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_alias.md b/docs/mkdocs/docs/api/basic_node/is_alias.md index 0c9b215c..6575654b 100644 --- a/docs/mkdocs/docs/api/basic_node/is_alias.md +++ b/docs/mkdocs/docs/api/basic_node/is_alias.md @@ -8,11 +8,13 @@ bool is_alias() const noexcept; Tests whether the node is an alias node. -### **Return Value** +## **Return Value** `true` if the node is an alias node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_alias.cpp:9" @@ -23,7 +25,7 @@ Tests whether the node is an alias node. --8<-- "examples/ex_basic_node_is_alias.output" ``` -### **See Also** +## **See Also** * [add_anchor_name](add_anchor_name.md) * [alias_of](alias_of.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_anchor.md b/docs/mkdocs/docs/api/basic_node/is_anchor.md index 2921ecd0..c7bd8a43 100644 --- a/docs/mkdocs/docs/api/basic_node/is_anchor.md +++ b/docs/mkdocs/docs/api/basic_node/is_anchor.md @@ -8,11 +8,13 @@ bool is_anchor() const noexcept; Tests whether the node is an anchor node. -### **Return Value** +## **Return Value** `true` if the node is an anchor node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_anchor.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node is an anchor node. --8<-- "examples/ex_basic_node_is_anchor.output" ``` -### **See Also** +## **See Also** * [add_anchor_name](add_anchor_name.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_boolean.md b/docs/mkdocs/docs/api/basic_node/is_boolean.md index 492e74a2..afb130ae 100644 --- a/docs/mkdocs/docs/api/basic_node/is_boolean.md +++ b/docs/mkdocs/docs/api/basic_node/is_boolean.md @@ -6,13 +6,15 @@ bool is_boolean() const noexcept; ``` -Tests whether the node value type is [`node_t::BOOLEAN`](node_t.md). +Tests whether the node is a boolean node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::BOOLEAN`](node_t.md), `false` otherwise. +`true` if the node is a boolean node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_boolean.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::BOOLEAN`](node_t.md). --8<-- "examples/ex_basic_node_is_boolean.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_float_number.md b/docs/mkdocs/docs/api/basic_node/is_float_number.md index cccb12d3..c22493a5 100644 --- a/docs/mkdocs/docs/api/basic_node/is_float_number.md +++ b/docs/mkdocs/docs/api/basic_node/is_float_number.md @@ -6,13 +6,15 @@ bool is_float_number() const noexcept; ``` -Tests whether the node value type is [`node_t::FLOAT_NUMBER`](node_t.md). +Tests whether the node is a floating point value node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::FLOAT_NUMBER`](node_t.md), `false` otherwise. +`true` if the node is a floating point value node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_float_number.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::FLOAT_NUMBER`](node_t.md). --8<-- "examples/ex_basic_node_is_float_number.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_integer.md b/docs/mkdocs/docs/api/basic_node/is_integer.md index c18a8bca..c223376f 100644 --- a/docs/mkdocs/docs/api/basic_node/is_integer.md +++ b/docs/mkdocs/docs/api/basic_node/is_integer.md @@ -6,13 +6,15 @@ bool is_integer() const noexcept; ``` -Tests whether the node value type is [`node_t::INTEGER`](node_t.md). +Tests whether the node is an integer node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::INTEGER`](node_t.md), `false` otherwise. +`true` if the node is an integer node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_integer.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::INTEGER`](node_t.md). --8<-- "examples/ex_basic_node_is_integer.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_mapping.md b/docs/mkdocs/docs/api/basic_node/is_mapping.md index ddbd0b54..9658dd6b 100644 --- a/docs/mkdocs/docs/api/basic_node/is_mapping.md +++ b/docs/mkdocs/docs/api/basic_node/is_mapping.md @@ -6,13 +6,15 @@ bool is_mapping() const noexcept; ``` -Tests whether the node value type is [`node_t::MAPPING`](node_t.md). +Tests whether the node is a mapping node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::MAPPING`](node_t.md), `false` otherwise. +`true` if the node is a mapping node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_mapping.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::MAPPING`](node_t.md). --8<-- "examples/ex_basic_node_is_mapping.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_null.md b/docs/mkdocs/docs/api/basic_node/is_null.md index 215c1335..e09fd182 100644 --- a/docs/mkdocs/docs/api/basic_node/is_null.md +++ b/docs/mkdocs/docs/api/basic_node/is_null.md @@ -6,13 +6,15 @@ bool is_null() const noexcept; ``` -Tests whether the node value type is [`node_t::NULL_OBJECT`](node_t.md). +Tests whether the node is a null node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::NULL_OBJECT`](node_t.md), `false` otherwise. +`true` if the node is a null node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_null.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::NULL_OBJECT`](node_t.md). --8<-- "examples/ex_basic_node_is_null.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_scalar.md b/docs/mkdocs/docs/api/basic_node/is_scalar.md index e78f2027..88932f40 100644 --- a/docs/mkdocs/docs/api/basic_node/is_scalar.md +++ b/docs/mkdocs/docs/api/basic_node/is_scalar.md @@ -6,18 +6,15 @@ bool is_scalar() const noexcept; ``` -Tests whether the node value type is one of the followings: -* [`node_t::NULL_OBJECT`](node_t.md) -* [`node_t::BOOLEAN`](node_t.md) -* [`node_t::INTEGER`](node_t.md) -* [`node_t::FLOAT_NUMBER`](node_t.md) -* [`node_t::STRING`](node_t.md) +Tests whether the node is a scalar node: either a null, boolean, integer, floating point or string node. -### **Return Value** +## **Return Value** -`true` if the type is a scalar type, `false` otherwise. +`true` if the node is a scalar node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_scalar.cpp:9" @@ -28,6 +25,6 @@ Tests whether the node value type is one of the followings: --8<-- "examples/ex_basic_node_is_scalar.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_sequence.md b/docs/mkdocs/docs/api/basic_node/is_sequence.md index 108c900d..79765c95 100644 --- a/docs/mkdocs/docs/api/basic_node/is_sequence.md +++ b/docs/mkdocs/docs/api/basic_node/is_sequence.md @@ -6,13 +6,15 @@ bool is_sequence() const noexcept; ``` -Tests whether the node value type is [`node_t::SEQUENCE`](node_t.md). +Tests whether the node is a sequence node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::SEQUENCE`](node_t.md), `false` otherwise. +`true` if the node is a sequence node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_sequence.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::SEQUENCE`](node_t.md). --8<-- "examples/ex_basic_node_is_sequence.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/is_string.md b/docs/mkdocs/docs/api/basic_node/is_string.md index f92c9fd4..3b0b3ebe 100644 --- a/docs/mkdocs/docs/api/basic_node/is_string.md +++ b/docs/mkdocs/docs/api/basic_node/is_string.md @@ -6,13 +6,15 @@ bool is_string() const noexcept; ``` -Tests whether the node value type is [`node_t::STRING`](node_t.md). +Tests whether the node is a string node. -### **Return Value** +## **Return Value** -`true` if the type is [`node_t::STRING`](node_t.md), `false` otherwise. +`true` if the node is a string node, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_is_string.cpp:9" @@ -23,6 +25,6 @@ Tests whether the node value type is [`node_t::STRING`](node_t.md). --8<-- "examples/ex_basic_node_is_string.output" ``` -### **See Also** +## **See Also** -* [node_t](node_t.md) +* [node_type](../node_type.md) diff --git a/docs/mkdocs/docs/api/basic_node/iterator.md b/docs/mkdocs/docs/api/basic_node/iterator.md index 75e3e877..acee0644 100644 --- a/docs/mkdocs/docs/api/basic_node/iterator.md +++ b/docs/mkdocs/docs/api/basic_node/iterator.md @@ -10,7 +10,7 @@ using iterator = detail::iterator; The types of non-const/const iterators for [`basic_node`](index.md) containers. They satisfies [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) and are commonly used for sequence and mapping container nodes. -## Member Types +## **Member Types** * iterator | Type | Definition | @@ -29,14 +29,16 @@ They satisfies [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/n | `difference_type` | [`std::ptrdiff_t`](https://en.cppreference.com/w/cpp/types/ptrdiff_t) | | `iterator_category` | [`std::bidirectional_iterator_tag`](https://en.cppreference.com/w/cpp/iterator/iterator_tags) | -## Member Functions +## **Member Functions** | Name | Description | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | key | Returns const reference to a key node of the current key-value pair.
`fkyaml::exception` is thrown if an iterator points to a sequence element. | | value | Returns reference to a sequence element if an element points to a sequence element, or a mapping value otherwise. | -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_iterator.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/mapping.md b/docs/mkdocs/docs/api/basic_node/mapping.md index 43040cb7..5750d564 100644 --- a/docs/mkdocs/docs/api/basic_node/mapping.md +++ b/docs/mkdocs/docs/api/basic_node/mapping.md @@ -8,11 +8,13 @@ static basic_node mapping(const mapping_type& seq); static basic_node mapping(mapping_type&& seq); ``` -The factory method which constructs a basic_node with the [`node_t::MAPPING`](node_t.md) type from a mapping node value. -Calling this API with no arguments will constructs a basic_node with an empty mapping node value. -The resulting basic_node has the [`node_t::MAPPING`](node_t.md) type. +The factory method which constructs a basic_node with the [`node_type::MAPPING`](../node_type.md) type. +Calling this function with no arguments will constructs a basic_node with an empty mapping node value. +The resulting basic_node has the [`node_type::MAPPING`](../node_type.md) type. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_mapping.cpp:9" @@ -24,8 +26,8 @@ The resulting basic_node has the [`node_t::MAPPING`](node_t.md) type. ``` -### **See Also** +## **See Also** * [basic_node](index.md) -* [node_t](node_t.md) +* [node_type](../node_type.md) * [operator<<](insertion_operator.md) diff --git a/docs/mkdocs/docs/api/basic_node/mapping_type.md b/docs/mkdocs/docs/api/basic_node/mapping_type.md index b8141b67..6e3db014 100644 --- a/docs/mkdocs/docs/api/basic_node/mapping_type.md +++ b/docs/mkdocs/docs/api/basic_node/mapping_type.md @@ -3,37 +3,32 @@ # fkyaml::basic_node::mapping_type ```cpp -using mapping_type = MappingType; +using mapping_type = MappingType; ``` -The type used to store mapping node values. +The type used to store mapping values. -To store mapping objects in [`basic_node`](index.md) class, the container type is defined by the template parameter `MappingType` which chooses the type to use for integer objects. -If not explicitly specified, the default type `std::map` will be chosen. -With the decided container type, the type of mapping objects will then be decided in the form of `MappingType` with which mapping objects are stored inside a [`basic_node`](index.md). -Note that mapping objects are stored as pointers in a [`basic_node`](index.md) so that the internal storage size will at most be 8 bytes. +The actual type is defined by the template parameter `MappingType`. +If not explicitly specified, the default type `std::map` is defined. +With the decided container type, the type of mapping objects will then be decided in the form of `MappingType` with which mapping objects are stored inside a [`basic_node`](index.md). + +Note that mapping values are stored as a pointer to an allocated memory area on the heap in a [`basic_node`](index.md) so that the internal storage size will at most be 8 bytes. !!! Note "Preserve the insertion order of key-value pairs" The YAML specification describes as a mapping node as "an unordered association of unique keys to values". Which means that **the insertion order of key-value pairs are not guranteed by the YAML specification**. To follow the specification, the fkYAML library uses `std::map` as the mapping container type by default with the intention of better integration with other C++ programs. - If your YAML documents really needs to be dependent on the insertion order (the YAML specification discourages that though), you can force preserving the insertion order by specifying [`fkyaml::ordered_map`](../ordered_map/index.md) as the MappingType template parameter as follows: + If mapping values needs to be dependent on the insertion order, you can force preserving the insertion order by specifying [`fkyaml::ordered_map`](../ordered_map/index.md) as the MappingType template parameter as follows: ```cpp #include using ordered_node = basic_node; ``` -### **Template Paramters** - -`MappingType` -: The container to store key-value pairs. Defaults to `std::map`. - -`StringType` -: The type of keys and string scalar values. Defaults to `std::string`. +## **Examples** -???+ Example +??? Example ```cpp --8<-- "examples/ex_basic_node_mapping_type.cpp:9" @@ -44,7 +39,7 @@ Note that mapping objects are stored as pointers in a [`basic_node`](index.md) s --8<-- "examples/ex_basic_node_mapping_type.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [ordered_map](../ordered_map/index.md) diff --git a/docs/mkdocs/docs/api/basic_node/node.md b/docs/mkdocs/docs/api/basic_node/node.md index b27ccb73..32236087 100644 --- a/docs/mkdocs/docs/api/basic_node/node.md +++ b/docs/mkdocs/docs/api/basic_node/node.md @@ -6,9 +6,11 @@ using node = basic_node<>; ``` -This type is the default specialization of the [basic_node](index.md) class which uses the standard template types. +This type is a specialization of the [basic_node](index.md) template class and uses the default template parameter types. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_node.cpp:9" @@ -19,7 +21,7 @@ This type is the default specialization of the [basic_node](index.md) class whic --8<-- "examples/ex_basic_node_node.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [operator<<](insertion_operator.md) diff --git a/docs/mkdocs/docs/api/basic_node/node_t.md b/docs/mkdocs/docs/api/basic_node/node_t.md index d337fd44..cf3ec9fb 100644 --- a/docs/mkdocs/docs/api/basic_node/node_t.md +++ b/docs/mkdocs/docs/api/basic_node/node_t.md @@ -17,7 +17,7 @@ enum class node_t !!! warning "Deprecation" - The enum class [`#!cpp fkyaml::node_type`](../node_type.md) replaces the type alias `#!cpp fkyaml::basic_node::node_t` which has been deprecated in version 0.3.12. It will be removed in version 0.4.0. Please replace usages like + The enum class [`#!cpp fkyaml::node_type`](../node_type.md) replaces the type alias `#!cpp fkyaml::basic_node::node_t` which has been deprecated in version 0.3.12. It will be removed in a future version. Please replace usages like ```cpp fkyaml::node::node_t t; @@ -29,7 +29,7 @@ enum class node_t fkyaml::node_type t; ``` -This enumeration collects the different YAML value types. They are internally used to distinguish the stored values, and the functions [`is_sequence`](is_sequence.md), [`is_mapping`](is_mapping.md) and [`is_scalar`](is_scalar.md) (with [`is_null`](is_null.md), [`is_boolean`](is_boolean.md), [`is_integer`](is_integer.md), [`is_float_number`](is_float_number.md), [`is_string`](is_string.md)) rely on it. +This enumeration collects the different YAML value types. !!! Note "Types of scalars" @@ -40,7 +40,9 @@ This enumeration collects the different YAML value types. They are internally us * [`float_number_type`](float_number_type.md) for float number scalar values * [`string_type`](string_type.md) for string scalar values -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_node_t.cpp:9" @@ -51,7 +53,7 @@ This enumeration collects the different YAML value types. They are internally us --8<-- "examples/ex_basic_node_node_t.output" ``` -### **See Also** +## **See Also** * [type](type.md) * [is_sequence](is_sequence.md) diff --git a/docs/mkdocs/docs/api/basic_node/operator=.md b/docs/mkdocs/docs/api/basic_node/operator=.md index 9d9dde97..1766fde2 100644 --- a/docs/mkdocs/docs/api/basic_node/operator=.md +++ b/docs/mkdocs/docs/api/basic_node/operator=.md @@ -9,27 +9,18 @@ basic_node& operator=(basic_node&& rhs) noexcept; // (2) ``` Assignment operator. -The `basic_node` class supports both copy and move assignments. - -## Overload (1) - -```cpp -basic_node& operator=(const basic_node& rhs) noexcept; -``` - -Copy assignment operator. -Copies a YAML node value via the "copy and swap" strategy to enhance exception safety. +The `basic_node` class supports both copy(1) and move(2) assignments. ### **Parameters** ***`rhs`*** [in] -: A lvalue basic_node object to be copied with. +: A basic_node to copy/move from. ### **Return Value** -Reference to this basic_node object. +Reference to `this` basic_node object. -???+ Example +??? Example "Overload(1): copy assignments a basic_node" ```cpp --8<-- "examples/ex_basic_node_copy_assignment_operator.cpp:9" @@ -40,47 +31,17 @@ Reference to this basic_node object. --8<-- "examples/ex_basic_node_copy_assignment_operator.output" ``` -## Overload (2) +## **Examples** -```cpp -basic_node& operator=(basic_node&& rhs) noexcept; -``` - -Move assignment operator. -Moves a YAML node value from the given node. - -### **Parameters** - -***`rhs`*** [in] -: A rvalue basic_node object to be moved from. - -### **Return Value** - -Reference to this basic_node object. - -???+ Example +??? Example "Overload(2): move assignments a basic_node" ```cpp - #include - #include - - int main() - { - fkyaml::node n = true; - fkyaml::node n2 = 123; - n = std::move(n2); - - std::cout << std::boolalpha << n.is_integer() << std::endl; - std::cout << n.get_value() << std::endl; - - return 0; - } + --8<-- "examples/ex_basic_node_move_assignment_operator.cpp:9" ``` output: ```bash - true - 123 + --8<-- "examples/ex_basic_node_move_assignment_operator.output" ``` ## **See Also** diff --git a/docs/mkdocs/docs/api/basic_node/operator[].md b/docs/mkdocs/docs/api/basic_node/operator[].md index 548f5d16..17dd6cbb 100644 --- a/docs/mkdocs/docs/api/basic_node/operator[].md +++ b/docs/mkdocs/docs/api/basic_node/operator[].md @@ -3,80 +3,63 @@ # fkyaml::basic_node::operator[] ```cpp -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -basic_node& operator[](KeyType&& key); // (1) - -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -const basic_node& operator[](KeyType&& key) const; // (2) - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -basic_node& operator[](KeyType&& key); // (3) - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -const basic_node& operator[](KeyType&& key) const; // (4) +// (1) +template +basic_node& operator[](KeyType&& key); + +template +const basic_node& operator[](KeyType&& key) const; + +// (2) +template +basic_node& operator[](BasicNodeType&& key); + +template +const basic_node& operator[](BasicNodeType&& key) const; ``` -Access to a YAML node element with either an index (for sequences) or a key (for mappings). -If the node is neither a sequence nor a mapping, or if the node is a sequence but the given `key` is not an integer, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown. +Access to an element in a container node with either an index or key value. +This function must be called on a container node, or a [`fkyaml::type_error`](../exception/type_error.md) would be thrown. -!!! Danger +The input parameter `key` must be either a [`basic_node`](index.md) object or an object of a compatible type, i.e., a type with which a [`basic_node`](index.md) object can be constructible. - This API does not check the size of a sequence node before accessing the element. - To avoid undefined behaviors, please make sure the argument `key` is smaller than the actual sequence size with a return value of the [`basic_node::size()`](size.md) function. - If bounds check is necessary, prefer [`basic_node::at()`](at.md) function. +Note that the overload (1) internally constructs a temporal [`basic_node`](index.md) object. +So, if you use the same key multiple times, for example, in a for loop, consider creating a [`basic_node`](index.md) as a key first for better performance. -!!! Warning +!!! Danger "Accessing an element with an invalid index (Undefined Behavior)" - This API does not check the existence of the given `key` in a mapping node. - If the key does not exist, a default [basic_node](index.md) object will be created. - Please make sure that the node has the given key in advance by calling the [`basic_node::contains()`](contains.md) function. - If such a behavior is unwanted, prefer [`basic_node::at()`](at.md) function. + This function does not check the size of the queried sequence before accessing the element. + To avoid undefined behaviors, please make sure the argument `key` is smaller than the queried sequence size with the [`size()`](size.md) function in advance. + Or use [`at()`](at.md) function instead, which executes the bounds check before accessing an element with a given index. -## Overload (1), (2) +!!! Warning "Accessing an element with a non-existent key" -```cpp -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -basic_node& operator[](KeyType&& key); // (1) - -template < - typename KeyType, detail::enable_if_t< - detail::conjunction< - detail::negation>, - detail::is_node_compatible_type>::value, - int> = 0> -const basic_node& operator[](KeyType&& key) const; // (2) -``` + This function does not check the existence of the given `key` in the queried mapping. + If the key does not exist, a [basic_node](index.md) object will be default-constructed. + If such a behavior is unwanted, choose one of the followings. + * use [`at()`](at.md) function instead, which executes additional checks before accessing an element. + * call the [`contains()`](contains.md) function in advance to make sure that the key exists in the queried mapping. + +## **Template Parameters** -Accesses to an element in the YAML sequence/mapping node with the given key object of a compatible type with the [`basic_node`](index.md) class, i.e., a type with which a [`basic_node`](index.md) object is constructible. -These overloads internally construct a [`basic_node`](index.md) object with `key`. +***KeyType*** +: A compatible key type. + +***BasicNodeType*** +: A basic_node template instance type. + +## **Parameters** -### **Parameters** +***`key`*** [in] +: A key to a target element in the sequence/mapping node. -***`index`*** [in] -: An index/key for an element in the YAML sequence/mapping node. +## **Return Value** -### **Return Value** +(Constant) reference to the node value which is associated with the given key. -Reference, or constant reference, to the YAML node object associated with the given index/key. +## **Examples** -???+ Example +??? Example "Overload(1): access an element with compatible keys" ```cpp --8<-- "examples/ex_basic_node_subscript_operator_compatible_type.cpp:9" @@ -87,37 +70,7 @@ Reference, or constant reference, to the YAML node object associated with the gi --8<-- "examples/ex_basic_node_subscript_operator_compatible_type.output" ``` -## Overload (3), (4) - -```cpp -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -basic_node& operator[](KeyType&& key); // (3) - -template < - typename KeyType, detail::enable_if_t>::value, int> = 0> -const basic_node& operator[](KeyType&& key) const; // (4) -``` - -Accesses to an element in the YAML sequence/mapping node with the given [`basic_node`](index.md) key object. -Unlike the overloads (1) and (2) above, these overloads do not internally construct a [`basic_node`](index.md) object. -So, these overloads works more effectively when some key objects are used multiple times, for instance, in a for-loop. - -### **Template Parameters** - -***KeyType*** -: A key type which is a kind of the [`basic_node`](index.md) template class. - -### **Parameters** - -***`key`*** [in] -: An index/key for an element in the YAML sequence/mapping node. - -### **Return Value** - -Reference, or constant reference, to the YAML node object associated with the given index/key. - -???+ Example +??? Example "Overload(2): access an element with `basic_node` keys" ```cpp --8<-- "examples/ex_basic_node_subscript_operator_basic_node.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/operator_eq.md b/docs/mkdocs/docs/api/basic_node/operator_eq.md index fb51fdb6..b5d09dd5 100644 --- a/docs/mkdocs/docs/api/basic_node/operator_eq.md +++ b/docs/mkdocs/docs/api/basic_node/operator_eq.md @@ -6,22 +6,23 @@ bool operator==(const basic_node& rhs) const noexcept; ``` -Equal-to operator. -Compares two `basic_node` objects for equality according to the following rules: +Compares two `basic_node` objects for equality according to the following rules: -* Two `basic_node` objects are equal if they are of the same [`node_t`](node_t.md) type and their stored values are the same according to their respective `operator==`. -* Two `basic_node` objects are always equal if both of them are of the [`node_t::NULL_OBJECT`](node_t.md) type. +* Two `basic_node` objects are equal if they are of the same [`node_type`](../node_type.md) type and their stored values are the same according to their respective `operator==`. +* Two `basic_node` objects are always equal if both of them are of the [`node_type::NULL_OBJECT`](../node_type.md) type. ## **Parameters** ***`rhs`*** [in] -: A `basic_node` object to be compared with `this` object. +: A `basic_node` object to compare with. ## **Return Value** -`true` if both types and values are equal, `false` otherwise. +`true` if both basic_node objects are equal, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_operator_eq.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/operator_ge.md b/docs/mkdocs/docs/api/basic_node/operator_ge.md index d1a873ab..a2c97943 100644 --- a/docs/mkdocs/docs/api/basic_node/operator_ge.md +++ b/docs/mkdocs/docs/api/basic_node/operator_ge.md @@ -6,20 +6,20 @@ bool operator>=(const basic_node& rhs) const noexcept; ``` -Greater-than-or-equal-to operator. Check if `this` object is greater than or equal to `rhs`. -The operator returns the result of `!(*this < rhs)`. (see [`operator<`](operator_lt.md)) ## **Parameters** ***`rhs`*** [in] -: A `basic_node` object to be compared with `this` object. +: A `basic_node` object to compare with. ## **Return Value** -`true` if `this` is greater than `rhs`, `false` otherwise. +`true` if `this` is greater than or equal to `rhs`, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_operator_ge.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/operator_gt.md b/docs/mkdocs/docs/api/basic_node/operator_gt.md index d3630ae2..c95ac0e5 100644 --- a/docs/mkdocs/docs/api/basic_node/operator_gt.md +++ b/docs/mkdocs/docs/api/basic_node/operator_gt.md @@ -6,20 +6,20 @@ bool operator>(const basic_node& rhs) const noexcept; ``` -Greater-than operator. Check if `this` object is greater than `rhs`. -The operator returns the result of `!(*this <= rhs)`. (see [`operator<=`](operator_le.md)) ## **Parameters** ***`rhs`*** [in] -: A `basic_node` object to be compared with `this` object. +: A `basic_node` object to compare with. ## **Return Value** `true` if `this` is greater than `rhs`, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_operator_gt.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/operator_le.md b/docs/mkdocs/docs/api/basic_node/operator_le.md index 566701ae..9fb6396c 100644 --- a/docs/mkdocs/docs/api/basic_node/operator_le.md +++ b/docs/mkdocs/docs/api/basic_node/operator_le.md @@ -6,20 +6,20 @@ bool operator<=(const basic_node& rhs) const noexcept; ``` -Less-than-or-equal-to operator. Check if `this` object is less than or equal to `rhs`. -The operator returns the result of `!(rhs < *this)`. (see [`operator<`](operator_lt.md)) ## **Parameters** ***`rhs`*** [in] -: A `basic_node` object to be compared with `this` object. +: A `basic_node` object to compare with. ## **Return Value** `true` if `this` is less than or equal to `rhs`, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_operator_le.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/operator_lt.md b/docs/mkdocs/docs/api/basic_node/operator_lt.md index 3678d9d1..46d75cba 100644 --- a/docs/mkdocs/docs/api/basic_node/operator_lt.md +++ b/docs/mkdocs/docs/api/basic_node/operator_lt.md @@ -6,31 +6,32 @@ bool operator<(const basic_node& rhs) const noexcept; ``` -Less-than operator. Check if `this` object is less than `rhs` according to the following rules: -* If the values are of the same [`node_t`](node_t.md) type, their stored values are compared according to their respective `operator<`. -* Two `basic_node` objects are always equal if both of them are of the [`node_t::NULL_OBJECT`](node_t.md) type. -* If the values are of different [`node_t`](node_t.md) types, the stored values are ignored and the order of the types are considered. The order of the types is as followed (top < bottom): - * node_t::SEQUENCE - * node_t::MAPPING - * node_t::NULL_OBJECT - * node_t::BOOLEAN - * node_t::INTEGER - * node_t::FLOAT_NUMBER - * node_t::STRING -* If the values are of the [`node_t::BOOLEAN`](node_t.md) type, a value whose stored value is `false` is less than a value whose stored value is `true`. +* If the values are of the same [`node_type`](../node_type.md) type, their stored values are compared according to their respective `operator<`. +* Two `basic_node` objects are always equal if both of them are of the [`node_type::NULL_OBJECT`](../node_type.md) type. +* If the values are of different [`node_type`](../node_type.md) types, the stored values are ignored and the order of the types are considered. The order of the types is as followed (top < bottom): + * node_type::SEQUENCE + * node_type::MAPPING + * node_type::NULL_OBJECT + * node_type::BOOLEAN + * node_type::INTEGER + * node_type::FLOAT + * node_type::STRING +* If the values are of the [`node_type::BOOLEAN`](../node_type.md) type, a value whose stored value is `false` is less than a value whose stored value is `true`. ## **Parameters** ***`rhs`*** [in] -: A `basic_node` object to be compared with `this` object. +: A `basic_node` object to compared with. ## **Return Value** `true` if `this` is less than `rhs`, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_operator_lt.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/operator_ne.md b/docs/mkdocs/docs/api/basic_node/operator_ne.md index 5291094b..2f7ab060 100644 --- a/docs/mkdocs/docs/api/basic_node/operator_ne.md +++ b/docs/mkdocs/docs/api/basic_node/operator_ne.md @@ -6,20 +6,20 @@ bool operator!=(const basic_node& rhs) const noexcept; ``` -Not-Equal-to operator. Compares two `basic_node` objects for inequality. -This operator returns the result of `!(*this == rhs)`. (see [`operator==`](operator_eq.md)) ## **Parameters** ***`rhs`*** [in] -: A `basic_node` object to be compared with `this` object. +: A `basic_node` object to compare with. ## **Return Value** `true` if either types or values are not equal, `false` otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_operator_ne.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/rbegin.md b/docs/mkdocs/docs/api/basic_node/rbegin.md index b3e2cf6a..33d0e662 100644 --- a/docs/mkdocs/docs/api/basic_node/rbegin.md +++ b/docs/mkdocs/docs/api/basic_node/rbegin.md @@ -8,16 +8,18 @@ const_reverse_iterator rbegin() const; const_reverse_iterator crbegin() const; ``` -Returns an iterator to the reverse-beginning (= last) element of a container node. +Returns a (constant) iterator to the reverse-beginning (= last) element of a container node. Throws a [`fkyaml::type_error`](../exception/type_error.md) if a basic_node is neither a sequence nor mapping node. ![Image from https://en.cppreference.com/w/cpp/iterator/reverse_iterator](../../img/range-rbegin-rend.svg) -### **Return Value** +## **Return Value** -A (constant) reverse iterator to the reverse-beginning (= last) element of a container node. +A (constant) iterator to the reverse-beginning (= last) element of a container node. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_rbegin.cpp:9" @@ -28,7 +30,7 @@ A (constant) reverse iterator to the reverse-beginning (= last) element of a con --8<-- "examples/ex_basic_node_rbegin.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [node](node.md) diff --git a/docs/mkdocs/docs/api/basic_node/rend.md b/docs/mkdocs/docs/api/basic_node/rend.md index 8ac5e93f..e73788c0 100644 --- a/docs/mkdocs/docs/api/basic_node/rend.md +++ b/docs/mkdocs/docs/api/basic_node/rend.md @@ -8,16 +8,18 @@ const_reverse_iterator rend() const; const_reverse_iterator crend() const; ``` -Returns an iterator to the reverse-end (= one before the first) element of a container node. +Returns a (constant) iterator to the reverse-end (= one before the first) element of a container node. Throws a [`fkyaml::type_error`](../exception/type_error.md) if a basic_node is neither a sequence nor mapping node. ![Image from https://en.cppreference.com/w/cpp/iterator/reverse_iterator](../../img/range-rbegin-rend.svg) -### **Return Value** +## **Return Value** -A (constant) reverse iterator to the reverse-end (= one before the first) element of a container node. +A (constant) iterator to the reverse-end (= one before the first) element of a container node. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_rend.cpp:9" @@ -28,7 +30,7 @@ A (constant) reverse iterator to the reverse-end (= one before the first) elemen --8<-- "examples/ex_basic_node_rend.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [node](node.md) diff --git a/docs/mkdocs/docs/api/basic_node/reverse_iterator.md b/docs/mkdocs/docs/api/basic_node/reverse_iterator.md index d0ebe24a..4efe66ae 100644 --- a/docs/mkdocs/docs/api/basic_node/reverse_iterator.md +++ b/docs/mkdocs/docs/api/basic_node/reverse_iterator.md @@ -3,43 +3,45 @@ # fkyaml::basic_node::reverse_iterator, fkyaml::basic_node::const_reverse_iterator ```cpp -using reverse_iterator = detail::reverse_iterator; -using const_reverse_iterator = detail::reverse_iterator; +using reverse_iterator = detail::reverse_iterator; +using const_reverse_iterator = detail::reverse_iterator; ``` The types of non-const/const reverse iterators for [`basic_node`](index.md) containers. They satisfies [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) and are commonly used for sequence and mapping container nodes. -## Member Types +## **Member Types** ### reverse_iterator | Type | Definition | | ------------------- | --------------------------------------------------------------------------------------------- | | `iterator_type` | `basic_node::iterator` | +| `iterator_category` | [`std::bidirectional_iterator_tag`](https://en.cppreference.com/w/cpp/iterator/iterator_tags) | | `value_type` | `basic_node` | -| `reference` | `basic_node&` | -| `pointer` | `basic_node*` | | `difference_type` | [`std::ptrdiff_t`](https://en.cppreference.com/w/cpp/types/ptrdiff_t) | -| `iterator_category` | [`std::bidirectional_iterator_tag`](https://en.cppreference.com/w/cpp/iterator/iterator_tags) | +| `pointer` | `basic_node*` | +| `reference` | `basic_node&` | ### const_reverse_iterator | Type | Definition | | ------------------- | --------------------------------------------------------------------------------------------- | | `iterator_type` | `basic_node::const_iterator` | +| `iterator_category` | [`std::bidirectional_iterator_tag`](https://en.cppreference.com/w/cpp/iterator/iterator_tags) | | `value_type` | `basic_node` | -| `reference` | `const basic_node&` | -| `pointer` | `const basic_node*` | | `difference_type` | [`std::ptrdiff_t`](https://en.cppreference.com/w/cpp/types/ptrdiff_t) | -| `iterator_category` | [`std::bidirectional_iterator_tag`](https://en.cppreference.com/w/cpp/iterator/iterator_tags) | +| `pointer` | `const basic_node*` | +| `reference` | `const basic_node&` | -## Member Functions +## **Member Functions** | Name | Description | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | key | Returns const reference to a key node of the current key-value pair.
`fkyaml::exception` is thrown if an iterator points to a sequence element. | | value | Returns reference to a sequence element if an element points to a sequence element, or a mapping value otherwise. | -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_reverse_iterator.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/sequence.md b/docs/mkdocs/docs/api/basic_node/sequence.md index b305fdde..ba7abedf 100644 --- a/docs/mkdocs/docs/api/basic_node/sequence.md +++ b/docs/mkdocs/docs/api/basic_node/sequence.md @@ -10,9 +10,11 @@ static basic_node sequence(sequence_type&& seq); The factory method which constructs a basic_node with the [`node_t::SEQUENCE`](node_t.md) type from a sequence node value. Calling this API with no arguments will constructs a basic_node with an empty sequence node value. -The resulting basic_node has the [`node_t::SEQUENCE`](node_t.md) type. +The resulting basic_node has the [`node_type::SEQUENCE`](../node_type.md) type. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_sequence.cpp:9" @@ -23,9 +25,8 @@ The resulting basic_node has the [`node_t::SEQUENCE`](node_t.md) type. --8<-- "examples/ex_basic_node_sequence.output" ``` - -### **See Also** +## **See Also** * [basic_node](index.md) -* [node_t](node_t.md) +* [node_type](../node_type.md) * [operator<<](insertion_operator.md) diff --git a/docs/mkdocs/docs/api/basic_node/sequence_type.md b/docs/mkdocs/docs/api/basic_node/sequence_type.md index f8cfb6e0..edabaa72 100644 --- a/docs/mkdocs/docs/api/basic_node/sequence_type.md +++ b/docs/mkdocs/docs/api/basic_node/sequence_type.md @@ -8,11 +8,15 @@ using sequence_type = SequenceType; The type used to store sequence node values. -To store sequence objects in [`basic_node`](index.md) class, the type is defined by the template parameter `SequenceType` which chooses the type to use for sequence objects. -If not explicitly specified, the default type `std::vector` will be chosen. -Note that sequence objects are stored as pointers to the decided type in a [`basic_node`](index.md) so that the internal storage size will at most be 8 bytes. +The type is defined by the template parameter `SequenceType`. +If not explicitly specified, the default type `std::vector` is defined. +With the decided container type, the type of sequence objects will then be decided in the form of `SequenceType` with which sequence objects are stored inside a [`basic_node`](index.md). -???+ Example +Note that sequence objects are stored as a pointer to an allocated memory area on the heap in a [`basic_node`](index.md) so that the internal storage size will at most be 8 bytes. + +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_sequence_type.cpp:9" @@ -23,6 +27,6 @@ Note that sequence objects are stored as pointers to the decided type in a [`bas --8<-- "examples/ex_basic_node_sequence_type.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) diff --git a/docs/mkdocs/docs/api/basic_node/serialize.md b/docs/mkdocs/docs/api/basic_node/serialize.md index 1861ef62..17370f54 100644 --- a/docs/mkdocs/docs/api/basic_node/serialize.md +++ b/docs/mkdocs/docs/api/basic_node/serialize.md @@ -8,8 +8,8 @@ static std::string serialize(const basic_node& node); Serializes YAML node values recursively. Currently, the serialization of mappings and sequences only supports block styles. -That means that, even if a deserialized source input contains container nodes written in flow styles, this function forces them to be emitted in block styles. -Moreover, fkYAML unconditionally uses LFs as the line break format in serialization outputs, and there is currently no way to change it to use CR+LFs instead. +That means that, even if an original YAML document contains container nodes written in the flow style, this function forces them to be emitted in the block style. +Moreover, fkYAML unconditionally uses LFs (Unix Style) as the line break format in serialization outputs, and there is currently no way to change it to use CR+LFs (Windows Style) instead. This function serializes the given `node` parameter in the following format. ```yaml @@ -47,16 +47,18 @@ This function serializes the given `node` parameter in the following format. : ``` -### **Parameters** +## **Parameters** ***`node`*** [in] : A `basic_node` object to be serialized. -### **Return Value** +## **Return Value** -The resulting string object from the serialization of the `node` object. +The resulting string object of the serialization. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_serialize.cpp:9" @@ -67,7 +69,7 @@ The resulting string object from the serialization of the `node` object. --8<-- "examples/ex_basic_node_serialize.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [add_anchor_name](add_anchor_name.md) diff --git a/docs/mkdocs/docs/api/basic_node/serialize_docs.md b/docs/mkdocs/docs/api/basic_node/serialize_docs.md index 39cc43be..444dd70c 100644 --- a/docs/mkdocs/docs/api/basic_node/serialize_docs.md +++ b/docs/mkdocs/docs/api/basic_node/serialize_docs.md @@ -8,7 +8,7 @@ static std::string serialize_docs(const std::vector& docs); Serializes YAML documents into a string. This function serializes the given `docs` parameter with the separation line (...) between YAML documents. -Regarding the serialization of each document, see the documentation for the [`serialize()`](serialize.md) function which this function calls internally. +Regarding the serialization of each document, see the documentation for the [`serialize()`](serialize.md) function with which this function shares internal implementation. Just as the [`serialize()`](serialize.md) function does, fkYAML unconditionally uses LFs as the line break format in serialization outputs, and there is currently no way to change it to use CR+LFs instead. ```yaml @@ -18,16 +18,18 @@ Just as the [`serialize()`](serialize.md) function does, fkYAML unconditionally # the last document end marker (...) is omitted since it's redundant. ``` -### **Parameters** +## **Parameters** ***`docs`*** [in] : `basic_node` objects to be serialized. -### **Return Value** +## **Return Value** -The resulting string object from the serialization of the `docs` object. +The resulting string object of the serialization. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_serialize_docs.cpp:9" @@ -38,7 +40,7 @@ The resulting string object from the serialization of the `docs` object. --8<-- "examples/ex_basic_node_serialize_docs.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) * [add_anchor_name](add_anchor_name.md) diff --git a/docs/mkdocs/docs/api/basic_node/set_yaml_version.md b/docs/mkdocs/docs/api/basic_node/set_yaml_version.md index 9090762e..2234e391 100644 --- a/docs/mkdocs/docs/api/basic_node/set_yaml_version.md +++ b/docs/mkdocs/docs/api/basic_node/set_yaml_version.md @@ -8,7 +8,7 @@ void set_yaml_version(const yaml_version_t version) noexcept; !!! warning "Deprecation" - The function [`#!cpp void set_yaml_version_type(const yaml_version_type)`](set_yaml_version_type.md) replaces the function `#!cpp void set_yaml_version(const basic_node::yaml_version_t)` which has been deprecated in version 0.3.12. It will be removed in version 0.4.0. Please replace calls like + The function [`#!cpp void set_yaml_version_type(const yaml_version_type)`](set_yaml_version_type.md) replaces the function `#!cpp void set_yaml_version(const basic_node::yaml_version_t)` which has been deprecated in version 0.3.12. It will be removed in a future version. Please replace calls like ```cpp n.set_yaml_version(fkyaml::node::yaml_version_t::VER_1_2); @@ -20,14 +20,16 @@ void set_yaml_version(const yaml_version_t version) noexcept; n.set_yaml_version_type(fkyaml::yaml_version_type::VERSION_1_2); ``` -Sets a target YAML version to the `basic_node` object. +Sets a target YAML specification version to the `basic_node` object. -### **Parameters** +## **Parameters** ***version*** [in] : A target YAML version. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_set_yaml_version.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/set_yaml_version_type.md b/docs/mkdocs/docs/api/basic_node/set_yaml_version_type.md index 5884d71f..f933c16c 100644 --- a/docs/mkdocs/docs/api/basic_node/set_yaml_version_type.md +++ b/docs/mkdocs/docs/api/basic_node/set_yaml_version_type.md @@ -6,14 +6,16 @@ void set_yaml_version_type(const yaml_version_type version) noexcept; ``` -Sets a target YAML version to the `basic_node` object. +Sets a target YAML specification version to the `basic_node` object. -### **Parameters** +## **Parameters** ***version*** [in] : A target YAML version. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_set_yaml_version_type.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/size.md b/docs/mkdocs/docs/api/basic_node/size.md index e48dca10..71ccce08 100644 --- a/docs/mkdocs/docs/api/basic_node/size.md +++ b/docs/mkdocs/docs/api/basic_node/size.md @@ -7,13 +7,15 @@ std::size_t size() const; ``` Gets the size of a node value. -Throws a [`fkyaml::exception`](../exception/index.md) if a basic_node does not have a conatiner nor string value. +Throws a [`fkyaml::exception`](../exception/index.md) if a basic_node is neither a sequence, mapping nor string value. -### **Return Value** +## **Return Value** The size of a node value. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_size.cpp:9" @@ -24,6 +26,6 @@ The size of a node value. --8<-- "examples/ex_basic_node_size.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) diff --git a/docs/mkdocs/docs/api/basic_node/string_type.md b/docs/mkdocs/docs/api/basic_node/string_type.md index 92861edd..b07fe8d9 100644 --- a/docs/mkdocs/docs/api/basic_node/string_type.md +++ b/docs/mkdocs/docs/api/basic_node/string_type.md @@ -8,11 +8,15 @@ using string_type = StringType; The type used to store integer node values and keys for mapping nodes. -To store string objects in [`basic_node`](index.md) class, the type is defined by the template parameter `StringType` which chooses the type to use for string objects. -If not explicitly specified, the default type `std::string` will be chosen. -Note that string objects are stored as pointers to the decided type in a [`basic_node`](index.md) so that the internal storage size will at most be 8 bytes. +The type is defined by the template parameter `StringType`. +If not explicitly specified, the default type `std::string` is defined. +With the decided type, string values are stored directly inside a [`basic_node`](index.md). -???+ Example +Note that string objects are stored as a pointer to an allocated memory area on the heap in a [`basic_node`](index.md) so that the internal storage size will at most be 8 bytes. + +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_string_type.cpp:9" @@ -23,6 +27,6 @@ Note that string objects are stored as pointers to the decided type in a [`basic --8<-- "examples/ex_basic_node_string_type.output" ``` -### **See Also** +## **See Also** * [basic_node](index.md) diff --git a/docs/mkdocs/docs/api/basic_node/swap.md b/docs/mkdocs/docs/api/basic_node/swap.md index 03017cad..bc2401c3 100644 --- a/docs/mkdocs/docs/api/basic_node/swap.md +++ b/docs/mkdocs/docs/api/basic_node/swap.md @@ -11,23 +11,20 @@ template < template class ConverterType> inline void swap( basic_node& lhs, - basic_node& rhs) noexcept(noexcept(lhs.swap(rhs))); // (2) + basic_node& rhs) noexcept(noexcept(lhs.swap(rhs))); // (2) non-member function ``` Swaps the internally stored data with the given basic_node object. -## Overload (1) +## **Parameters** -```cpp -void swap(basic_node& rhs) noexcept; // (1) -``` - -### **Parameters** +***`lhs`*** [in, out] +: A basic_node to swap the contents with. -***`rhs`*** [in] -: A basic_node object to be swapped with. +***`rhs`*** [in, out] +: A basic_node to swap the contents with. -???+ Example +??? Example "member function: Swap the contents with another basic_node" ```cpp --8<-- "examples/ex_basic_node_swap_member.cpp:9" @@ -38,27 +35,9 @@ void swap(basic_node& rhs) noexcept; // (1) --8<-- "examples/ex_basic_node_swap_member.output" ``` -## Overload (2) - -```cpp -template < - template class SequenceType, template class MappingType, - typename BooleanType, typename IntegerType, typename FloatNumberType, typename StringType, - template class ConverterType> -inline void swap( - basic_node& lhs, - basic_node& rhs) noexcept(noexcept(lhs.swap(rhs))); // (2) -``` - -### **Parameters** - -***`lhs`*** [in] -: A left-hand-side basic_node object to be swapped with. - -***`rhs`*** -: A right-hand-side basic_node object to be swapped with. +## **Examples** -???+ Example +??? Example "non-member function: Swap the contents between basic_node objects" ```cpp --8<-- "examples/ex_basic_node_swap_std.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/type.md b/docs/mkdocs/docs/api/basic_node/type.md index 8a3f0038..51e1bc8c 100644 --- a/docs/mkdocs/docs/api/basic_node/type.md +++ b/docs/mkdocs/docs/api/basic_node/type.md @@ -8,7 +8,7 @@ node_t type() const noexcept; !!! warning "Deprecation" - The function [`#!cpp node_type get_type()`](get_type.md) replaces the function `basic_node::node_t type()` which has been deprecated in version 0.3.12. It will be removed in version 0.4.0. Please replace calls like + The function [`#!cpp node_type get_type()`](get_type.md) replaces the function `basic_node::node_t type()` which has been deprecated in version 0.3.12. It will be removed in a future version. Please replace calls like ```cpp fkyaml::node::node_t t = n.type(); @@ -20,9 +20,9 @@ node_t type() const noexcept; fkyaml::node_type t = n.get_type(); ``` -Returns the type of the YAML node value as a value from the [`node_t`](node_t.md) enumeration. +Returns the type of the YAML node value. -### **Return Value** +## **Return Value** The type of the YAML node value. @@ -36,7 +36,9 @@ The type of the YAML node value. | floating point number | node_t::FLOAT_NUMBER | | string | node_t::STRING | -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_type.cpp:9" @@ -47,6 +49,6 @@ The type of the YAML node value. --8<-- "examples/ex_basic_node_type.output" ``` -### **See Also** +## **See Also** * [node_t](node_t.md) diff --git a/docs/mkdocs/docs/api/basic_node/value_converter_type.md b/docs/mkdocs/docs/api/basic_node/value_converter_type.md index a1b103b4..c67c5553 100644 --- a/docs/mkdocs/docs/api/basic_node/value_converter_type.md +++ b/docs/mkdocs/docs/api/basic_node/value_converter_type.md @@ -7,21 +7,23 @@ template using value_converter_type = ValueConverterType; ``` -A helper type alias to determine converter type for the given target native data type `T`. +A helper type alias to determine converter type for the target type `T`. The default type of the template parameter `ValueConverterType` is [`node_value_converter`](../node_value_converter/index.md). -This type alias is used to determine the target type `T` is convertible from/to [`basic_node`](index.md). -The function [`get_value`](get_value.md) relies on it internally. -If you want to convert some type from/to `basic_node`, however, it is recommended to use [`basic_node::get_value`](get_value.md) instead, in order both to make your program more understandable and to avoid too much dependency on the fkYAML library implementation. +This type alias is used to determine the target type `T` is convertible from/to [`basic_node`](index.md) and quite a few functions rely on it such as the [`get_value()`](get_value.md) function. -### **Template Parameters** +If you want to convert some type from/to `basic_node`, however, it is recommended to use [`basic_node::get_value`](get_value.md) instead, in order for your program to avoid too much dependency on the fkYAML library implementation. + +## **Template Parameters** ***T*** : The target native data type. ***SFINAE*** -: Type to add compile type checks via SFINAE. Usually `void` is given. +: Type for [SFINAE](https://en.cppreference.com/w/cpp/language/sfinae). If you do not need compile-time type checks, pass just `void`. + +## **Examples** -???+ Example +??? Example ```cpp --8<-- "examples/ex_basic_node_value_converter_type.cpp:9" diff --git a/docs/mkdocs/docs/api/basic_node/yaml_version_t.md b/docs/mkdocs/docs/api/basic_node/yaml_version_t.md index ad9d6700..a9029901 100644 --- a/docs/mkdocs/docs/api/basic_node/yaml_version_t.md +++ b/docs/mkdocs/docs/api/basic_node/yaml_version_t.md @@ -12,7 +12,7 @@ enum class yaml_version_t !!! warning "Deprecation" - The enum class [`fkyaml::yaml_version_type`](../yaml_version_type.md) replaces the type alias `fkyaml::basic_node::yaml_version_t` which has been deprecated in version 0.3.12. It will be removed in version 0.4.0. Please replace usages like + The enum class [`fkyaml::yaml_version_type`](../yaml_version_type.md) replaces the type alias `fkyaml::basic_node::yaml_version_t` which has been deprecated in version 0.3.12. It will be removed in a future version. Please replace usages like ```cpp fkyaml::node::yaml_version_t v; @@ -24,9 +24,11 @@ enum class yaml_version_t fkyaml::yaml_version_type v; ``` -This enumeration collects the used versions of YAML specification. It is used as meta data of a basic_node and the functions [`get_yaml_version`](get_yaml_version.md) and [`set_yaml_version`](set_yaml_version.md) rely on it. +This enumeration collects the YAML specification versions. It is used as meta data of a basic_node and the functions [`get_yaml_version`](get_yaml_version.md) and [`set_yaml_version`](set_yaml_version.md) rely on it. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_basic_node_yaml_version_t.cpp:9" @@ -37,7 +39,7 @@ This enumeration collects the used versions of YAML specification. It is used as --8<-- "examples/ex_basic_node_yaml_version_t.output" ``` -### **See Also** +## **See Also** * [deserialize](deserialize.md) * [get_yaml_version](get_yaml_version.md) diff --git a/docs/mkdocs/docs/api/exception/constructor.md b/docs/mkdocs/docs/api/exception/constructor.md index 0b0ba0ae..1efb6233 100644 --- a/docs/mkdocs/docs/api/exception/constructor.md +++ b/docs/mkdocs/docs/api/exception/constructor.md @@ -9,17 +9,14 @@ explicit exception(const char* msg) noexcept; // (2) ``` Constructs an exception object. -You can specify an error message on constructing an exception with an overloaded constructor. +You can specify an error message on constructing an object with an overloaded constructor. -## Overload (1) +## **Parameters** -```cpp -exception() = default; // (1) -``` - -Constructs an exception object without an error message. +***`msg`*** [in] +: An error message for the exception. If `nullptr` is given, the resulting error message will be empty. -???+ Example +??? Example "Overload(1): create a default value" ```cpp --8<-- "examples/ex_exception_constructor_noarg.cpp:9" @@ -30,21 +27,9 @@ Constructs an exception object without an error message. --8<-- "examples/ex_exception_constructor_noarg.output" ``` -## Overloads (2) - -```cpp -explicit exception(const char* msg) noexcept; // (2) -``` - -Constructs an exception with a given error message. -The given error message can be retrieved by calling [`exception::what()`](what.md) function. - -### **Parameters** - -***`msg`*** [in] -: An error message for the exception. If `nullptr` is given, the resulting error message will be empty. +## **Examples** -???+ Example +??? Example "Overload(2): create an object with an error message" ```cpp --8<-- "examples/ex_exception_constructor_msg.cpp:9" diff --git a/docs/mkdocs/docs/api/exception/destructor.md b/docs/mkdocs/docs/api/exception/destructor.md index b490ca46..18db8c8e 100644 --- a/docs/mkdocs/docs/api/exception/destructor.md +++ b/docs/mkdocs/docs/api/exception/destructor.md @@ -3,7 +3,7 @@ # fkyaml::exception::(destructor) ```cpp -~exception() noexcept; +~exception(); ``` Destroy an exception. diff --git a/docs/mkdocs/docs/api/exception/index.md b/docs/mkdocs/docs/api/exception/index.md index 876ab06b..2e91daf6 100644 --- a/docs/mkdocs/docs/api/exception/index.md +++ b/docs/mkdocs/docs/api/exception/index.md @@ -8,16 +8,17 @@ class exception : public std::exception; A basic exception class used in the fkYAML library. -## Derived Classes +## **Derived Classes** | Type | Description | | --------------------------------------- | ---------------------------------------------------- | | [invalid_encoding](invalid_encoding.md) | The exception indicating an encoding error. | +| [invalid_tag](invalid_tag.md) | The exception indicating an invalid tag. | | [out_of_range](out_of_range.md) | The exception indicating an out-of-range error. | | [parse_error](parse_error.md) | The exception indicating an error in parsing. | | [type_error](type_error.md) | The exception indicating an invalid type conversion. | -## Member Functions +## **Member Functions** ### Construction/Destruction diff --git a/docs/mkdocs/docs/api/exception/invalid_tag.md b/docs/mkdocs/docs/api/exception/invalid_tag.md new file mode 100644 index 00000000..755da61c --- /dev/null +++ b/docs/mkdocs/docs/api/exception/invalid_tag.md @@ -0,0 +1,19 @@ +Defined in header [``](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/exception.hpp) + +# fkyaml::invalid_tag + +```cpp +class invalid_tag : public exception; +``` + +A exception class indicating an invalid tag. +This class extends the [`fkyaml::exception`](index.md) class and the [`what()`](what.md) function emits an error message in the following format. + +``` +invalid_tag: [error message] tag=[invalid tag contents] +``` + +## **See Also** + +* [exception](index.md) +* [what](what.md) diff --git a/docs/mkdocs/docs/api/exception/what.md b/docs/mkdocs/docs/api/exception/what.md index 4526d47a..c20fe981 100644 --- a/docs/mkdocs/docs/api/exception/what.md +++ b/docs/mkdocs/docs/api/exception/what.md @@ -6,9 +6,15 @@ const char* what() const noexcept; ``` -Returns an error message for an exception. If nothing, a non-null, empty string will be returned. +Returns an error message for an exception. If nothing, a non-null pointer to an empty string will be returned. -???+ Example +## **Return Value** + +An error message for an exception or a non-null pointer to an empty string. + +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_exception_what.cpp:9" @@ -19,6 +25,6 @@ Returns an error message for an exception. If nothing, a non-null, empty string --8<-- "examples/ex_exception_what.output" ``` -### **See Also** +## **See Also** * [(constructor)](constructor.md) diff --git a/docs/mkdocs/docs/api/index.md b/docs/mkdocs/docs/api/index.md new file mode 100644 index 00000000..a7410848 --- /dev/null +++ b/docs/mkdocs/docs/api/index.md @@ -0,0 +1,18 @@ +# API References + +This section provides fkYAML API references. +Each sub-section contains API specifications and example snippets. + +* Classes + * [basic_node](./basic_node/index.md) + * [exception](./exception/index.md) + * [node_value_converter](./node_value_converter/index.md) + * [ordered_map](./ordered_map/index.md) +* Enumeration Types + * [node_type](./node_type.md) + * [yaml_version_type](./yaml_version_type.md) +* Non-member functions/operators + * [operator"" _yaml](./operator_literal_yaml.md) + * [operator<<(basic_node)](./basic_node/insertion_operator.md) + * [operator>>(basic_node)](./basic_node/extraction_operator.md) +* [Preprocessor Macros](./macros.md) diff --git a/docs/mkdocs/docs/api/macros.md b/docs/mkdocs/docs/api/macros.md index 263bc8a6..30ba0b6e 100644 --- a/docs/mkdocs/docs/api/macros.md +++ b/docs/mkdocs/docs/api/macros.md @@ -14,7 +14,7 @@ These macros are available for client applications as the metadata of this libra | FK_YAML_MINOR_VERSION | the minor version of the fkYAML library | | FK_YAML_PATCH_VERSION | the patch version of the fkYAML library | -??? Example annotate "Example: print the library version" +??? Example "print the library version" ```cpp --8<-- "examples/ex_macros_versions.cpp:9" @@ -42,16 +42,16 @@ You can also override the implementation by defining the following preprocessor | ----------------- | ---------------------------------------- | | FK_YAML_ASSERT(x) | controls behavior of runtime assertions. | -??? Example annotate "Example: disable runtime assertions" +??? Example "disable runtime assertions" ```cpp - #define NDEBUG + #define FK_YAML_ASSERT(x) #include // your code from here ``` -??? Example annotate "Example: override the implementation of runtime assertions" +??? Example "override the implementation of runtime assertions" ```cpp #include @@ -66,7 +66,7 @@ You can also override the implementation by defining the following preprocessor ## Language Supports The fkYAML library targets C++11, but also supports some features introduced in later C++ standards. -For those new features, the library implements some preprocessor checks to determine the active C++ standard based on preprocessor macros `__cplusplus` and `_MSVC_LANG`. +For such features, the library implements some preprocessor checks to determine the active C++ standard based on preprocessor macros `__cplusplus` or `_MSVC_LANG`. By defining any of the following macros, the internal check is overridden and the provided C++ standard is unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and the standard would be detected incorrectly. @@ -78,7 +78,7 @@ This can be helpful for compilers that only implement parts of the standard and | FK_YAML_HAS_CXX_20 | supports C++20 features. | | FK_YAML_HAS_CXX_23 | supports C++23 features. | -??? Example annotate "Example: force the fkYAML library to use a specific C++ standard" +??? Example "force enabling features in specific C++ standard" ```cpp // force fkYAML to use the C++14 standard. diff --git a/docs/mkdocs/docs/api/node_type.md b/docs/mkdocs/docs/api/node_type.md index 24c573de..b72a6b9f 100644 --- a/docs/mkdocs/docs/api/node_type.md +++ b/docs/mkdocs/docs/api/node_type.md @@ -36,7 +36,9 @@ This enumeration collects the different YAML value types. They are internally us * [`basic_node::float_number_type`](basic_node/float_number_type.md) for float number scalar values * [`basic_node::string_type`](basic_node/string_type.md) for string scalar values -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_node_type.cpp:9" @@ -47,7 +49,7 @@ This enumeration collects the different YAML value types. They are internally us --8<-- "examples/ex_node_type.output" ``` -### **See Also** +## **See Also** * [basic_node](basic_node/index.md) * [get_type](basic_node/get_type.md) diff --git a/docs/mkdocs/docs/api/node_value_converter/from_node.md b/docs/mkdocs/docs/api/node_value_converter/from_node.md index 41d98cb9..19500c90 100644 --- a/docs/mkdocs/docs/api/node_value_converter/from_node.md +++ b/docs/mkdocs/docs/api/node_value_converter/from_node.md @@ -1,6 +1,6 @@ Defined in header [``](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node_value_converter.hpp) -# fkyaml::basic_node::from_node +# fkyaml::node_value_converter::from_node ```cpp template @@ -13,12 +13,12 @@ Converts a [`basic_node`](../basic_node/index.md) object to the target native da This function is usually called by the [`get_value()`](../basic_node/get_value.md) function of the [`basic_node`](../basic_node/index.md) class. Note that the `TargetType` must be default-constructible. -!!! Tips +!!! Tips "Customization for non-standard types" This function can be used for user-defined types by implementing (partial) specialization for `from_node()` function which is called internally by this function. - Note that the specialization **must be implemented in the same namespace as the user-defined types (including the global namespace)** so that the specialization can successfully be found by ADL (Argument Dependent Lookup). + Note that the specialization **must be implemented in the same namespace as the user-defined types (including the global namespace)** so that the specialization can successfully be found by [ADL (Argument Dependent Lookup)](https://en.cppreference.com/w/cpp/language/adl). You can find a detailed explanation of how this customization point works at [this link](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4381.html). - Also, see the example below for the feel of how it can be achieved. + Also, see the example below to get the feel of how it can be achieved. ## **Template Parameters** @@ -36,7 +36,13 @@ Note that the `TargetType` must be default-constructible. ***`val`*** [out] : A native data object to which the converted value is assigned. -???+ Example +## **Return Value** + +A value of a compatible type converted from a basic_node. + +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_node_value_converter_from_node.cpp:9" diff --git a/docs/mkdocs/docs/api/node_value_converter/index.md b/docs/mkdocs/docs/api/node_value_converter/index.md index b5d4445b..974b9b52 100644 --- a/docs/mkdocs/docs/api/node_value_converter/index.md +++ b/docs/mkdocs/docs/api/node_value_converter/index.md @@ -9,13 +9,13 @@ class node_value_converter; An ADL friendly converter between [basic_node](../basic_node/index.md) objects and native data objects. -## Template Paramters +## **Template Paramters** | Template parameter | Description | |--------------------|--------------------------------------| | `ValueType` | The default target native data type. | -## Member Functions +## **Member Functions** ### Conversions diff --git a/docs/mkdocs/docs/api/node_value_converter/to_node.md b/docs/mkdocs/docs/api/node_value_converter/to_node.md index 420f808e..91466409 100644 --- a/docs/mkdocs/docs/api/node_value_converter/to_node.md +++ b/docs/mkdocs/docs/api/node_value_converter/to_node.md @@ -1,6 +1,6 @@ Defined in header [``](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/node_value_converter.hpp) -# fkyaml::basic_node::from_node +# fkyaml::node_value_converter::from_node ```cpp template @@ -9,14 +9,14 @@ static auto to_node(BasicNodeType& n, TargetType&& val) noexcept( -> decltype(::fkyaml::to_node(n, std::forward(val))) ``` -Converts a native data to a [`basic_node`](../basic_node/index.md) object. -This function is usually called by the constructors of the [`basic_node`](../basic_node/index.md) class. +Converts a value to a [`basic_node`](../basic_node/index.md) object. +This function is usually called by the [`constructors`](../basic_node/constructor.md) of the [`basic_node`](../basic_node/index.md) class. -!!! Tips +!!! Tips "Customization for non-standard types" This function can be used for user-defined types by implementing (partial) specialization for `to_node()` function which is called internally by this function. - Note that the specialization **must be implemented in the same namespace as the user-defined types** so that the specialization can successfully be found by ADL (Argument Dependent Lookup). - See the example below for more information. + Note that the specialization **must be implemented in the same namespace as the user-defined types** so that the specialization can successfully be found by [ADL (Argument-Dependent Lookup)](https://en.cppreference.com/w/cpp/language/adl). + See the example below to get the feel of how it can be achieved. ## **Template Parameters** @@ -34,7 +34,13 @@ This function is usually called by the constructors of the [`basic_node`](../bas ***`val`*** [in] : A native data object used for conversion. -???+ Example +## **Return Value** + +A basic_node object converted from a value of a compatible type. + +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_node_value_converter_to_node.cpp:9" diff --git a/docs/mkdocs/docs/api/operator_literal_yaml.md b/docs/mkdocs/docs/api/operator_literal_yaml.md index bc8da3c0..da0f36d0 100644 --- a/docs/mkdocs/docs/api/operator_literal_yaml.md +++ b/docs/mkdocs/docs/api/operator_literal_yaml.md @@ -14,10 +14,10 @@ It can be used by adding `#!cpp _yaml` to a string literal encoded in either UTF Calling this operator is equivalent with calling [`#!cpp fkyaml::basic_node::deserialize(s, s + n)`](basic_node/deserialize.md). This operator is declared in the namespace `fkyaml::literals::yaml_literals`, where both `literals` and `yaml_literals` are [inline namespaces](https://en.cppreference.com/w/cpp/language/namespace#Inline_namespaces). -Access to this operator can be gained with: +Access to this operator can therefore be gained with one of the followings: * `#!cpp using namespace fkyaml::literals;`, -* `#!cpp using namespace fkyaml::yaml_literals;`, or +* `#!cpp using namespace fkyaml::yaml_literals;` * `#!cpp using namespace fkyaml::literals::yaml_literals;` ## **Parameters** @@ -33,7 +33,9 @@ Access to this operator can be gained with: The resulting basic_node object deserialized from the input string `s`. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_operator_literal_yaml.cpp:9" diff --git a/docs/mkdocs/docs/api/ordered_map/at.md b/docs/mkdocs/docs/api/ordered_map/at.md index ba052bb1..3b659dee 100644 --- a/docs/mkdocs/docs/api/ordered_map/at.md +++ b/docs/mkdocs/docs/api/ordered_map/at.md @@ -3,19 +3,15 @@ # fkyaml::ordered_map::at ```cpp -template < - typename KeyType, - detail::enable_if_t::value, int> = 0> +template mapped_type& at(KeyType&& key) noexcept; -template < - typename KeyType, - detail::enable_if_t::value, int> = 0> +template const mapped_type& at(KeyType&& key) const ``` Accesses an element with the given key. -This API throws a [`fkyaml::exception`] if the given key does not exist in the ordered_map object. +This function throws a [`fkyaml::exception`] if the given key does not exist in the ordered_map object. ## **Template Parameters** @@ -29,9 +25,11 @@ This API throws a [`fkyaml::exception`] if the given key does not exist in the o ## **Return Value** -Reference, or constant reference, to a `mapped_type` object associated with the given key. +(Constant) reference to a `mapped_type` object associated with the given key. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_ordered_map_at.cpp:9" diff --git a/docs/mkdocs/docs/api/ordered_map/constructor.md b/docs/mkdocs/docs/api/ordered_map/constructor.md index 33498f8a..9517a9c1 100644 --- a/docs/mkdocs/docs/api/ordered_map/constructor.md +++ b/docs/mkdocs/docs/api/ordered_map/constructor.md @@ -11,16 +11,14 @@ ordered_map(std::initializer_list init); // (2) Constructs a new ordered_map. You can specify the initial value on constructing an ordered_map with an overloaded constructor. -## Overload (1) +## **Parameters** -```cpp -ordered_map(); // (1) -``` +***`init`*** [in] +: An initializer list of key-value pairs. -Constructs an ordered_map object without an initial value. -The content of a newly constructed ordered_map is an empty list of key-value pairs. +## **Examples** -???+ Example +??? Example "Overload(1): create a default value." ```cpp --8<-- "examples/ex_ordered_map_constructor_noarg.cpp:9" @@ -31,21 +29,7 @@ The content of a newly constructed ordered_map is an empty list of key-value pai --8<-- "examples/ex_ordered_map_constructor_noarg.output" ``` -## Overload (2) - -```cpp -ordered_map(std::initializer_list init); // (2) -``` - -Constructs a new ordered_map with an initializer list. -The resulting ordered_map object has the same list of key-value pairs as the given initializer list. - -## **Parameters** - -***`init`*** [in] -: An initializer list of key-value pairs. - -???+ Example +??? Example "Overload(2): create an ordered_map object with an initializer list" ```cpp --8<-- "examples/ex_ordered_map_constructor_initializer_list.cpp:9" diff --git a/docs/mkdocs/docs/api/ordered_map/destructor.md b/docs/mkdocs/docs/api/ordered_map/destructor.md index aeb8eef3..0c5568fd 100644 --- a/docs/mkdocs/docs/api/ordered_map/destructor.md +++ b/docs/mkdocs/docs/api/ordered_map/destructor.md @@ -1,6 +1,6 @@ Defined in header [``](https://github.com/fktn-k/fkYAML/blob/develop/include/fkYAML/ordered_map.hpp) -# fkyaml::ordered_map::(constructor) +# fkyaml::ordered_map::(destructor) ```cpp ~ordered_map() = default; diff --git a/docs/mkdocs/docs/api/ordered_map/emplace.md b/docs/mkdocs/docs/api/ordered_map/emplace.md index ebd1c3f4..1e5616a6 100644 --- a/docs/mkdocs/docs/api/ordered_map/emplace.md +++ b/docs/mkdocs/docs/api/ordered_map/emplace.md @@ -3,13 +3,11 @@ # fkyaml::ordered_map::emplace ```cpp -template < - typename KeyType, - detail::enable_if_t::value, int> = 0> +template std::pair emplace(KeyType&& key, const mapped_type& value) noexcept; ``` -Emplaces a new key-value pair if the new key does not exist in the ordered_map object. +Emplaces a new key-value pair if the given key does not exist in the ordered_map object. ***KeyType*** : A type compatible with the key type. @@ -24,9 +22,11 @@ Emplaces a new key-value pair if the new key does not exist in the ordered_map o ## **Return Value** -A pair consisting of an iterator to the inserted element, or the already-existing element if no insertion happend, and a boolean denoting the insertion took place (`true` if insertion happened, `false` otherwise). +A pair consisting of an iterator to the inserted element or the already-existing element, and a boolean denoting the insertion took place (`true` if insertion happened, `false` otherwise). -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_ordered_map_constructor_initializer_list.cpp:9" diff --git a/docs/mkdocs/docs/api/ordered_map/find.md b/docs/mkdocs/docs/api/ordered_map/find.md index ad492b9f..c183c893 100644 --- a/docs/mkdocs/docs/api/ordered_map/find.md +++ b/docs/mkdocs/docs/api/ordered_map/find.md @@ -3,14 +3,10 @@ # fkyaml::ordered_map::find ```cpp -template < - typename KeyType, - detail::enable_if_t::value, int> = 0> +template iterator find(KeyType&& key) noexcept; -template < - typename KeyType, - detail::enable_if_t::value, int> = 0> +template const_iterator find(KeyType&& key) const noexcept; ``` @@ -28,9 +24,11 @@ Find a value with the given key. ## **Return Value** -An iterator to the target value if found, the result of end() otherwise. +A (constant) iterator to the target value if found, the result of end() otherwise. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_ordered_map_emplace.cpp:9" diff --git a/docs/mkdocs/docs/api/ordered_map/index.md b/docs/mkdocs/docs/api/ordered_map/index.md index 60203f41..8b1f9f97 100644 --- a/docs/mkdocs/docs/api/ordered_map/index.md +++ b/docs/mkdocs/docs/api/ordered_map/index.md @@ -19,17 +19,17 @@ This documentation only describes APIs which are not of the parent class [`std:: However, the above recommendation with a sequence of key-value pair does not work so efficiently on the application layer because it cannot be a direct representation of the deserialization result and could also break the original order when the deserialized node is serialized again. The ordered_map class is thus provided to help resolve those issues. -## Template Parameters +## **Template Parameters** -| Template parameter | Description | Derived type | -|--------------------|---------------------------------------------------------|--------------| -| `Key` | type for sequence node value containers | key_type | -| `Value` | type for mapping node value containers | mapped_type | -| `IgnoredCompare` | type for boolean node values | - | -| `Allocator` | type for integer node values | - | +| Template parameter | Description | Derived type | +| ------------------ | ------------------------------------ | ------------ | +| `Key` | type for keys | key_type | +| `Value` | type for values | mapped_type | +| `IgnoredCompare` | placeholder type for key comparisons | - | +| `Allocator` | type for allocators | - | -## Member Types +## **Member Types** | Name | Description | |----------------|-------------------------------------------------| @@ -42,7 +42,7 @@ This documentation only describes APIs which are not of the parent class [`std:: | size_type | The type for size parameters used in the class. | | key_compare | The type for comparison between keys. | -## Member Functions +## **Member Functions** ### Construction/Destruction | Name | Description | diff --git a/docs/mkdocs/docs/api/ordered_map/operator[].md b/docs/mkdocs/docs/api/ordered_map/operator[].md index 7e16c694..5b21b36b 100644 --- a/docs/mkdocs/docs/api/ordered_map/operator[].md +++ b/docs/mkdocs/docs/api/ordered_map/operator[].md @@ -3,9 +3,7 @@ # fkyaml::ordered_map::operator[] ```cpp -template < - typename KeyType, - detail::enable_if_t::value, int> = 0> +template mapped_type& operator[](KeyType&& key) noexcept; ``` @@ -14,8 +12,8 @@ Accesses an element with the given key. !!! Tip This API behaves like the [`std::map`](https://en.cppreference.com/w/cpp/container/map) class does. - In other words, it does not check the existence of the given key, and could return a default value if the key does not exist. - To avoid such a behavior, you can use [`at()`](at.md) function which throws a [`fkyaml::exception`](../exception/index.md) if the given key does not match any keys in the ordered_map object. + In other words, it does not check the existence of the given key, and could create and return a default value if the key does not exist. + To avoid such a behavior, you can use [`at()`](at.md) function which throws a [`fkyaml::exception`](../exception/index.md) if the given key does not exist in the ordered_map object. ## **Template Parameters** @@ -32,7 +30,9 @@ Accesses an element with the given key. Reference to a `mapped_type` object associated with the given key. Possibly a default value of the `mapped_type` if the ordered_map does not contain the given key. -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_ordered_map_subscript_operator.cpp:9" diff --git a/docs/mkdocs/docs/api/yaml_version_type.md b/docs/mkdocs/docs/api/yaml_version_type.md index bba81947..b0069023 100644 --- a/docs/mkdocs/docs/api/yaml_version_type.md +++ b/docs/mkdocs/docs/api/yaml_version_type.md @@ -15,7 +15,9 @@ This enumeration collects the used versions of YAML specification. It is used as * [`get_yaml_version_type()`](basic_node/get_yaml_version_type.md) * [`set_yaml_version_type()`](basic_node/set_yaml_version_type.md) -???+ Example +## **Examples** + +??? Example ```cpp --8<-- "examples/ex_yaml_version_type.cpp:9" @@ -26,7 +28,7 @@ This enumeration collects the used versions of YAML specification. It is used as --8<-- "examples/ex_yaml_version_type.output" ``` -### **See Also** +## **See Also** * [deserialize](basic_node/deserialize.md) * [get_yaml_version_type](basic_node/get_yaml_version_type.md) diff --git a/docs/mkdocs/docs/home/license.md b/docs/mkdocs/docs/home/license.md index a736ba15..50eaec62 100644 --- a/docs/mkdocs/docs/home/license.md +++ b/docs/mkdocs/docs/home/license.md @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2023 Kensuke Fukutani +Copyright (c) 2023-2024 Kensuke Fukutani Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/docs/mkdocs/docs/tutorials/cmake_integration.md b/docs/mkdocs/docs/tutorials/cmake_integration.md index d46f56f8..987f6afb 100644 --- a/docs/mkdocs/docs/tutorials/cmake_integration.md +++ b/docs/mkdocs/docs/tutorials/cmake_integration.md @@ -14,7 +14,7 @@ To use fkYAML from a CMake project, you can locate it directly with [`find_packa Note that this method requires a release package to be installed somewhere on your machine. The package configuration file, `fkYAMLConfig.cmake`, can be used either from an install tree or directly out of the build tree. -???+ Example +??? Example ```cmake title="CMakeLists.txt" cmake_minimum_required(VERSION 3.8) @@ -30,7 +30,7 @@ The package configuration file, `fkYAMLConfig.cmake`, can be used either from an To embed the library directory into an existing CMake project, place the entire source tree in a subdirectory and call [`add_subdirectory()`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html) in your `CMakeLists.txt` file. -???+ Example +??? Example ```cmake title="CMakeLists.txt" cmake_minimum_required(VERSION 3.8) @@ -46,7 +46,7 @@ To embed the library directory into an existing CMake project, place the entire Since CMake v3.11, [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html) is available which automatically downloads a release as a dependency during configuration. -???+ Example +??? Example ```cmake title="CMakeLists.txt" cmake_minimum_required(VERSION 3.11) diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index a2e36482..df61fe58 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -11,186 +11,183 @@ theme: name: material language: en palette: - - media: '(prefers-color-scheme: light)' - scheme: default - primary: teal - accent: green - toggle: - icon: material/brightness-7 - name: Switch to dark mode - - media: '(prefers-color-scheme: dark)' - scheme: slate - primary: blue grey - accent: blue - toggle: - icon: material/brightness-4 - name: Switch to light mode + - media: '(prefers-color-scheme: light)' + scheme: default + primary: teal + accent: green + toggle: + icon: material/brightness-7 + name: Switch to dark mode + - media: '(prefers-color-scheme: dark)' + scheme: slate + primary: blue grey + accent: blue + toggle: + icon: material/brightness-4 + name: Switch to light mode font: text: Roboto code: JetBrains Mono icon: repo: fontawesome/brands/github features: - - navigation.instant - - navigation.tracking - - navigation.tabs - - navigation.indexes - - navigation.top - - content.tabs.link - - content.code.copy - - search.suggest + - navigation.instant + - navigation.tracking + - navigation.tabs + - navigation.indexes + - navigation.top + - content.tabs.link + - content.code.copy + - search.suggest markdown_extensions: - - abbr - - admonition - - attr_list - - def_list - - pymdownx.details - - pymdownx.emoji: - emoji_index: !!python/name:material.extensions.emoji.twemoji - emoji_generator: !!python/name:material.extensions.emoji.to_svg - - pymdownx.highlight: - anchor_linenums: true - line_spans: __span - pygments_lang_class: true - - pymdownx.inlinehilite - - pymdownx.magiclink - - pymdownx.superfences - - pymdownx.tabbed: - alternate_style: true - - pymdownx.tilde - - pymdownx.snippets: - base_path: .. - check_paths: true - - toc: - permalink: true +- abbr +- admonition +- attr_list +- def_list +- pymdownx.details +- pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg +- pymdownx.highlight: + anchor_linenums: true + line_spans: __span + pygments_lang_class: true +- pymdownx.inlinehilite +- pymdownx.magiclink +- pymdownx.superfences +- pymdownx.tabbed: + alternate_style: true +- pymdownx.tilde +- pymdownx.snippets: + base_path: .. + check_paths: true +- toc: + permalink: true extra: social: - - icon: fontawesome/brands/github - link: https://github.com/fktn-k + - icon: fontawesome/brands/github + link: https://github.com/fktn-k generator: false analytics: provider: google property: G-3KS8Y4E3DZ extra_javascript: - - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/hightlight.min.js - - javascripts/config.js +- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/hightlight.min.js +- javascripts/config.js extra_css: - - https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css +- https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.1.1/styles/default.min.css plugins: - - search - - git-revision-date-localized +- search +- git-revision-date-localized nav: - - Home: - - Home: index.md - - License: home/license.md - - Releases: home/releases.md - - Supported Compilers: home/supported_compilers.md - - Community Support: home/community_support.md - - Tutorials: - - The First Steps: tutorials/index.md - - CMake Integration: tutorials/cmake_integration.md - - API References: - - basic_node: - - basic_node: api/basic_node/index.md - - (constructor): api/basic_node/constructor.md - - (destructor): api/basic_node/destructor.md - - operator=: api/basic_node/operator=.md - - add_anchor_name: api/basic_node/add_anchor_name.md - - add_tag_name: api/basic_node/add_tag_name.md - - alias_of: api/basic_node/alias_of.md - - at: api/basic_node/at.md - - begin: api/basic_node/begin.md - - boolean_type: api/basic_node/boolean_type.md - - cbegin: api/basic_node/begin.md - - cend: api/basic_node/end.md - - crbegin: api/basic_node/rbegin.md - - crend: api/basic_node/rend.md - - const_iterator: api/basic_node/iterator.md - - const_reverse_iterator: api/basic_node/reverse_iterator.md - - contains: api/basic_node/contains.md - - deserialize: api/basic_node/deserialize.md - - deserialize_docs: api/basic_node/deserialize_docs.md - - empty: api/basic_node/empty.md - - end: api/basic_node/end.md - - float_number_type: api/basic_node/float_number_type.md - - get_anchor_name: api/basic_node/get_anchor_name.md - - get_tag_name: api/basic_node/get_tag_name.md - - 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_ref: api/basic_node/get_value_ref.md - - get_yaml_version: api/basic_node/get_yaml_version.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 - - integer_type: api/basic_node/integer_type.md - - is_alias: api/basic_node/is_alias.md - - is_anchor: api/basic_node/is_anchor.md - - is_boolean: api/basic_node/is_boolean.md - - is_float_number: api/basic_node/is_float_number.md - - is_integer: api/basic_node/is_integer.md - - is_mapping: api/basic_node/is_mapping.md - - is_null: api/basic_node/is_null.md - - is_scalar: api/basic_node/is_scalar.md - - is_sequence: api/basic_node/is_sequence.md - - is_string: api/basic_node/is_string.md - - iterator: api/basic_node/iterator.md - - mapping_type: api/basic_node/mapping_type.md - - mapping: api/basic_node/mapping.md - - node_t: api/basic_node/node_t.md - - node: api/basic_node/node.md - - rbegin: api/basic_node/rbegin.md - - rend: api/basic_node/rend.md - - reverse_iterator: api/basic_node/reverse_iterator.md - - sequence_type: api/basic_node/sequence_type.md - - sequence: api/basic_node/sequence.md - - serialize: api/basic_node/serialize.md - - serialize_docs: api/basic_node/serialize_docs.md - - set_yaml_version: api/basic_node/set_yaml_version.md - - set_yaml_version_type: api/basic_node/set_yaml_version_type.md - - size: api/basic_node/size.md - - string_type: api/basic_node/string_type.md - - swap: api/basic_node/swap.md - - type: api/basic_node/type.md - - value_converter_type: api/basic_node/value_converter_type.md - - yaml_version_t: api/basic_node/yaml_version_t.md - - operator[]: api/basic_node/operator[].md - - operator==: api/basic_node/operator_eq.md - - operator!=: api/basic_node/operator_ne.md - - operator<: api/basic_node/operator_lt.md - - operator<=: api/basic_node/operator_le.md - - operator>: api/basic_node/operator_gt.md - - operator>=: api/basic_node/operator_ge.md - - exception: - - exception: api/exception/index.md - - (constructor): api/exception/constructor.md - - (destructor): api/exception/destructor.md - - what: api/exception/what.md - - invalid_encoding: api/exception/invalid_encoding.md - - out_of_range: api/exception/out_of_range.md - - parse_error: api/exception/parse_error.md - - type_error: api/exception/type_error.md - - macros: api/macros.md - - node_type: api/node_type.md - - node_value_converter: - - node_value_converter: api/node_value_converter/index.md - - from_node: api/node_value_converter/from_node.md - - to_node: api/node_value_converter/to_node.md - - operator"" _yaml(): api/operator_literal_yaml.md - - operator<<(basic_node): api/basic_node/insertion_operator.md - - operator>>(basic_node): api/basic_node/extraction_operator.md - - ordered_map: - - ordered_map: api/ordered_map/index.md - - (constructor): api/ordered_map/constructor.md - - (destructor): api/ordered_map/destructor.md - - at: api/ordered_map/at.md - - emplace: api/ordered_map/emplace.md - - find: api/ordered_map/find.md - - operator[]: api/ordered_map/operator[].md - - yaml_version_type: api/yaml_version_type.md +- Home: + - Home: index.md + - License: home/license.md + - Releases: home/releases.md + - Supported Compilers: home/supported_compilers.md + - Community Support: home/community_support.md +- Tutorials: + - The First Steps: tutorials/index.md + - CMake Integration: tutorials/cmake_integration.md +- API References: + - API References: api/index.md + - basic_node: + - basic_node: api/basic_node/index.md + - member types: + - sequence_type: api/basic_node/sequence_type.md + - mapping_type: api/basic_node/mapping_type.md + - boolean_type: api/basic_node/boolean_type.md + - integer_type: api/basic_node/integer_type.md + - float_number_type: api/basic_node/float_number_type.md + - string_type: api/basic_node/string_type.md + - 'iterator, const_iterator': api/basic_node/iterator.md + - 'reverse_iterator, const_reverse_iterator': api/basic_node/reverse_iterator.md + - value_converter_type: api/basic_node/value_converter_type.md + - node_t: api/basic_node/node_t.md + - yaml_version_t: api/basic_node/yaml_version_t.md + - (constructor): api/basic_node/constructor.md + - (destructor): api/basic_node/destructor.md + - operators: + - operator=: api/basic_node/operator=.md + - 'operator[]': api/basic_node/operator[].md + - operator==: api/basic_node/operator_eq.md + - operator!=: api/basic_node/operator_ne.md + - operator<: api/basic_node/operator_lt.md + - operator<=: api/basic_node/operator_le.md + - operator>: api/basic_node/operator_gt.md + - operator>=: api/basic_node/operator_ge.md + - add_anchor_name: api/basic_node/add_anchor_name.md + - add_tag_name: api/basic_node/add_tag_name.md + - alias_of: api/basic_node/alias_of.md + - at: api/basic_node/at.md + - 'begin, cbegin': api/basic_node/begin.md + - contains: api/basic_node/contains.md + - deserialize: api/basic_node/deserialize.md + - deserialize_docs: api/basic_node/deserialize_docs.md + - empty: api/basic_node/empty.md + - 'end, cend': api/basic_node/end.md + - get_anchor_name: api/basic_node/get_anchor_name.md + - get_tag_name: api/basic_node/get_tag_name.md + - 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_ref: api/basic_node/get_value_ref.md + - get_yaml_version: api/basic_node/get_yaml_version.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 + - is_alias: api/basic_node/is_alias.md + - is_anchor: api/basic_node/is_anchor.md + - is_boolean: api/basic_node/is_boolean.md + - is_float_number: api/basic_node/is_float_number.md + - is_integer: api/basic_node/is_integer.md + - is_mapping: api/basic_node/is_mapping.md + - is_null: api/basic_node/is_null.md + - is_scalar: api/basic_node/is_scalar.md + - is_sequence: api/basic_node/is_sequence.md + - is_string: api/basic_node/is_string.md + - mapping: api/basic_node/mapping.md + - node: api/basic_node/node.md + - 'rbegin, crbegin': api/basic_node/rbegin.md + - 'rend, crend': api/basic_node/rend.md + - sequence: api/basic_node/sequence.md + - serialize: api/basic_node/serialize.md + - serialize_docs: api/basic_node/serialize_docs.md + - set_yaml_version: api/basic_node/set_yaml_version.md + - set_yaml_version_type: api/basic_node/set_yaml_version_type.md + - size: api/basic_node/size.md + - swap: api/basic_node/swap.md + - type: api/basic_node/type.md + - exception: + - exception: api/exception/index.md + - (constructor): api/exception/constructor.md + - (destructor): api/exception/destructor.md + - what: api/exception/what.md + - invalid_encoding: api/exception/invalid_encoding.md + - out_of_range: api/exception/out_of_range.md + - parse_error: api/exception/parse_error.md + - type_error: api/exception/type_error.md + - node_value_converter: + - node_value_converter: api/node_value_converter/index.md + - from_node: api/node_value_converter/from_node.md + - to_node: api/node_value_converter/to_node.md + - ordered_map: + - ordered_map: api/ordered_map/index.md + - (constructor): api/ordered_map/constructor.md + - (destructor): api/ordered_map/destructor.md + - at: api/ordered_map/at.md + - emplace: api/ordered_map/emplace.md + - find: api/ordered_map/find.md + - 'operator[]': api/ordered_map/operator[].md + - node_type: api/node_type.md + - yaml_version_type: api/yaml_version_type.md + - operator"" _yaml(): api/operator_literal_yaml.md + - operator<<(basic_node): api/basic_node/insertion_operator.md + - operator>>(basic_node): api/basic_node/extraction_operator.md + - macros: api/macros.md diff --git a/docs/mkdocs/requirements.txt b/docs/mkdocs/requirements.txt index 64272a10..9074e9f5 100644 --- a/docs/mkdocs/requirements.txt +++ b/docs/mkdocs/requirements.txt @@ -1,33 +1,34 @@ -Babel==2.14.0 -certifi==2024.2.2 -charset-normalizer==3.3.2 +babel==2.16.0 +certifi==2024.12.14 +charset-normalizer==3.4.0 click==8.1.7 colorama==0.4.6 ghp-import==2.1.0 gitdb==4.0.11 GitPython==3.1.43 -idna==3.7 -Jinja2==3.1.3 -Markdown==3.6 -MarkupSafe==2.1.5 +idna==3.10 +Jinja2==3.1.4 +Markdown==3.7 +MarkupSafe==3.0.2 mergedeep==1.3.4 -mkdocs==1.5.3 -mkdocs-git-revision-date-localized-plugin==1.2.4 -mkdocs-material==9.5.18 +mkdocs==1.6.1 +mkdocs-get-deps==0.2.0 +mkdocs-git-revision-date-localized-plugin==1.3.0 +mkdocs-material==9.5.49 mkdocs-material-extensions==1.3.1 -packaging==24.0 -paginate==0.5.6 +packaging==24.2 +paginate==0.5.7 pathspec==0.12.1 -platformdirs==4.2.0 -Pygments==2.17.2 -pymdown-extensions==10.7.1 +platformdirs==4.3.6 +Pygments==2.18.0 +pymdown-extensions==10.12 python-dateutil==2.9.0.post0 -pytz==2024.1 -PyYAML==6.0.1 +pytz==2024.2 +PyYAML==6.0.2 pyyaml_env_tag==0.1 -regex==2024.4.16 -requests==2.31.0 -six==1.16.0 +regex==2024.11.6 +requests==2.32.3 +six==1.17.0 smmap==5.0.1 -urllib3==2.2.1 -watchdog==4.0.0 +urllib3==2.2.3 +watchdog==6.0.0 diff --git a/include/fkYAML/exception.hpp b/include/fkYAML/exception.hpp index 1fa614be..f3b353a7 100644 --- a/include/fkYAML/exception.hpp +++ b/include/fkYAML/exception.hpp @@ -113,8 +113,13 @@ class invalid_encoding : public exception { }; /// @brief An exception class indicating an error in parsing. +/// @sa https://fktn-k.github.io/fkYAML/api/exception/parse_error/ class parse_error : public exception { public: + /// @brief Constructs a new parse_error object with an error message and counts of lines and colums at the error. + /// @param[in] msg An error message. + /// @param[in] lines Count of lines. + /// @param[in] cols_in_line Count of colums. explicit parse_error(const char* msg, uint32_t lines, uint32_t cols_in_line) noexcept : exception(generate_error_message(msg, lines, cols_in_line).c_str()) { } @@ -155,12 +160,18 @@ class type_error : public exception { } }; +/// @brief An exception class indicating an out-of-range error. +/// @sa https://fktn-k.github.io/fkYAML/api/exception/out_of_range/ class out_of_range : public exception { public: + /// @brief Construct a new out_of_range object with an invalid index value. + /// @param[in] index An invalid index value. explicit out_of_range(int index) noexcept : exception(generate_error_message(index).c_str()) { } + /// @brief Construct a new out_of_range object with invalid key contents. + /// @param[in] key Invalid key contents explicit out_of_range(const char* key) noexcept : exception(generate_error_message(key).c_str()) { } @@ -175,8 +186,13 @@ class out_of_range : public exception { } }; +/// @brief An exception class indicating an invalid tag. +/// @sa https://fktn-k.github.io/fkYAML/api/exception/invalid_tag/ class invalid_tag : public exception { public: + /// @brief Constructs a new invalid_tag object with an error message and invalid tag contents. + /// @param[in] msg An error message. + /// @param[in] tag Invalid tag contents. explicit invalid_tag(const char* msg, const char* tag) : exception(generate_error_message(msg, tag).c_str()) { } diff --git a/include/fkYAML/ordered_map.hpp b/include/fkYAML/ordered_map.hpp index 6051d07c..ccf1c936 100644 --- a/include/fkYAML/ordered_map.hpp +++ b/include/fkYAML/ordered_map.hpp @@ -32,21 +32,36 @@ template < typename Allocator = std::allocator>> class ordered_map : public std::vector, Allocator> { public: - /// A type for keys. + /// @brief A type for keys. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using key_type = Key; - /// A type for values. + + /// @brief A type for values. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using mapped_type = Value; - /// A type for internal key-value containers. + + /// @brief A type for internal key-value containers. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using Container = std::vector, Allocator>; - /// A type for key-value pairs. + + /// @brief A type for key-value pairs. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using value_type = typename Container::value_type; - /// A type for non-const iterators. + + /// @brief A type for non-const iterators. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using iterator = typename Container::iterator; - /// A type for const iterators. + + /// @brief A type for const iterators. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using const_iterator = typename Container::const_iterator; - /// A type for size parameters used in this class. + + /// @brief A type for size parameters used in this class. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using size_type = typename Container::size_type; - /// A type for comparison between keys. + + /// @brief A type for comparison between keys. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using key_compare = std::equal_to; public: diff --git a/single_include/fkYAML/node.hpp b/single_include/fkYAML/node.hpp index 925b4138..3f38c26e 100644 --- a/single_include/fkYAML/node.hpp +++ b/single_include/fkYAML/node.hpp @@ -1692,8 +1692,13 @@ class invalid_encoding : public exception { }; /// @brief An exception class indicating an error in parsing. +/// @sa https://fktn-k.github.io/fkYAML/api/exception/parse_error/ class parse_error : public exception { public: + /// @brief Constructs a new parse_error object with an error message and counts of lines and colums at the error. + /// @param[in] msg An error message. + /// @param[in] lines Count of lines. + /// @param[in] cols_in_line Count of colums. explicit parse_error(const char* msg, uint32_t lines, uint32_t cols_in_line) noexcept : exception(generate_error_message(msg, lines, cols_in_line).c_str()) { } @@ -1734,12 +1739,18 @@ class type_error : public exception { } }; +/// @brief An exception class indicating an out-of-range error. +/// @sa https://fktn-k.github.io/fkYAML/api/exception/out_of_range/ class out_of_range : public exception { public: + /// @brief Construct a new out_of_range object with an invalid index value. + /// @param[in] index An invalid index value. explicit out_of_range(int index) noexcept : exception(generate_error_message(index).c_str()) { } + /// @brief Construct a new out_of_range object with invalid key contents. + /// @param[in] key Invalid key contents explicit out_of_range(const char* key) noexcept : exception(generate_error_message(key).c_str()) { } @@ -1754,8 +1765,13 @@ class out_of_range : public exception { } }; +/// @brief An exception class indicating an invalid tag. +/// @sa https://fktn-k.github.io/fkYAML/api/exception/invalid_tag/ class invalid_tag : public exception { public: + /// @brief Constructs a new invalid_tag object with an error message and invalid tag contents. + /// @param[in] msg An error message. + /// @param[in] tag Invalid tag contents. explicit invalid_tag(const char* msg, const char* tag) : exception(generate_error_message(msg, tag).c_str()) { } @@ -12095,21 +12111,36 @@ template < typename Allocator = std::allocator>> class ordered_map : public std::vector, Allocator> { public: - /// A type for keys. + /// @brief A type for keys. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using key_type = Key; - /// A type for values. + + /// @brief A type for values. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using mapped_type = Value; - /// A type for internal key-value containers. + + /// @brief A type for internal key-value containers. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using Container = std::vector, Allocator>; - /// A type for key-value pairs. + + /// @brief A type for key-value pairs. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using value_type = typename Container::value_type; - /// A type for non-const iterators. + + /// @brief A type for non-const iterators. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using iterator = typename Container::iterator; - /// A type for const iterators. + + /// @brief A type for const iterators. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using const_iterator = typename Container::const_iterator; - /// A type for size parameters used in this class. + + /// @brief A type for size parameters used in this class. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using size_type = typename Container::size_type; - /// A type for comparison between keys. + + /// @brief A type for comparison between keys. + /// @sa https://fktn-k.github.io/fkYAML/api/ordered_map/ using key_compare = std::equal_to; public: