mirror of
https://github.com/ToruNiina/toml11.git
synced 2025-09-17 09:08:08 +08:00
440 lines
108 KiB
HTML
440 lines
108 KiB
HTML
<!doctype html><html lang=en dir=ltr><head><meta charset=UTF-8><meta name=viewport content="width=device-width,initial-scale=1"><meta name=description content="
|
|
Retrieving Values
|
|
#
|
|
|
|
This section explains how to access the values stored in toml::value.
|
|
|
|
Accessing Values Using Member Functions
|
|
#
|
|
|
|
|
|
is_something and as_something
|
|
#
|
|
|
|
toml::value has member functions like is_boolean() and is_integer() which allow you to check the type of the stored value.
|
|
Additionally, it has member functions like as_boolean() and as_integer() that allow you to access the value of that type.
|
|
For a complete list, refer to the toml::value reference."><meta name=theme-color media="(prefers-color-scheme: light)" content="#ffffff"><meta name=theme-color media="(prefers-color-scheme: dark)" content="#343a40"><meta name=color-scheme content="light dark"><meta property="og:url" content="https://toruniina.github.io/toml11/docs/features/value/"><meta property="og:site_name" content="toml11"><meta property="og:title" content="getting values"><meta property="og:description" content="Retrieving Values # This section explains how to access the values stored in toml::value.
|
|
Accessing Values Using Member Functions # is_something and as_something # toml::value has member functions like is_boolean() and is_integer() which allow you to check the type of the stored value.
|
|
Additionally, it has member functions like as_boolean() and as_integer() that allow you to access the value of that type.
|
|
For a complete list, refer to the toml::value reference."><meta property="og:locale" content="en"><meta property="og:type" content="article"><meta property="article:section" content="docs"><title>getting values | toml11</title>
|
|
<link rel=manifest href=/toml11/manifest.json><link rel=icon href=/toml11/favicon.png><link rel=canonical href=https://toruniina.github.io/toml11/docs/features/value/><link rel=alternate hreflang=ja href=https://toruniina.github.io/toml11/ja/docs/features/value/ title="getting values"><link rel=stylesheet href=/toml11/book.min.ddac3efe7ea4c1007ff53e5a8fd67f12517e5d2e99984d8c67a18668f7ecaa03.css integrity="sha256-3aw+/n6kwQB/9T5aj9Z/ElF+XS6ZmE2MZ6GGaPfsqgM=" crossorigin=anonymous><script defer src=/toml11/fuse.min.js></script><script defer src=/toml11/en.search.min.db4a558804ac41f081539588cec8e4a415587801da466728166bb5341dd62411.js integrity="sha256-20pViASsQfCBU5WIzsjkpBVYeAHaRmcoFmu1NB3WJBE=" crossorigin=anonymous></script></head><body dir=ltr><input type=checkbox class="hidden toggle" id=menu-control>
|
|
<input type=checkbox class="hidden toggle" id=toc-control><main class="container flex"><aside class=book-menu><div class=book-menu-content><nav><h2 class=book-brand><a class="flex align-center" href=/toml11/><span>toml11</span></a></h2><div class="book-search hidden"><input type=text id=book-search-input placeholder=Search aria-label=Search maxlength=64 data-hotkeys=s/><div class="book-search-spinner hidden"></div><ul id=book-search-results></ul></div><script>document.querySelector(".book-search").classList.remove("hidden")</script><ul class=book-languages><li><input type=checkbox id=languages class=toggle>
|
|
<label for=languages class="flex justify-between"><a role=button class="flex align-center"><img src=/toml11/svg/translate.svg class=book-icon alt=Languages>
|
|
English</a></label><ul><li><a href=https://toruniina.github.io/toml11/ja/docs/features/value/>日本語</a></li></ul></li></ul><ul><li><a href=/toml11/docs/installation/>installation</a><ul></ul></li><li><input type=checkbox id=section-291123c850af98d8b815ccdbb4c33657 class=toggle checked>
|
|
<label for=section-291123c850af98d8b815ccdbb4c33657 class="flex justify-between"><a href=/toml11/docs/features/>features</a></label><ul><li><a href=/toml11/docs/features/parsing_files/>parsing files</a></li><li><a href=/toml11/docs/features/value/ class=active>getting values</a></li><li><a href=/toml11/docs/features/error_message/>error message</a></li><li><a href=/toml11/docs/features/serialize/>serializing values</a></li><li><a href=/toml11/docs/features/configure_types/>configuring types</a></li><li><a href=/toml11/docs/features/literal/>toml literal</a></li><li><a href=/toml11/docs/features/toml_spec/>toml spec</a></li><li><a href=/toml11/docs/features/extension/>extension</a></li></ul></li><li><input type=checkbox id=section-e2e812e55021b82e114feaae98f1a02e class=toggle>
|
|
<label for=section-e2e812e55021b82e114feaae98f1a02e class="flex justify-between"><a href=/toml11/docs/reference/>reference</a></label><ul><li><a href=/toml11/docs/reference/color/>color.hpp</a></li><li><a href=/toml11/docs/reference/comments/>comments.hpp</a></li><li><a href=/toml11/docs/reference/conversion/>conversion.hpp</a></li><li><a href=/toml11/docs/reference/datetime/>datetime.hpp</a></li><li><a href=/toml11/docs/reference/error_info/>error_info.hpp</a></li><li><a href=/toml11/docs/reference/exception/>exception.hpp</a></li><li><a href=/toml11/docs/reference/find/>find.hpp</a></li><li><a href=/toml11/docs/reference/format/>format.hpp</a></li><li><a href=/toml11/docs/reference/from/>from.hpp</a></li><li><a href=/toml11/docs/reference/get/>get.hpp</a></li><li><a href=/toml11/docs/reference/into/>into.hpp</a></li><li><a href=/toml11/docs/reference/literal/>literal.hpp</a></li><li><a href=/toml11/docs/reference/ordered_map/>ordered_map.hpp</a></li><li><a href=/toml11/docs/reference/parser/>parser.hpp</a></li><li><a href=/toml11/docs/reference/result/>result.hpp</a></li><li><a href=/toml11/docs/reference/serializer/>serializer.hpp</a></li><li><a href=/toml11/docs/reference/source_location/>source_location.hpp</a></li><li><a href=/toml11/docs/reference/spec/>spec.hpp</a></li><li><a href=/toml11/docs/reference/toml_fwd/>toml_fwd.hpp</a></li><li><a href=/toml11/docs/reference/toml/>toml.hpp</a></li><li><a href=/toml11/docs/reference/types/>types.hpp</a></li><li><a href=/toml11/docs/reference/value_t/>value_t.hpp</a></li><li><a href=/toml11/docs/reference/value/>value.hpp</a></li><li><a href=/toml11/docs/reference/version/>version.hpp</a></li><li><a href=/toml11/docs/reference/visit/>visit.hpp</a></li></ul></li><li><a href=/toml11/docs/changelog/>changelog</a><ul></ul></li></ul><ul><li><a href=https://github.com/ToruNiina/toml11 target=_blank rel=noopener>GitHub</a></li></ul></nav><script>(function(){var e=document.querySelector("aside .book-menu-content");addEventListener("beforeunload",function(){localStorage.setItem("menu.scrollTop",e.scrollTop)}),e.scrollTop=localStorage.getItem("menu.scrollTop")})()</script></div></aside><div class=book-page><header class=book-header><div class="flex align-center justify-between"><label for=menu-control><img src=/toml11/svg/menu.svg class=book-icon alt=Menu>
|
|
</label><strong>getting values</strong>
|
|
<label for=toc-control><img src=/toml11/svg/toc.svg class=book-icon alt="Table of Contents"></label></div><aside class="hidden clearfix"><nav id=TableOfContents><ul><li><a href=#retrieving-values>Retrieving Values</a><ul><li><a href=#accessing-values-using-member-functions>Accessing Values Using Member Functions</a><ul><li><a href=#is_something-and-as_something><code>is_something</code> and <code>as_something</code></a></li><li><a href=#tomlvalue_t><code>toml::value_t</code></a></li><li><a href=#at--contains-size-push_back-emplace_back><code>at</code>, <code>[]</code>, <code>contains</code>, <code>size</code>, <code>push_back</code>, <code>emplace_back</code></a></li></ul></li><li><a href=#accessing-comments>Accessing Comments</a></li><li><a href=#handling-inline-tables-and-dotted-keys>Handling Inline Tables and Dotted Keys</a></li><li><a href=#handling-date-and-time-information>Handling Date and Time Information</a></li><li><a href=#converting-using-tomlgett>Converting Using <code>toml::get<T></code></a><ul><li><a href=#simple-conversions>Simple Conversions</a></li><li><a href=#conditions-for-obtaining-references>Conditions for Obtaining References</a></li><li><a href=#converting-arrays-to-stl-containers>Converting Arrays to STL Containers</a></li><li><a href=#converting-arrays-to-stdpair-or-stdtuple>Converting Arrays to <code>std::pair</code> or <code>std::tuple</code></a></li><li><a href=#converting-nested-arrays>Converting Nested Arrays</a></li><li><a href=#converting-tables-to-stdmap>Converting Tables to <code>std::map</code></a></li></ul></li><li><a href=#using-tomlget_or-to-specify-a-value-on-failure>Using <code>toml::get_or</code> to Specify a Value on Failure</a></li><li><a href=#using-tomlfindt-to-search-and-convert-simultaneously>Using <code>toml::find<T></code> to Search and Convert Simultaneously</a></li><li><a href=#using-tomlfind_or-to-search-and-specify-a-value-on-failure>Using <code>toml::find_or</code> to Search and Specify a Value on Failure</a></li><li><a href=#using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>Using <code>toml::find_or_default</code> to Search and Use the Default Value on Failure</a></li><li><a href=#tomlfindstdoptionalt><code>toml::find<std::optional<T>></code></a></li><li><a href=#defining-conversions-for-user-defined-types>Defining Conversions for User-Defined Types</a><ul><li><a href=#defining-tomlfrom>Defining <code>toml::from</code></a></li><li><a href=#defining-a-from_toml-member-function>Defining a <code>from_toml</code> Member Function</a></li><li><a href=#constructor-accepting-tomlvalue>Constructor Accepting <code>toml::value</code></a></li></ul></li><li><a href=#applying-functions-with-tomlvisit>Applying Functions with <code>toml::visit</code></a></li><li><a href=#constructing-tomlvalue>Constructing <code>toml::value</code></a></li><li><a href=#converting-to-tomlvalue>Converting to <code>toml::value</code></a><ul><li><a href=#defining-tomlinto>Defining <code>toml::into</code></a></li><li><a href=#defining-into_toml-member-function>Defining <code>into_toml</code> Member Function</a></li></ul></li></ul></li><li><a href=#checking-whether-a-value-has-been-accessed>Checking Whether a Value Has Been Accessed</a></li></ul></nav></aside></header><article class="markdown book-article"><h1 id=retrieving-values>Retrieving Values
|
|
<a class=anchor href=#retrieving-values>#</a></h1><p>This section explains how to access the values stored in <code>toml::value</code>.</p><h2 id=accessing-values-using-member-functions>Accessing Values Using Member Functions
|
|
<a class=anchor href=#accessing-values-using-member-functions>#</a></h2><h3 id=is_something-and-as_something><code>is_something</code> and <code>as_something</code>
|
|
<a class=anchor href=#is_something-and-as_something>#</a></h3><p><code>toml::value</code> has member functions like <code>is_boolean()</code> and <code>is_integer()</code> which allow you to check the type of the stored value.</p><p>Additionally, it has member functions like <code>as_boolean()</code> and <code>as_integer()</code> that allow you to access the value of that type.</p><p>For a complete list, refer to the <a href=https://toruniina.github.io/toml11/docs/reference/value/#is_xxx><code>toml::value</code> reference</a>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/* ... */</span>;
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(v.is_string())
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> v.as_string() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
|
</span></span><span style=display:flex><span>}
|
|
</span></span></code></pre></div><p>If the stored value is of a different type than specified, a <a href=https://toruniina.github.io/toml11/docs/reference/value/#tomltype_error><code>toml::type_error</code></a> is thrown.</p><p>The <code>what()</code> method will contain a message like the following:</p><pre tabindex=0><code>[error] toml::value::as_string(): bad_cast to string
|
|
--> input.toml
|
|
|
|
|
1 | a = 123_456
|
|
| ^^^^^^^-- the actual type is integer
|
|
</code></pre><h3 id=tomlvalue_t><code>toml::value_t</code>
|
|
<a class=anchor href=#tomlvalue_t>#</a></h3><p>Type information can be identified using <a href=https://toruniina.github.io/toml11/docs/reference/value_t/><code>enum class toml::value_t</code></a>.</p><p>The <a href=https://toruniina.github.io/toml11/docs/reference/value/#type><code>type()</code></a> member function returns the type information of the currently stored value.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/* ... */</span>;
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>switch</span>(v.type())
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>empty : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>boolean : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>integer : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>floating : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>string : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>offset_datetime: { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>local_datetime : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>local_date : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>local_time : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>array : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml:value_t<span style=color:#f92672>::</span>table : { <span style=color:#75715e>/*...*/</span> <span style=color:#66d9ef>break</span>; }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>default</span><span style=color:#f92672>:</span> {<span style=color:#66d9ef>break</span>;}
|
|
</span></span><span style=display:flex><span>}
|
|
</span></span></code></pre></div><p>The <a href=https://toruniina.github.io/toml11/docs/reference/value/#istomlvalue_t><code>is(toml::value_t)</code></a> member function returns <code>true</code> if the stored value is of the given <code>value_t</code> type, otherwise it returns <code>false</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/* ... */</span>;
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>if</span>(v.is(toml<span style=color:#f92672>::</span>value_t<span style=color:#f92672>::</span>integer))
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> v.as_integer() <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
|
</span></span><span style=display:flex><span>}
|
|
</span></span></code></pre></div><h3 id=at--contains-size-push_back-emplace_back><code>at</code>, <code>[]</code>, <code>contains</code>, <code>size</code>, <code>push_back</code>, <code>emplace_back</code>
|
|
<a class=anchor href=#at--contains-size-push_back-emplace_back>#</a></h3><p><code>toml::value</code> provides some member functions similar to those of standard library containers.</p><p>These functions internally convert <code>toml::value</code> to the corresponding type and call the respective member functions.</p><h4 id=atstdsize_t-i-operatorstdsize_t-i><code>at(std::size_t i)</code>, <code>operator[](std::size_t i)</code>
|
|
<a class=anchor href=#atstdsize_t-i-operatorstdsize_t-i>#</a></h4><p>These are equivalent to <code>as_array().at(i)</code> and <code>as_array()[i]</code>.</p><p><code>toml::value</code> uses <code>std::vector<toml::value></code> as <code>array_type</code> by default, so <code>at</code> throws <code>std::out_of_range</code> on error, while <code>operator[]</code> results in undefined behavior.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>array{<span style=color:#ae81ff>1</span>,<span style=color:#ae81ff>2</span>,<span style=color:#ae81ff>3</span>});
|
|
</span></span><span style=display:flex><span>std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> v.at(<span style=color:#ae81ff>1</span>);
|
|
</span></span></code></pre></div><p>If the stored type is not <code>array_type</code>, a <code>type_error</code> is thrown.</p><h4 id=atstdstring-key-operatorstdstring-key><code>at(std::string key)</code>, <code>operator[](std::string key)</code>
|
|
<a class=anchor href=#atstdstring-key-operatorstdstring-key>#</a></h4><p>These are equivalent to <code>as_table().at(key)</code> and <code>as_table()[key]</code>.</p><p><code>toml::value</code> uses <code>std::unordered_map<std::string, toml::value></code> as <code>table_type</code> by default, so if the corresponding value does not exist, <code>at</code> throws <code>std::out_of_range</code>, while <code>operator[]</code> constructs a new <code>toml::value</code> and returns a reference to it. Therefore, there is no <code>const</code> version of <code>operator[]</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>table{});
|
|
</span></span><span style=display:flex><span>v[<span style=color:#e6db74>"a"</span>] <span style=color:#f92672>=</span> <span style=color:#ae81ff>42</span>;
|
|
</span></span></code></pre></div><p>If the stored type is not <code>table_type</code>, a <code>type_error</code> is thrown.</p><h4 id=size><code>size()</code>
|
|
<a class=anchor href=#size>#</a></h4><p>Returns the length.</p><p>For <code>array_type</code> or <code>table_type</code>, it returns the number of elements; for <code>string_type</code>, it returns the number of characters (in bytes).</p><p>If the stored type is none of these, a <code>type_error</code> is thrown.</p><h4 id=push_back-emplace_back><code>push_back()</code>, <code>emplace_back()</code>
|
|
<a class=anchor href=#push_back-emplace_back>#</a></h4><p>These are equivalent to <code>as_array().push_back()</code> and <code>as_array().emplace_back()</code>.</p><p>If the stored type is not <code>array_type</code>, a <code>type_error</code> is thrown.</p><h2 id=accessing-comments>Accessing Comments
|
|
<a class=anchor href=#accessing-comments>#</a></h2><p>In toml11, comments are parsed by default and saved line by line with the corresponding value.</p><p>A comment corresponds to the value that comes immediately after the consecutive lines of comments, or to the value on the same line as the comment.</p><p>If there is no value immediately before or after the comment, it is not associated with any value and is ignored.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># input.toml</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This is a comment about a.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>3.14</span> <span style=color:#75715e># This is a comment about b.</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This comment is ignored because it has no corresponding value.</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This is the 1st comment about c.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This is the 2nd comment about c.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span> <span style=color:#75715e># This is the final comment about c.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This comment is NOT a comment about c.</span>
|
|
</span></span></code></pre></div><p>Comments corresponding to a value can be accessed using the <code>comments()</code> member function of <code>toml::value</code>.</p><p><code>comments()</code> returns a container that has the same member functions as <code>std::vector<std::string></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> v <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> a <span style=color:#f92672>=</span> v.at(<span style=color:#e6db74>"a"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> b <span style=color:#f92672>=</span> v.at(<span style=color:#e6db74>"b"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> c <span style=color:#f92672>=</span> v.at(<span style=color:#e6db74>"c"</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>assert(a.comments().size() <span style=color:#f92672>==</span> <span style=color:#ae81ff>1</span>);
|
|
</span></span><span style=display:flex><span>assert(a.comments().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is a comment about a."</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>assert(b.comments().size() <span style=color:#f92672>==</span> <span style=color:#ae81ff>1</span>);
|
|
</span></span><span style=display:flex><span>assert(b.comments().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is a comment about b."</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>assert(c.comments().size() <span style=color:#f92672>==</span> <span style=color:#ae81ff>3</span>);
|
|
</span></span><span style=display:flex><span>assert(c.comments().at(<span style=color:#ae81ff>0</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is the 1st comment about c."</span>);
|
|
</span></span><span style=display:flex><span>assert(c.comments().at(<span style=color:#ae81ff>1</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is the 2nd comment about c."</span>);
|
|
</span></span><span style=display:flex><span>assert(c.comments().at(<span style=color:#ae81ff>2</span>) <span style=color:#f92672>==</span> <span style=color:#e6db74>"# This is the final comment about c."</span>);
|
|
</span></span></code></pre></div><p>Comments related to the root table of the entire file are written at the beginning of the file.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># This is a comment about the root table.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This is also a comment about the root table.</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This comment is ignored.</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This is a comment about a.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
|
</span></span></code></pre></div><p>However, if a value immediately follows the initial comment, the comment is interpreted as pertaining to that value, and there are no comments for the root table.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># This is a comment about a.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This is also a comment about a.</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>42</span>
|
|
</span></span></code></pre></div><h2 id=handling-inline-tables-and-dotted-keys>Handling Inline Tables and Dotted Keys
|
|
<a class=anchor href=#handling-inline-tables-and-dotted-keys>#</a></h2><p>An inline table is simply a table, and there is no difference in handling it compared to other tables in C++ code.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>42</span>, <span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span>}
|
|
</span></span></code></pre></div><p>Dotted keys are also just tables, with no difference in handling compared to other tables in C++ code.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span>.<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>42</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>a</span>.<span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span>
|
|
</span></span></code></pre></div><p>These TOML files are identical to the following file.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span>[<span style=color:#a6e22e>a</span>]
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>42</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>c</span> = <span style=color:#e6db74>"foo"</span>
|
|
</span></span></code></pre></div><p>Thus, they can all be processed with the exact same code.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"a"</span>).at(<span style=color:#e6db74>"b"</span>).as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>42</span>);
|
|
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"a"</span>).at(<span style=color:#e6db74>"c"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"foo"</span>);
|
|
</span></span></code></pre></div><p>However, it is possible to distinguish them based on format information.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>switch</span>(input.at(<span style=color:#e6db74>"a"</span>).as_table_fmt().fmt)
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml<span style=color:#f92672>::</span>table_format<span style=color:#f92672>::</span>oneline:
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> <span style=color:#e6db74>"inline table"</span> <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>break</span>;
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml<span style=color:#f92672>::</span>table_format<span style=color:#f92672>::</span>multiline:
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> <span style=color:#e6db74>"normal table"</span> <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>break</span>;
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>case</span> toml<span style=color:#f92672>::</span>table_format<span style=color:#f92672>::</span>dotted:
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> <span style=color:#e6db74>"dotted keys"</span> <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>break</span>;
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>}
|
|
</span></span></code></pre></div><p>This format information is also considered during serialization, which will be described later.</p><h2 id=handling-date-and-time-information>Handling Date and Time Information
|
|
<a class=anchor href=#handling-date-and-time-information>#</a></h2><p><a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_date><code>local_date</code></a>,
|
|
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_time><code>local_time</code></a>,
|
|
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_datetime><code>local_datetime</code></a>, and
|
|
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#offset_datetime><code>offset_datetime</code></a>
|
|
are parsed into dedicated structures with corresponding member variables in toml11.</p><p>When using these, you can directly extract the values or use <code>toml::get</code> and <code>toml::find</code> to convert them into types such as <code>std::chrono::system_clock::time_point</code> or <code>std::tm</code>.</p><h2 id=converting-using-tomlgett>Converting Using <code>toml::get<T></code>
|
|
<a class=anchor href=#converting-using-tomlgett>#</a></h2><p><code>toml::get<T></code> is a function that converts and retrieves the value stored in <code>toml::value</code>.
|
|
Specify the desired target type as <code>T</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value v <span style=color:#f92672>=</span> <span style=color:#75715e>/*...*/</span>;
|
|
</span></span><span style=display:flex><span>std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl;
|
|
</span></span></code></pre></div><p>The <code>toml::find<T></code> function, described later, also has the same functionality for type conversion.</p><p>If an unsupported type is specified for the stored value, a <code>toml::type_error</code> is thrown.</p><h3 id=simple-conversions>Simple Conversions
|
|
<a class=anchor href=#simple-conversions>#</a></h3><h4 id=boolean_type>boolean_type
|
|
<a class=anchor href=#boolean_type>#</a></h4><p>Conversion from <code>boolean_type</code> is possible only to <code>bool</code>.</p><h4 id=integer_type>integer_type
|
|
<a class=anchor href=#integer_type>#</a></h4><p>Any type for which <code>std::is_integral<T></code> is <code>true</code>, except <code>bool</code>, can be converted from <code>integer_type</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>42</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> u32 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span><span style=color:#66d9ef>uint32_t</span><span style=color:#f92672>></span>(v);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> i16 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>short</span><span style=color:#f92672>></span>(v);
|
|
</span></span></code></pre></div><h4 id=floating_type>floating_type
|
|
<a class=anchor href=#floating_type>#</a></h4><p>Any type for which <code>std::is_floating_point<T></code> is <code>true</code> can be converted from <code>floating_type</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>3.14</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> f64 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>double</span><span style=color:#f92672>></span>(v);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> f32 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span><span style=color:#66d9ef>float</span> <span style=color:#f92672>></span>(v);
|
|
</span></span></code></pre></div><h4 id=string_type>string_type
|
|
<a class=anchor href=#string_type>#</a></h4><p><code>string_type</code> can be converted to <code>std::string</code>.
|
|
From C++17 onwards, it can also be converted to <code>std::string_view</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#e6db74>"foo"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> s <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e>// C++17
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> sv <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string_view<span style=color:#f92672>></span>(v);
|
|
</span></span></code></pre></div><h4 id=datetime-variants>datetime variants
|
|
<a class=anchor href=#datetime-variants>#</a></h4><p><a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_date><code>local_date</code></a>,
|
|
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_datetime><code>local_datetime</code></a>, and
|
|
<a href=https://toruniina.github.io/toml11/docs/reference/datetime/#offset_datetime><code>offset_datetime</code></a> represent specific dates and times,
|
|
so they can be converted to <code>std::chrono::system_clock::time_point</code>.</p><p>However, since <a href=https://toruniina.github.io/toml11/docs/reference/datetime/#local_time><code>local_time</code></a> does not include date information, it supports conversion to <code>std::chrono::duration</code> as the elapsed time from <code>00:00.00</code>.</p><p>Additionally, <code>local_date</code> and <code>local_datetime</code> conversions take the executing machine’s timezone into account.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>date</span> = <span style=color:#ae81ff>2024-01-23</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>time</span> = <span style=color:#ae81ff>12</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>30</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>00</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>l_dt</span> = <span style=color:#ae81ff>2024-01-23</span><span style=color:#a6e22e>T12</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>30</span><span style=color:#960050;background-color:#1e0010>:</span><span style=color:#ae81ff>00</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>o_dt</span> = <span style=color:#e6db74>2024-01-23T12:30:00+09:00</span>
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> date <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>system_clock<span style=color:#f92672>::</span>time_point<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"date"</span>));
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> l_dt <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>system_clock<span style=color:#f92672>::</span>time_point<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"l_dt"</span>));
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> o_dt <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>system_clock<span style=color:#f92672>::</span>time_point<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"o_dt"</span>));
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> time <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>chrono<span style=color:#f92672>::</span>minutes<span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"time"</span>)); <span style=color:#75715e>// 12 * 60 + 30 min
|
|
</span></span></span></code></pre></div><h3 id=conditions-for-obtaining-references>Conditions for Obtaining References
|
|
<a class=anchor href=#conditions-for-obtaining-references>#</a></h3><p><code>toml::get<T></code> can return a reference if <code>T</code> is the exact type stored in <code>toml::value</code>.</p><p>Conversely, if a conversion is necessary (e.g., extracting an integer stored as <code>std::int64_t</code> into <code>std::uint32_t</code>), it is not possible to return a reference to the converted type.</p><p>When no conversion is needed, the returned reference can be used to modify the value.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>42</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>integer_type<span style=color:#f92672>></span>(v) <span style=color:#f92672>=</span> <span style=color:#ae81ff>6</span> <span style=color:#f92672>*</span> <span style=color:#ae81ff>9</span>;
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>assert(v.as_integer() <span style=color:#f92672>==</span> <span style=color:#ae81ff>54</span>);
|
|
</span></span></code></pre></div><h3 id=converting-arrays-to-stl-containers>Converting Arrays to STL Containers
|
|
<a class=anchor href=#converting-arrays-to-stl-containers>#</a></h3><p>If all elements in an array have the same type and can be converted to <code>T</code>, it is possible to convert them to <code>std::vector<T></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>, <span style=color:#ae81ff>4</span>, <span style=color:#ae81ff>5</span>]
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span></code></pre></div><p>Other STL containers can also be used.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a1 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>deque<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a2 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>list <span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a3 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>array<span style=color:#f92672><</span><span style=color:#66d9ef>int</span>, <span style=color:#ae81ff>5</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span></code></pre></div><p>When converting to <code>std::array</code>, the number of elements must match. If they don’t match, a <code>std::out_of_range</code> exception is thrown.</p><p>Non-STL containers that have a default constructor and a <code>push_back</code> method can also be converted using <code>toml::get</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>boost<span style=color:#f92672>::</span>container<span style=color:#f92672>::</span>small_vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span>, <span style=color:#ae81ff>8</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span></code></pre></div><h3 id=converting-arrays-to-stdpair-or-stdtuple>Converting Arrays to <code>std::pair</code> or <code>std::tuple</code>
|
|
<a class=anchor href=#converting-arrays-to-stdpair-or-stdtuple>#</a></h3><p>If an array contains elements of different types, it can be converted to <code>std::pair</code> or <code>std::tuple</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [<span style=color:#66d9ef>true</span>, <span style=color:#ae81ff>3.14</span>]
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>b</span> = [<span style=color:#ae81ff>42</span>, <span style=color:#ae81ff>2.718</span>, <span style=color:#e6db74>"foo"</span>]
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>pair<span style=color:#f92672><</span><span style=color:#66d9ef>bool</span>, <span style=color:#66d9ef>double</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>tuple<span style=color:#f92672><</span><span style=color:#66d9ef>int</span>, <span style=color:#66d9ef>double</span>, std<span style=color:#f92672>::</span>string<span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"b"</span>));
|
|
</span></span></code></pre></div><p>As with <code>std::array</code>, the length of the array must match the number of elements in the <code>std::pair</code> or <code>std::tuple</code>. If they don’t match, a <code>std::out_of_range</code> exception is thrown.</p><p>Additionally, each element must be convertible to the corresponding element in the <code>std::pair</code> or <code>std::tuple</code>. If conversion is not possible, a <code>toml::type_error</code> exception is thrown.</p><h3 id=converting-nested-arrays>Converting Nested Arrays
|
|
<a class=anchor href=#converting-nested-arrays>#</a></h3><p>Nested arrays can be converted to nested containers.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [ [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>], [<span style=color:#ae81ff>4</span>, <span style=color:#ae81ff>5</span>, <span style=color:#ae81ff>6</span>] ]
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span></code></pre></div><p>If the types are different, <code>std::pair</code> or <code>std::tuple</code> can be useful.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [ [<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>], [<span style=color:#e6db74>"foo"</span>, <span style=color:#e6db74>"bar"</span>] ]
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>pair<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>, std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>>></span>
|
|
</span></span><span style=display:flex><span> <span style=color:#f92672>></span>(input.at(<span style=color:#e6db74>"a"</span>));
|
|
</span></span></code></pre></div><h3 id=converting-tables-to-stdmap>Converting Tables to <code>std::map</code>
|
|
<a class=anchor href=#converting-tables-to-stdmap>#</a></h3><p>If all values in a table have the same type, they can be converted to <code>std::map</code> or <code>std::unordered_map</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>t</span> = {<span style=color:#a6e22e>a</span> = <span style=color:#ae81ff>1</span>, <span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>2</span>}
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> t <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>map<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string, <span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"t"</span>));
|
|
</span></span></code></pre></div><p>Non-STL containers that have a default constructor and an <code>emplace(key, mapped)</code> method can also be converted using <code>toml::get</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> t <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get<span style=color:#f92672><</span>boost<span style=color:#f92672>::</span>container<span style=color:#f92672>::</span>flat_map<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string, <span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input.at(<span style=color:#e6db74>"t"</span>));
|
|
</span></span></code></pre></div><p>If the conversion of any element fails, a <code>toml::type_error</code> exception is thrown.</p><h2 id=using-tomlget_or-to-specify-a-value-on-failure>Using <code>toml::get_or</code> to Specify a Value on Failure
|
|
<a class=anchor href=#using-tomlget_or-to-specify-a-value-on-failure>#</a></h2><p><code>toml::get</code> throws a <code>toml::type_error</code> exception if the conversion fails.</p><p>By using <code>toml::get_or</code>, you can specify a default value to return instead of an exception in case of a conversion failure.</p><p>Unlike <code>toml::get<T></code>, <code>get_or</code> infers the target type from the arguments, so there is no need to specify <code><T></code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get_or(input.at(<span style=color:#e6db74>"a"</span>), <span style=color:#ae81ff>42</span>);
|
|
</span></span></code></pre></div><p>The types that can be converted are the same as for <code>toml::get</code>.</p><p>If you specify <code>toml::value::xxx_type</code>, you can also retrieve a reference, but in that case, the argument must also be a reference.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>integer_type a_default <span style=color:#f92672>=</span> <span style=color:#ae81ff>42</span>;
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>auto</span> a<span style=color:#f92672>&</span> <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>get_or(input.at(<span style=color:#e6db74>"a"</span>), a_default);
|
|
</span></span></code></pre></div><h2 id=using-tomlfindt-to-search-and-convert-simultaneously>Using <code>toml::find<T></code> to Search and Convert Simultaneously
|
|
<a class=anchor href=#using-tomlfindt-to-search-and-convert-simultaneously>#</a></h2><p><code>toml::find<T></code> is a function that searches for a value in a <code>toml::value</code> holding a table and simultaneously performs the same type conversion as <code>toml::get</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = toml::get<int>(input.at("a"));
|
|
</span></span></span></code></pre></div><p><code>toml::find<T></code> can also be used with arrays.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> input.at(<span style=color:#e6db74>"a"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a2 <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(a, <span style=color:#ae81ff>2</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a2 = toml::get<int>(input.at("a").at(2));
|
|
</span></span></span></code></pre></div><p>If an error occurs during type conversion, <code>toml::find<T></code> throws the same <code>toml::type_error</code> as <code>toml::get</code>.
|
|
If the key is not found or the index does not exist, it throws <code>std::out_of_range</code>.</p><p>If no type is specified, <code>toml::find</code> returns a <code>toml::value</code> without type conversion.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find(input, <span style=color:#e6db74>"a"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = input.at("a");
|
|
</span></span></span></code></pre></div><p><code>toml::find<T></code> can access values recursively.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = {<span style=color:#a6e22e>b</span> = {<span style=color:#a6e22e>c</span> = <span style=color:#ae81ff>42</span>}}
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a_b_c <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>, <span style=color:#e6db74>"b"</span>, <span style=color:#e6db74>"c"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = toml::get<int>(input.at("a").at("b").at("c"));
|
|
</span></span></span></code></pre></div><p>You can mix keys and indexes.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#a6e22e>a</span> = [ {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>1</span>}, {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>2</span>}, {<span style=color:#a6e22e>b</span> = <span style=color:#ae81ff>3</span>} ]
|
|
</span></span></code></pre></div><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a_2_b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>, <span style=color:#ae81ff>2</span>, <span style=color:#e6db74>"b"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#75715e>// Equivalent to: const auto a = toml::get<int>(input.at("a").at(2).at("c"));
|
|
</span></span></span></code></pre></div><blockquote class="book-hint info"><p>TOML supports a feature called quoted keys, which allows using normally disallowed characters in keys by enclosing them in <code>""</code> or <code>''</code>. Within quoted keys, <code>.</code> does <strong>not</strong> introduce tables.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#e6db74>"127.0.0.1"</span> = <span style=color:#e6db74>"value"</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>site</span>.<span style=color:#e6db74>"google.com"</span> = <span style=color:#66d9ef>true</span>
|
|
</span></span></code></pre></div><p>You can read this TOML file as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse(<span style=color:#e6db74>"input.toml"</span>);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"127.0.0.1"</span>).as_string() <span style=color:#f92672>==</span> <span style=color:#e6db74>"value"</span>);
|
|
</span></span><span style=display:flex><span>assert(input.at(<span style=color:#e6db74>"site"</span>).at(<span style=color:#e6db74>"google.com"</span>).as_boolean());
|
|
</span></span></code></pre></div><p>To handle such cases seamlessly, toml11 does not automatically split keys containing <code>.</code>. Explicitly specifying the table hierarchy helps in structuring the input file correctly.</p><p>Reference: <a href=https://toml.io/en/v1.0.0#key>toml.io/Key</a></p></blockquote><h2 id=using-tomlfind_or-to-search-and-specify-a-value-on-failure>Using <code>toml::find_or</code> to Search and Specify a Value on Failure
|
|
<a class=anchor href=#using-tomlfind_or-to-search-and-specify-a-value-on-failure>#</a></h2><p><code>toml::find_or</code> works similarly to <code>toml::find<T></code>, but allows specifying a default value to return if the search or conversion fails.</p><p>This is useful when you want to provide a fallback value instead of handling exceptions.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find_or(input, <span style=color:#e6db74>"a"</span>, <span style=color:#ae81ff>42</span>);
|
|
</span></span></code></pre></div><h2 id=using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>Using <code>toml::find_or_default</code> to Search and Use the Default Value on Failure
|
|
<a class=anchor href=#using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>#</a></h2><p><code>toml::find_or_default</code> works similarly to <code>toml::find_or<T></code> but returns the default constructor result if the search or conversion fails.</p><p>This is useful when you want to use the default value instead of handling exceptions, especially when the default construction is costly, as this delays it until the actual failure happens.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find_or(input, <span style=color:#e6db74>"a"</span>, expensive()); <span style=color:#75715e>// ctor is called before the function call
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find_or_default<span style=color:#f92672><</span>expensive<span style=color:#f92672>></span>(input, <span style=color:#e6db74>"a"</span>); <span style=color:#75715e>// ctor will be called only on failure
|
|
</span></span></span></code></pre></div><h2 id=tomlfindstdoptionalt><code>toml::find<std::optional<T>></code>
|
|
<a class=anchor href=#tomlfindstdoptionalt>#</a></h2><p>If <code>std::optional</code> is available, you can specify <code>std::optional</code> as a template argument of <code>toml::find</code>.</p><p>Recursive access is also supported.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> input <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>parse_str(R<span style=color:#e6db74>"(</span>
|
|
</span></span><span style=display:flex><span>integer <span style=color:#f92672>=</span> <span style=color:#ae81ff>1</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>[table]
|
|
</span></span><span style=display:flex><span>key <span style=color:#f92672>=</span> <span style=color:#ae81ff>2</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>[[array-of-tables]]</span>
|
|
</span></span><span style=display:flex><span>key <span style=color:#f92672>=</span> <span style=color:#ae81ff>3</span>
|
|
</span></span><span style=display:flex><span>)<span style=color:#e6db74>");</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>optional<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input, <span style=color:#e6db74>"integer"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>optional<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input, <span style=color:#e6db74>"table"</span>, <span style=color:#e6db74>"key"</span>);
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> c <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>optional<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>>></span>(input, <span style=color:#e6db74>"array-of-tables"</span>, <span style=color:#ae81ff>0</span>, <span style=color:#e6db74>"key"</span>);
|
|
</span></span></code></pre></div><p>If a key does not exist, no exception is thrown, and <code>std::nullopt</code> is returned.</p><p>However, if a type conversion fails, or if you attempt to access a key on a value that is not a table, or an index on a value that is not an array, a <code>toml::type_error</code> is thrown.</p><h2 id=defining-conversions-for-user-defined-types>Defining Conversions for User-Defined Types
|
|
<a class=anchor href=#defining-conversions-for-user-defined-types>#</a></h2><p>With <code>toml::get</code> and <code>toml::find</code>, you can use user-defined types by employing one of the following methods.</p><h3 id=defining-tomlfrom>Defining <code>toml::from</code>
|
|
<a class=anchor href=#defining-tomlfrom>#</a></h3><p>In toml11, there is a <code>toml::from</code> type that supports conversions from user-defined types by specializing it as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>namespace</span> toml
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>template</span><span style=color:#f92672><></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>from</span><span style=color:#f92672><</span>extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>></span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> extlib<span style=color:#f92672>::</span>foo from_toml(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> v)
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> extlib<span style=color:#f92672>::</span>foo{
|
|
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>),
|
|
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>)
|
|
</span></span><span style=display:flex><span> };
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// toml
|
|
</span></span></span></code></pre></div><p>If you also want to support <code>toml::value</code> with a modified type configuration, do as follows:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>namespace</span> toml
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>template</span><span style=color:#f92672><></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>from</span><span style=color:#f92672><</span>extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>></span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> TC<span style=color:#f92672>></span>
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> extlib<span style=color:#f92672>::</span>foo from_toml(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>>&</span> v)
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> extlib<span style=color:#f92672>::</span>foo{
|
|
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>),
|
|
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>)
|
|
</span></span><span style=display:flex><span> };
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// toml
|
|
</span></span></span></code></pre></div><p>This definition can be automatically generated using <code>TOML11_DEFINE_CONVERSION_NON_INTRUSIVE</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
|
</span></span><span style=display:flex><span>TOML11_DEFINE_CONVERSION_NON_INTRUSIVE(extlib<span style=color:#f92672>::</span>foo, a, b)
|
|
</span></span></code></pre></div><p>Alternatively, you can use a reflection library. Refer to the sample in <code>example</code> using <code>boost-ext/reflect</code>.</p><h3 id=defining-a-from_toml-member-function>Defining a <code>from_toml</code> Member Function
|
|
<a class=anchor href=#defining-a-from_toml-member-function>#</a></h3><p>You can also define a conversion by defining a <code>from_toml</code> member function.</p><p>When using this method, a default constructor is required.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>bar</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>void</span> <span style=color:#a6e22e>from_toml</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> v)
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>a <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>);
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>b <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>);
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> ;
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span></code></pre></div><p>If both are defined, <code>toml::from</code> takes precedence.</p><h3 id=constructor-accepting-tomlvalue>Constructor Accepting <code>toml::value</code>
|
|
<a class=anchor href=#constructor-accepting-tomlvalue>#</a></h3><p>If there is a constructor that accepts <code>toml::value</code>, conversion via <code>toml::get</code> can be performed.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>baz</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>explicit</span> <span style=color:#a6e22e>baz</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> v)
|
|
</span></span><span style=display:flex><span> <span style=color:#f92672>:</span> a(toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span><span style=color:#66d9ef>int</span><span style=color:#f92672>></span>(v, <span style=color:#e6db74>"a"</span>)), b(toml<span style=color:#f92672>::</span>find<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string<span style=color:#f92672>></span>(v, <span style=color:#e6db74>"b"</span>))
|
|
</span></span><span style=display:flex><span> {}
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span></code></pre></div><p>If both are defined, <code>toml::from</code> and <code>from_toml</code> take precedence.</p><h2 id=applying-functions-with-tomlvisit>Applying Functions with <code>toml::visit</code>
|
|
<a class=anchor href=#applying-functions-with-tomlvisit>#</a></h2><p>If you have a function object that can be applied to all types stored in <code>toml::value</code>, you can directly call that function without type conversion using <code>toml::visit</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>type_name_of</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>boolean_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"boolean"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>integer_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"integer"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>floating_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"floating"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>string_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"string"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>local_time_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"local_time"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>local_date_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"local_date"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>local_datetime_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"local_datetime"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>offset_datetime_type<span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"offset_datetime"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>array_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"array"</span>;}
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string <span style=color:#66d9ef>operator</span>()(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>::</span>table_type <span style=color:#f92672>&</span>) <span style=color:#66d9ef>const</span> {<span style=color:#66d9ef>return</span> <span style=color:#e6db74>"table"</span>;}
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(<span style=color:#ae81ff>3.14</span>);
|
|
</span></span><span style=display:flex><span>std<span style=color:#f92672>::</span>cout <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>visit(type_name_of{}, v) <span style=color:#f92672><<</span> std<span style=color:#f92672>::</span>endl; <span style=color:#75715e>// floating
|
|
</span></span></span></code></pre></div><h2 id=constructing-tomlvalue>Constructing <code>toml::value</code>
|
|
<a class=anchor href=#constructing-tomlvalue>#</a></h2><p><code>toml::value</code> can be constructed not only internally by the parser but also in user code.</p><p>You can construct it by passing a type that is either the same as or convertible to the types stored in <code>toml::value</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v1(true);
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v2(<span style=color:#ae81ff>42</span>);
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v3(<span style=color:#ae81ff>3.14</span>);
|
|
</span></span></code></pre></div><p>For arrays, you can use <code>toml::array</code>:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>array{<span style=color:#ae81ff>1</span>, <span style=color:#ae81ff>2</span>, <span style=color:#ae81ff>3</span>});
|
|
</span></span></code></pre></div><p>Alternatively, you can pass containers such as <code>std::vector</code> directly:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>vector<span style=color:#f92672><</span>toml<span style=color:#f92672>::</span>value<span style=color:#f92672>></span> a{<span style=color:#ae81ff>1</span>,<span style=color:#ae81ff>2</span>,<span style=color:#ae81ff>3</span>};
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(a);
|
|
</span></span></code></pre></div><p>For tables, you can use <code>toml::table</code>:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(toml<span style=color:#f92672>::</span>table{{<span style=color:#e6db74>"foo"</span>, <span style=color:#ae81ff>1</span>}, {<span style=color:#e6db74>"bar"</span>, <span style=color:#ae81ff>2</span>}, {<span style=color:#e6db74>"baz"</span>, <span style=color:#ae81ff>3</span>}});
|
|
</span></span></code></pre></div><p>Or pass containers such as <code>std::map</code> directly:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>const</span> std<span style=color:#f92672>::</span>map<span style=color:#f92672><</span>std<span style=color:#f92672>::</span>string, toml<span style=color:#f92672>::</span>value<span style=color:#f92672>></span> t{
|
|
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"foo"</span>, <span style=color:#ae81ff>1</span>}, {<span style=color:#e6db74>"bar"</span>, <span style=color:#ae81ff>2</span>}, {<span style=color:#e6db74>"baz"</span>, <span style=color:#ae81ff>3</span>}
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v(t);
|
|
</span></span></code></pre></div><p>You can pass <code>format_info</code> and comments to the constructor.</p><p>The type of comments is <code>std::vector<std::string></code>.
|
|
Each element corresponds to a line.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span>toml<span style=color:#f92672>::</span>integer_format_info fmt;
|
|
</span></span><span style=display:flex><span>fmt.fmt <span style=color:#f92672>=</span> toml<span style=color:#f92672>::</span>integer_format<span style=color:#f92672>::</span>hex;
|
|
</span></span><span style=display:flex><span>fmt.spacer <span style=color:#f92672>=</span> <span style=color:#ae81ff>4</span>;
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v1(<span style=color:#ae81ff>0xDEADBEEF</span>, fmt);
|
|
</span></span><span style=display:flex><span>toml<span style=color:#f92672>::</span>value v2(<span style=color:#ae81ff>0xC0FFEE</span>, fmt, {<span style=color:#e6db74>"hex value!"</span>});
|
|
</span></span></code></pre></div><h2 id=converting-to-tomlvalue>Converting to <code>toml::value</code>
|
|
<a class=anchor href=#converting-to-tomlvalue>#</a></h2><p>When constructing <code>toml::value</code> from user-defined types, you can customize the behavior by defining <code>toml::into</code> or <code>into_toml</code>.</p><p><code>toml::into</code> is particularly useful when converting types from other libraries.</p><h3 id=defining-tomlinto>Defining <code>toml::into</code>
|
|
<a class=anchor href=#defining-tomlinto>#</a></h3><p>By specializing <code>toml::into</code>, you can enable conversions to <code>toml::value</code>.</p><p>This is useful for types from external libraries that do not provide a conversion to <code>toml::value</code>.</p><p>Since <code>toml::value</code> passes <code>type_config</code> during conversion, you need to accept the <code>template</code> argument of <code>basic_value</code>.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>namespace</span> extlib
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>foo</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// extlib
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>template</span><span style=color:#f92672><></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>into</span><span style=color:#f92672><</span>extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>></span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> TC<span style=color:#f92672>></span>
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>static</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span> into_toml(<span style=color:#66d9ef>const</span> extlib<span style=color:#f92672>::</span>foo<span style=color:#f92672>&</span> f)
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span>(<span style=color:#66d9ef>typename</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>>::</span>table_type{{<span style=color:#e6db74>"a"</span>, f.a}, {<span style=color:#e6db74>"b"</span>, f.b}});
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span></code></pre></div><h3 id=defining-into_toml-member-function>Defining <code>into_toml</code> Member Function
|
|
<a class=anchor href=#defining-into_toml-member-function>#</a></h3><p>Similar to <code>from_toml</code>, you can define the conversion through a member function.</p><p>If <code>toml::into</code> is defined, it takes precedence.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#66d9ef>struct</span> <span style=color:#a6e22e>bar</span>
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>int</span> a;
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>string b;
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>template</span><span style=color:#f92672><</span><span style=color:#66d9ef>typename</span> TC<span style=color:#f92672>></span>
|
|
</span></span><span style=display:flex><span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span> into_toml() <span style=color:#66d9ef>const</span>
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>></span>(<span style=color:#66d9ef>typename</span> toml<span style=color:#f92672>::</span>basic_value<span style=color:#f92672><</span>TC<span style=color:#f92672>>::</span>table_type{
|
|
</span></span><span style=display:flex><span> {<span style=color:#e6db74>"a"</span>, <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>a}, {<span style=color:#e6db74>"b"</span>, <span style=color:#66d9ef>this</span><span style=color:#f92672>-></span>b}
|
|
</span></span><span style=display:flex><span> });
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span>};
|
|
</span></span></code></pre></div><h1 id=checking-whether-a-value-has-been-accessed>Checking Whether a Value Has Been Accessed
|
|
<a class=anchor href=#checking-whether-a-value-has-been-accessed>#</a></h1><p>When compiled with the <code>TOML11_ENABLE_ACCESS_CHECK</code> macro defined, the <code>toml::value</code> class gains an additional method: <code>bool accessed() const</code>.
|
|
This allows you to check whether a value has been accessed after parsing.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ g++ -std<span style=color:#f92672>=</span>c++17 -O2 -DTOML11_ENABLE_ACCESS_CHECK -I/path/to/toml11/include main.cpp
|
|
</span></span></code></pre></div><p>or</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-console data-lang=console><span style=display:flex><span>$ cmake -B ./build -DTOML11_ENABLE_ACCESS_CHECK<span style=color:#f92672>=</span>ON
|
|
</span></span></code></pre></div><p>or</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cmake data-lang=cmake><span style=display:flex><span>CPMAddPackage(
|
|
</span></span><span style=display:flex><span> <span style=color:#e6db74>NAME</span> <span style=color:#e6db74>toml11</span>
|
|
</span></span><span style=display:flex><span> <span style=color:#e6db74>GITHUB_REPOSITORY</span> <span style=color:#e6db74>"ToruNiina/toml11"</span>
|
|
</span></span><span style=display:flex><span> <span style=color:#e6db74>VERSION</span> <span style=color:#e6db74>4.4.0</span>
|
|
</span></span><span style=display:flex><span> <span style=color:#e6db74>OPTIONS</span> <span style=color:#e6db74>"CMAKE_CXX_STANDARD 17"</span> <span style=color:#e6db74>"TOML11_PRECOMPILE ON"</span> <span style=color:#e6db74>"TOML11_ENABLE_ACCESS_CHECK ON"</span>
|
|
</span></span><span style=display:flex><span> )<span style=color:#960050;background-color:#1e0010>
|
|
</span></span></span></code></pre></div><p>This feature allows users to implement code that warns about values defined in a table but never used.</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-cpp data-lang=cpp><span style=display:flex><span><span style=color:#75715e>#include</span> <span style=color:#75715e><toml.hpp></span><span style=color:#75715e>
|
|
</span></span></span><span style=display:flex><span><span style=color:#75715e></span>
|
|
</span></span><span style=display:flex><span><span style=color:#66d9ef>namespace</span> yours
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span>Config <span style=color:#a6e22e>read_config</span>(<span style=color:#66d9ef>const</span> toml<span style=color:#f92672>::</span>value<span style=color:#f92672>&</span> input)
|
|
</span></span><span style=display:flex><span>{
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span> cfg <span style=color:#f92672>=</span> read_your_config(input);
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>for</span> (<span style=color:#66d9ef>const</span> <span style=color:#66d9ef>auto</span><span style=color:#f92672>&</span> [k, v] <span style=color:#f92672>:</span> input.as_table())
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>if</span> (<span style=color:#f92672>!</span>v.accessed())
|
|
</span></span><span style=display:flex><span> {
|
|
</span></span><span style=display:flex><span> std<span style=color:#f92672>::</span>cerr <span style=color:#f92672><<</span> toml<span style=color:#f92672>::</span>format_error(<span style=color:#e6db74>"value defined but not used"</span>,
|
|
</span></span><span style=display:flex><span> v.source_location(), <span style=color:#e6db74>"not used"</span>);
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span> }
|
|
</span></span><span style=display:flex><span> <span style=color:#66d9ef>return</span> cfg;
|
|
</span></span><span style=display:flex><span>}
|
|
</span></span><span style=display:flex><span>} <span style=color:#75715e>// namespace yours
|
|
</span></span></span></code></pre></div><p>This feature is useful when a value is mistakenly defined under the wrong name but is never accessed. For example:</p><div class=highlight><pre tabindex=0 style=color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4><code class=language-toml data-lang=toml><span style=display:flex><span><span style=color:#75715e># The correct key is "reactions"</span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># reactions = [ ":+1:", "star" ]</span>
|
|
</span></span><span style=display:flex><span>
|
|
</span></span><span style=display:flex><span><span style=color:#75715e># This key is incorrect and will not be read</span>
|
|
</span></span><span style=display:flex><span><span style=color:#a6e22e>reaction</span> = [ <span style=color:#e6db74>":+1:"</span>, <span style=color:#e6db74>"star"</span> ]
|
|
</span></span></code></pre></div><p>If this file is read using the above code, <code>read_your_config</code> will search for <code>reactions</code>. Since it is not defined, it will process <code>reactions</code> as an empty array.
|
|
In this case, <code>input.at("reaction").accessed()</code> will be <code>false</code>, allowing it to be detected as an error.</p></article><footer class=book-footer><div class="flex flex-wrap justify-between"></div><script>(function(){function e(e){const t=window.getSelection(),n=document.createRange();n.selectNodeContents(e),t.removeAllRanges(),t.addRange(n)}document.querySelectorAll("pre code").forEach(t=>{t.addEventListener("click",function(){if(window.getSelection().toString())return;e(t.parentElement),navigator.clipboard&&navigator.clipboard.writeText(t.parentElement.textContent)})})})()</script></footer><label for=menu-control class="hidden book-menu-overlay"></label></div><aside class=book-toc><div class=book-toc-content><nav id=TableOfContents><ul><li><a href=#retrieving-values>Retrieving Values</a><ul><li><a href=#accessing-values-using-member-functions>Accessing Values Using Member Functions</a><ul><li><a href=#is_something-and-as_something><code>is_something</code> and <code>as_something</code></a></li><li><a href=#tomlvalue_t><code>toml::value_t</code></a></li><li><a href=#at--contains-size-push_back-emplace_back><code>at</code>, <code>[]</code>, <code>contains</code>, <code>size</code>, <code>push_back</code>, <code>emplace_back</code></a></li></ul></li><li><a href=#accessing-comments>Accessing Comments</a></li><li><a href=#handling-inline-tables-and-dotted-keys>Handling Inline Tables and Dotted Keys</a></li><li><a href=#handling-date-and-time-information>Handling Date and Time Information</a></li><li><a href=#converting-using-tomlgett>Converting Using <code>toml::get<T></code></a><ul><li><a href=#simple-conversions>Simple Conversions</a></li><li><a href=#conditions-for-obtaining-references>Conditions for Obtaining References</a></li><li><a href=#converting-arrays-to-stl-containers>Converting Arrays to STL Containers</a></li><li><a href=#converting-arrays-to-stdpair-or-stdtuple>Converting Arrays to <code>std::pair</code> or <code>std::tuple</code></a></li><li><a href=#converting-nested-arrays>Converting Nested Arrays</a></li><li><a href=#converting-tables-to-stdmap>Converting Tables to <code>std::map</code></a></li></ul></li><li><a href=#using-tomlget_or-to-specify-a-value-on-failure>Using <code>toml::get_or</code> to Specify a Value on Failure</a></li><li><a href=#using-tomlfindt-to-search-and-convert-simultaneously>Using <code>toml::find<T></code> to Search and Convert Simultaneously</a></li><li><a href=#using-tomlfind_or-to-search-and-specify-a-value-on-failure>Using <code>toml::find_or</code> to Search and Specify a Value on Failure</a></li><li><a href=#using-tomlfind_or_default-to-search-and-use-the-default-value-on-failure>Using <code>toml::find_or_default</code> to Search and Use the Default Value on Failure</a></li><li><a href=#tomlfindstdoptionalt><code>toml::find<std::optional<T>></code></a></li><li><a href=#defining-conversions-for-user-defined-types>Defining Conversions for User-Defined Types</a><ul><li><a href=#defining-tomlfrom>Defining <code>toml::from</code></a></li><li><a href=#defining-a-from_toml-member-function>Defining a <code>from_toml</code> Member Function</a></li><li><a href=#constructor-accepting-tomlvalue>Constructor Accepting <code>toml::value</code></a></li></ul></li><li><a href=#applying-functions-with-tomlvisit>Applying Functions with <code>toml::visit</code></a></li><li><a href=#constructing-tomlvalue>Constructing <code>toml::value</code></a></li><li><a href=#converting-to-tomlvalue>Converting to <code>toml::value</code></a><ul><li><a href=#defining-tomlinto>Defining <code>toml::into</code></a></li><li><a href=#defining-into_toml-member-function>Defining <code>into_toml</code> Member Function</a></li></ul></li></ul></li><li><a href=#checking-whether-a-value-has-been-accessed>Checking Whether a Value Has Been Accessed</a></li></ul></nav></div></aside></main></body></html> |