1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> 2<html> 3<head> 4<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 5<title>How to Access Data in a Property Tree</title> 6<link rel="stylesheet" href="../../../doc/src/boostbook.css" type="text/css"> 7<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 8<link rel="home" href="../index.html" title="The Boost C++ Libraries BoostBook Documentation Subset"> 9<link rel="up" href="../property_tree.html" title="Chapter 31. Boost.PropertyTree"> 10<link rel="prev" href="parsers.html" title="How to Populate a Property Tree"> 11<link rel="next" href="appendices.html" title="Appendices"> 12</head> 13<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 14<table cellpadding="2" width="100%"><tr> 15<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../boost.png"></td> 16<td align="center"><a href="../../../index.html">Home</a></td> 17<td align="center"><a href="../../../libs/libraries.htm">Libraries</a></td> 18<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td> 19<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td> 20<td align="center"><a href="../../../more/index.htm">More</a></td> 21</tr></table> 22<hr> 23<div class="spirit-nav"> 24<a accesskey="p" href="parsers.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../property_tree.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="appendices.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 25</div> 26<div class="section"> 27<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28<a name="property_tree.accessing"></a><a class="link" href="accessing.html" title="How to Access Data in a Property Tree">How to Access Data in a Property 29 Tree</a> 30</h2></div></div></div> 31<p> 32 Property tree resembles (almost is) a standard container with value type of 33 <code class="computeroutput"><span class="identifier">pair</span><span class="special"><</span><span class="identifier">string</span><span class="special">,</span> <span class="identifier">ptree</span><span class="special">></span></code>. 34 It has the usual member functions, such as <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_17-bb">insert</a></code>, 35 <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_22-bb">push_back</a></code>, 36 <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_34-bb">find</a></code>, 37 <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_19-bb">erase</a></code>, 38 etc. These can of course be used to populate and access the tree. For example 39 the following code adds key <code class="computeroutput"><span class="string">"pi"</span></code> 40 with data (almost) equal to mathematical <span class="emphasis"><em>pi</em></span> value: 41 </p> 42<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> <span class="identifier">pt</span><span class="special">;</span> 43<span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_22-bb">push_back</a></code><span class="special">(</span><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code><span class="special">::</span><code class="computeroutput">value_type</code><span class="special">(</span><span class="string">"pi"</span><span class="special">,</span> <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code><span class="special">(</span><span class="string">"3.14159"</span><span class="special">)));</span> 44</pre> 45<p> 46 To find the value of <code class="computeroutput"><span class="identifier">pi</span></code> we 47 might do the following: 48 </p> 49<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code><span class="special">::</span><code class="computeroutput">const_iterator</code> <span class="identifier">it</span> <span class="special">=</span> <span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_34-bb">find</a></code><span class="special">(</span><span class="string">"pi"</span><span class="special">);</span> 50<span class="keyword">double</span> <span class="identifier">pi</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">lexical_cast</span><span class="special"><</span><span class="keyword">double</span><span class="special">>(</span><span class="identifier">it</span><span class="special">-></span><span class="identifier">second</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_42-bb">data</a></code><span class="special">());</span> 51</pre> 52<p> 53 This looks quite cumbersome, and would be even more so if <code class="computeroutput"><span class="identifier">pi</span></code> 54 value was not stored so near the top of the tree, and we cared just a little 55 bit more about errors. Fortunately, there is another, correct way of doing 56 it: 57 </p> 58<pre class="programlisting"><span class="identifier">ptree</span> <span class="identifier">pt</span><span class="special">;</span> 59<span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code><span class="special">(</span><span class="string">"pi"</span><span class="special">,</span> <span class="number">3.14159</span><span class="special">);</span> <span class="comment">// put double</span> 60<span class="keyword">double</span> <span class="identifier">pi</span> <span class="special">=</span> <span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code><span class="special"><</span><span class="keyword">double</span><span class="special">>(</span><span class="string">"pi"</span><span class="special">);</span> <span class="comment">// get double</span> 61</pre> 62<p> 63 It doesn't get simpler than that. Basically, there are 2 families of member 64 functions, <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code> 65 and <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code>, 66 which allow intuitive access to data stored in the tree (direct children or 67 not). 68 </p> 69<h4> 70<a name="property_tree.accessing.h0"></a> 71 <span class="phrase"><a name="property_tree.accessing.three_ways_of_getting_data"></a></span><a class="link" href="accessing.html#property_tree.accessing.three_ways_of_getting_data">Three 72 Ways of Getting Data</a> 73 </h4> 74<p> 75 There are three versions of get: get, get (default-value version), and get_optional, 76 which differ by failure handling strategy. All versions take path specifier, 77 which determines in which key to search for a value. It can be a single key, 78 or a path to key, where path elements are separated with a special character 79 (a '.' if not specified differently). For example debug.logging.errorlevel 80 might be a valid path with dot as a separator. 81 </p> 82<div class="orderedlist"><ol class="orderedlist" type="1"> 83<li class="listitem"> 84<p class="simpara"> 85 The throwing version (<code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code>): 86 </p> 87<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> <span class="identifier">pt</span><span class="special">;</span> 88<span class="comment">/* ... */</span> 89<span class="keyword">float</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code><span class="special"><</span><span class="keyword">float</span><span class="special">>(</span><span class="string">"a.path.to.float.value"</span><span class="special">);</span> 90</pre> 91<p class="simpara"> 92 This call locates the proper node in the tree and tries to translate its 93 data string to a float value. If that fails, exception is thrown. If path 94 does not exist, it will be <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree_bad_path.html" title="Class ptree_bad_path">ptree_bad_path</a></code> 95 exception. If value could not be translated, it will be <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree_bad_data.html" title="Class ptree_bad_data">ptree_bad_data</a></code>. 96 Both of them derive from <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree_error.html" title="Class ptree_error">ptree_error</a></code> 97 to make common handling possible. 98 </p> 99</li> 100<li class="listitem"> 101<p class="simpara"> 102 The default-value version (<code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code>): 103 </p> 104<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> <span class="identifier">pt</span><span class="special">;</span> 105<span class="comment">/* ... */</span> 106<span class="keyword">float</span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code><span class="special">(</span><span class="string">"a.path.to.float.value"</span><span class="special">,</span> <span class="special">-</span><span class="number">1.f</span><span class="special">);</span> 107</pre> 108<p class="simpara"> 109 It will do the same as above, but if it fails, it will return the default 110 value specified by second parameter (here -1.f) instead of throwing. This 111 is very useful in common situations where one wants to allow omitting of 112 some keys. Note that type specification needed in throwing version is normally 113 not necessary here, because type is determined by the default value parameter. 114 </p> 115</li> 116<li class="listitem"> 117<p class="simpara"> 118 The optional version (<code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_69-bb">get_optional</a></code>): 119 </p> 120<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> <span class="identifier">pt</span><span class="special">;</span> 121<span class="comment">/* ... */</span> 122<span class="identifier">boost</span><span class="special">::</span><span class="identifier">optional</span><span class="special"><</span><span class="keyword">float</span><span class="special">></span> <span class="identifier">v</span> <span class="special">=</span> <span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_69-bb">get_optional</a></code><span class="special"><</span><span class="keyword">float</span><span class="special">>(</span><span class="string">"a.path.to.float.value"</span><span class="special">);</span> 123</pre> 124<p class="simpara"> 125 This version uses boost::optional class to handle extraction failure. On 126 successful extraction, it will return boost::optional initialized with 127 extracted value. Otherwise, it will return uninitialized boost::optional. 128 </p> 129</li> 130</ol></div> 131<p> 132 To retrieve a value from this tree (not some subkey), use <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_53-bb">get_value</a></code>, 133 <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_53-bb">get_value</a></code> 134 (default-value version), and <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_59-bb">get_value_optional</a></code>. 135 They have identical semantics to <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code> 136 functions, except they don't take the <code class="computeroutput"><a class="link" href="../boost/property_tree/string_path.html" title="Class template string_path">path</a></code> 137 parameter. Don't call <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code> 138 with and empty <code class="computeroutput"><a class="link" href="../boost/property_tree/string_path.html" title="Class template string_path">path</a></code> 139 to do this as it will try to extract contents of subkey with empty name. 140 </p> 141<p> 142 To use a separator character other than default '<code class="literal">.</code>', you 143 need to construct a path object explicitly. The path type for a <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> is a string_path instantiation, 144 so the easiest way to refer to it is <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code>::path_type. 145 This way you can use trees that have dots in their keys: 146 </p> 147<pre class="programlisting"><span class="keyword">typedef</span> <span class="identifier">ptree</span><span class="special">::</span><span class="identifier">path_type</span> <span class="identifier">path</span><span class="special">;</span> 148<span class="identifier">pt</span><span class="special">.</span><span class="identifier">get</span><span class="special"><</span><span class="keyword">float</span><span class="special">>(</span><span class="identifier">path</span><span class="special">(</span><span class="string">"p.a.t.h/t.o/v.a.l.u.e"</span><span class="special">,</span> <span class="char">'/'</span><span class="special">));</span> 149<span class="identifier">pt</span><span class="special">.</span><span class="identifier">get</span><span class="special">(</span><span class="identifier">path</span><span class="special">(</span><span class="string">"p.a.t.h/t.o/v.a.l.u.e"</span><span class="special">,</span> <span class="char">'/'</span><span class="special">),</span> <span class="number">0</span><span class="special">,</span> <span class="identifier">NULL</span><span class="special">);</span> 150<span class="identifier">pt</span><span class="special">.</span><span class="identifier">get_optional</span><span class="special"><</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span><span class="special">>(</span><span class="identifier">path</span><span class="special">(</span><span class="string">"p.a.t.h/t.o/v.a.l.u.e"</span><span class="special">,</span> <span class="char">'/'</span><span class="special">));</span> 151</pre> 152<p> 153 Note: the special overloads of <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code> 154 and <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_69-bb">get_optional</a></code> 155 taking a separator character that existed in pre-release versions of PropertyTree 156 have been removed. This is because the overloads conflicted with using per-call 157 data translators. 158 </p> 159<h4> 160<a name="property_tree.accessing.h1"></a> 161 <span class="phrase"><a name="property_tree.accessing.two_ways_of_putting_data"></a></span><a class="link" href="accessing.html#property_tree.accessing.two_ways_of_putting_data">Two 162 Ways of Putting Data</a> 163 </h4> 164<p> 165 To complement <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code>, 166 there are <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code> 167 and <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_73-bb">add</a></code>. 168 Contrary to <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code>, 169 they have only one variant each. This is because there is no need to deal with 170 missing values when adding data. If the supplied value cannot be converted 171 to the tree's data type, the functions will throw <code class="computeroutput"><a class="link" href="../boost/property_tree/ptree_bad_data.html" title="Class ptree_bad_data">ptree_bad_data</a></code>. 172 </p> 173<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> <span class="identifier">pt</span><span class="special">;</span> 174<span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code><span class="special">(</span><span class="string">"a.path.to.float.value"</span><span class="special">,</span> <span class="number">3.14f</span><span class="special">);</span> 175<span class="comment">// Overwrites the value</span> 176<span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code><span class="special">(</span><span class="string">"a.path.to.float.value"</span><span class="special">,</span> <span class="number">2.72f</span><span class="special">);</span> 177<span class="comment">// Adds a second node with the new value.</span> 178<span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_73-bb">add</a></code><span class="special">(</span><span class="string">"a.path.to.float.value"</span><span class="special">,</span> <span class="number">3.14f</span><span class="special">);</span> 179</pre> 180<p> 181 Calling <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code> 182 will insert a new value at specified path, so that a call to <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_63-bb">get</a></code> 183 specifying the same path will retrieve it. Further, <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code> 184 will insert any missing path elements during path traversal. For example, calling 185 <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a><span class="special">(</span><span class="string">"key1.key2.key3"</span><span class="special">,</span> <span class="number">3.14f</span><span class="special">)</span></code> 186 on an empty tree will insert three new children: <code class="computeroutput"><span class="identifier">key1</span></code>, 187 <code class="computeroutput"><span class="identifier">key1</span><span class="special">.</span><span class="identifier">key2</span></code> and <code class="computeroutput"><span class="identifier">key1</span><span class="special">.</span><span class="identifier">key2</span><span class="special">.</span><span class="identifier">key3</span></code>. The last one will receive a string 188 <code class="computeroutput"><span class="string">"3.14"</span></code> as data, while 189 the two former ones will have empty data strings. <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code> 190 always inserts new keys at the back of the existing sequences. The difference 191 between <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code> 192 and <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_73-bb">add</a></code> 193 is that put will overwrite existing values if there are any, while add will 194 create a new node to hold the value even if the specified path references an 195 existing node. 196 </p> 197<p> 198 Similar to <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_53-bb">get_value</a></code>, 199 there is also a <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_61-bb">put_value</a></code> 200 function. It does the same for this property tree what <code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_71-bb">put</a></code> 201 does for its children. Thus, it does not receive a <code class="computeroutput"><a class="link" href="../boost/property_tree/string_path.html" title="Class template string_path">path</a></code>: 202 </p> 203<pre class="programlisting"><code class="computeroutput"><a class="link" href="../boost/property_tree/ptree.html" title="Type definition ptree">ptree</a></code> <span class="identifier">pt</span><span class="special">;</span> 204<span class="identifier">pt</span><span class="special">.</span><code class="computeroutput"><a class="link" href="../boost/property_tree/basic_ptree.html#id-1_3_32_10_7_1_1_1_3_61-bb">put_value</a></code><span class="special">(</span><span class="number">3.14f</span><span class="special">);</span> 205</pre> 206<p> 207 There is no add_value function. 208 </p> 209</div> 210<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 211<td align="left"></td> 212<td align="right"><div class="copyright-footer">Copyright © 2008-2010 Marcin Kalicinski<br>Copyright © 2010-2013 Sebastian 213 Redl<p> 214 Distributed under the Boost Software License, Version 1.0. (See accompanying 215 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>) 216 </p> 217</div></td> 218</tr></table> 219<hr> 220<div class="spirit-nav"> 221<a accesskey="p" href="parsers.html"><img src="../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../property_tree.html"><img src="../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../index.html"><img src="../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="appendices.html"><img src="../../../doc/src/images/next.png" alt="Next"></a> 222</div> 223</body> 224</html> 225
