runtime_error
Base class for all property tree errors. Derives from `std::runtime_error`. Call member function `what` to get human readable message associated with the error.
const std::string &

The message to associate with this error.

Instantiate a `ptree_error` instance with the given message.

boost::property_tree::ptree_error
Error indicating that translation from given value to the property tree data_type (or vice versa) failed. Derives from `ptree_error`.
T Retrieve the data associated with this error. This is the source value that failed to be translated. You need to explicitly specify its type.
const std::string &

The message to associate with this error.

const T &

The value associated with this error that was the source of the translation failure.

Instantiate a `ptree_bad_data` instance with the given message and data.

boost::property_tree::ptree_error
Error indicating that specified path does not exist. Derives from `ptree_error`.
T Retrieve the invalid path. You need to explicitly specify the type of path.
const std::string &

The message to associate with this error.

const T &

The path that could not be found in the property_tree.

Instantiate a `ptree_bad_path` with the given message and path data.

T
T
`id_translator`< T >
std::basic_string< Ch
Traits
Alloc >
std::basic_string< Ch
Traits
Alloc >
`id_translator`< std::basic_string< Ch, Traits, Alloc > >
void `std::basic_istream< Ch > &` `Ptree &`

Read INFO from a the given stream and translate it to a property tree.

Replaces the existing contents. Strong exception guarantee.

`info_parser_error` If the stream cannot be read, doesn't contain valid INFO, or a conversion fails.

void `std::basic_istream< Ch > &` `Ptree &` `const Ptree &

If parsing fails, pt is set to a copy of this tree.

`

Read INFO from a the given stream and translate it to a property tree.

Replaces the existing contents. Strong exception guarantee.

void `const std::string &` `Ptree &` `const std::locale &std::locale()`

Read INFO from a the given file and translate it to a property tree. The tree's key type must be a string type, i.e. it must have a nested value_type typedef that is a valid parameter for basic_ifstream.

Replaces the existing contents. Strong exception guarantee.

`info_parser_error` If the file cannot be read, doesn't contain valid INFO, or a conversion fails.

void `const std::string &` `Ptree &` `const Ptree &

If parsing fails, pt is set to a copy of this tree.

` `const std::locale &std::locale()`

Read INFO from a the given file and translate it to a property tree. The tree's key type must be a string type, i.e. it must have a nested value_type typedef that is a valid parameter for basic_ifstream.

Replaces the existing contents. Strong exception guarantee.

void `std::basic_ostream< Ch > &` `const Ptree &` `const info_writer_settings< Ch > &info_writer_settings< Ch >()

The settings to use when writing the INFO data.

`

Writes a tree to the stream in INFO format.

`info_parser_error` If the stream cannot be written to, or a conversion fails.

void `const std::string &` `const Ptree &` `const std::locale &std::locale()` `const info_writer_settings< typename Ptree::key_type::value_type > &info_writer_make_settings< typename Ptree::key_type::value_type >()

The settings to use when writing the INFO data.

`

Writes a tree to the file in INFO format. The tree's key type must be a string type, i.e. it must have a nested value_type typedef that is a valid parameter for basic_ofstream.

`info_parser_error` If the file cannot be written to, or a conversion fails.

file_parser_error

Indicates an error parsing INI formatted data.

const std::string &

Message describing the parser error.

const std::string &

The name of the file being parsed containing the error.

unsigned long

The line in the given file where an error was encountered.

Construct an ``ini_parser_error``

bool `int

value to check for validity as flags to ini_parser.

`

Determines whether the `flags` are valid for use with the ini_parser.

true if the flags are valid, false otherwise.

void `std::basic_istream< typename Ptree::key_type::value_type > &

Stream from which to read in the property tree.

` `Ptree &

The property tree to populate.

`

Read INI from a the given stream and translate it to a property tree.

Clears existing contents of property tree. In case of error the property tree is not modified.

`ini_parser_error` If a format violation is found.

void `const std::string &

Name of file from which to read in the property tree.

` `Ptree &

The property tree to populate.

` `const std::locale &std::locale()

The locale to use when reading in the file contents.

`

Read INI from a the given file and translate it to a property tree.

Clears existing contents of property tree. In case of error the property tree unmodified.

`ini_parser_error` In case of error deserializing the property tree.

void `std::basic_ostream< typename Ptree::key_type::value_type > &

The stream to which to write the INI representation of the property tree.

` `const Ptree &

The property tree to tranlsate to INI and output.

` `int0

The flags to use when writing the INI file. No flags are currently supported.

`

Translates the property tree to INI and writes it the given output stream.

pt cannot have data in its root.

pt cannot have keys both data and children.

pt cannot be deeper than two levels.

There cannot be duplicate keys on any given level of pt.

`ini_parser_error` In case of error translating the property tree to INI or writing to the output stream.

void `const std::string &

The name of the file to which to write the INI representation of the property tree.

` `const Ptree &

The property tree to tranlsate to INI and output.

` `int0

The flags to use when writing the INI file. The following flags are supported:

- `skip_ini_validity_check` – Skip check if ptree is a valid ini. The validity check covers the preconditions but takes `O(n log n)` time.

` `const std::locale &std::locale()

The locale to use when writing the file.

`

Translates the property tree to INI and writes it the given file.

pt cannot have data in its root.

pt cannot have keys both data and children.

pt cannot be deeper than two levels.

There cannot be duplicate keys on any given level of pt.

`info_parser_error` In case of error translating the property tree to INI or writing to the file.

void `std::basic_istream< typename Ptree::key_type::value_type > &

Stream from which to read in the property tree.

` `Ptree &

The property tree to populate.

`

Read JSON from a the given stream and translate it to a property tree.

Clears existing contents of property tree. In case of error the property tree unmodified.

Items of JSON arrays are translated into ptree keys with empty names. Members of objects are translated into named keys.

JSON data can be a string, a numeric value, or one of literals "null", "true" and "false". During parse, any of the above is copied verbatim into ptree data string.

`json_parser_error` In case of error deserializing the property tree.

void `const std::string &

Name of file from which to read in the property tree.

` `Ptree &

The property tree to populate.

` `const std::locale &std::locale()

The locale to use when reading in the file contents.

`

Read JSON from a the given file and translate it to a property tree.

Clears existing contents of property tree. In case of error the property tree unmodified.

Items of JSON arrays are translated into ptree keys with empty names. Members of objects are translated into named keys.

JSON data can be a string, a numeric value, or one of literals "null", "true" and "false". During parse, any of the above is copied verbatim into ptree data string.

`json_parser_error` In case of error deserializing the property tree.

void `std::basic_ostream< typename Ptree::key_type::value_type > &

The stream to which to write the JSON representation of the property tree.

` `const Ptree &

The property tree to tranlsate to JSON and output.

` `booltrue

Whether to pretty-print. Defaults to true for backward compatibility.

`

Translates the property tree to JSON and writes it the given output stream.

Any property tree key containing only unnamed subkeys will be rendered as JSON arrays.

pt cannot contain keys that have both subkeys and non-empty data.

`json_parser_error` In case of error translating the property tree to JSON or writing to the output stream.

void `const std::string &

The name of the file to which to write the JSON representation of the property tree.

` `const Ptree &

The property tree to translate to JSON and output.

` `const std::locale &std::locale()

The locale to use when writing out to the output file.

` `booltrue

Whether to pretty-print. Defaults to true and last place for backward compatibility.

`

Translates the property tree to JSON and writes it the given file.

Any property tree key containing only unnamed subkeys will be rendered as JSON arrays.

pt cannot contain keys that have both subkeys and non-empty data.

`json_parser_error` In case of error translating the property tree to JSON or writing to the file.

std::less<Key>

Property tree main structure. A property tree is a hierarchical data structure which has one element of type `Data` in each node, as well as an ordered sequence of sub-nodes, which are additionally identified by a non-unique key of type `Key`.

Key equivalency is defined by `KeyCompare`, a predicate defining a strict weak ordering.

Property tree defines a Container-like interface to the (key-node) pairs of its direct sub-nodes. The iterators are bidirectional. The sequence of nodes is held in insertion order, not key order.

void `self_type &`

Swap with other tree. Only constant-time and nothrow if the data type's swap is.

size_type

The number of direct children of this node.

size_type
bool

Whether there are any direct children.

iterator
const_iterator
iterator
const_iterator
reverse_iterator
const_reverse_iterator
reverse_iterator
const_reverse_iterator
value_type &
const value_type &
value_type &
const value_type &
iterator `iterator` `const value_type &`

Insert a copy of the given tree with its key just before the given position in this node. This operation invalidates no iterators.

An iterator to the newly created child.

void `iterator` `It` `It`

Range insert. Equivalent to:

    for(; first != last; ++first) insert(where, *first);

iterator `iterator`

Erase the child pointed at by the iterator. This operation invalidates the given iterator, as well as its equivalent assoc_iterator.

A valid iterator pointing to the element after the erased.

iterator `iterator` `iterator`

Range erase. Equivalent to:

    while(first != last;) first = erase(first);

iterator `const value_type &`

Equivalent to insert(begin(), value).

iterator `const value_type &`

Equivalent to insert(end(), value).

void

Equivalent to erase(begin()).

void

Equivalent to erase(boost::prior(end())).

void

Reverses the order of direct children in the property tree.

void `Compare`

Sorts the direct children of this node according to the predicate. The predicate is passed the whole pair of key and child.

void

Sorts the direct children of this node according to key order.

bool `const self_type &`

Two property trees are the same if they have the same data, the keys and order of their children are the same, and the children compare equal, recursively.

bool `const self_type &`
assoc_iterator

Returns an iterator to the first child, in key order.

const_assoc_iterator

Returns an iterator to the first child, in key order.

assoc_iterator

Returns the not-found iterator. Equivalent to end() in a real associative container.

const_assoc_iterator

Returns the not-found iterator. Equivalent to end() in a real associative container.

assoc_iterator `const key_type &`

Find a child with the given key, or not_found() if there is none. There is no guarantee about which child is returned if multiple have the same key.

const_assoc_iterator `const key_type &`

Find a child with the given key, or not_found() if there is none. There is no guarantee about which child is returned if multiple have the same key.

std::pair< assoc_iterator, assoc_iterator > `const key_type &`

Find the range of children that have the given key.

std::pair< const_assoc_iterator, const_assoc_iterator > `const key_type &`

Find the range of children that have the given key.

size_type `const key_type &`

Count the number of direct children with the given key.

size_type `const key_type &`

Erase all direct children with the given key and return the count.

iterator `assoc_iterator`

Get the iterator that points to the same element as the argument.

A valid assoc_iterator range (a, b) does not imply that (to_iterator(a), to_iterator(b)) is a valid range.

const_iterator `const_assoc_iterator`

Get the iterator that points to the same element as the argument.

A valid const_assoc_iterator range (a, b) does not imply that (to_iterator(a), to_iterator(b)) is a valid range.

data_type &

Reference to the actual data in this node.

const data_type &

Reference to the actual data in this node.

void

Clear this tree completely, of both data and children.

self_type & `const path_type &`

Get the child at the given path, or throw ``ptree_bad_path``.

Depending on the path, the result at each level may not be completely deterministic, i.e. if the same key appears multiple times, which child is chosen is not specified. This can lead to the path not being resolved even though there is a descendant with this path. Example:

    a -> b -> c
      -> b

The path "a.b.c" will succeed if the resolution of "b" chooses the first such node, but fail if it chooses the second.
const self_type & `const path_type &`

Get the child at the given path, or throw ``ptree_bad_path``.

self_type & `const path_type &` `self_type &`

Get the child at the given path, or return `default_value`.

const self_type & `const path_type &` `const self_type &`

Get the child at the given path, or return `default_value`.

optional< self_type & > `const path_type &`

Get the child at the given path, or return boost::null.

optional< const self_type & > `const path_type &`

Get the child at the given path, or return boost::null.

self_type & `const path_type &` `const self_type &`

Set the node at the given path to the given value. Create any missing parents. If the node at the path already exists, replace it.

Because of the way paths work, it is not generally guaranteed that a node newly created can be accessed using the same path.

If the path could refer to multiple nodes, it is unspecified which one gets replaced.

A reference to the inserted subtree.

self_type & `const path_type &

Path to the child. The last fragment must not have an index.

` `const self_type &`

Add the node at the given path. Create any missing parents. If there already is a node at the path, add another one with the same key.

Because of the way paths work, it is not generally guaranteed that a node newly created can be accessed using the same path.

A reference to the inserted subtree.

unspecified `Translator`

Take the value of this node and attempt to translate it to a `Type` object using the supplied translator.

`ptree_bad_data` if the conversion fails.

Type

Take the value of this node and attempt to translate it to a `Type` object using the default translator.

`ptree_bad_data` if the conversion fails.

Type `const Type &` `Translator`

Take the value of this node and attempt to translate it to a `Type` object using the supplied translator. Return `default_value` if this fails.

unspecified `const Ch *` `Translator`

Make get_value do the right thing for string literals.

unspecified `const Type &`

Take the value of this node and attempt to translate it to a `Type` object using the default translator. Return `default_value` if this fails.

unspecified `const Ch *`

Make get_value do the right thing for string literals.

optional< Type > `Translator`

Take the value of this node and attempt to translate it to a `Type` object using the supplied translator. Return boost::null if this fails.

optional< Type >

Take the value of this node and attempt to translate it to a `Type` object using the default translator. Return boost::null if this fails.

void `const Type &` `Translator`

Replace the value at this node with the given value, translated to the tree's data type using the supplied translator.

`ptree_bad_data` if the conversion fails.

void `const Type &`

Replace the value at this node with the given value, translated to the tree's data type using the default translator.

`ptree_bad_data` if the conversion fails.

unspecified `const path_type &` `Translator`

Shorthand for get_child(path).get_value(tr).

Type `const path_type &`

Shorthand for get_child(path).get_value<Type>().

Type `const path_type &` `const Type &` `Translator`

Shorthand for get_child(path, empty_ptree()) .get_value(default_value, tr). That is, return the translated value if possible, and the default value if the node doesn't exist or conversion fails.

unspecified `const path_type &` `const Ch *` `Translator`

Make get do the right thing for string literals.

unspecified `const path_type &` `const Type &`

Shorthand for get_child(path, empty_ptree()) .get_value(default_value). That is, return the translated value if possible, and the default value if the node doesn't exist or conversion fails.

unspecified `const path_type &` `const Ch *`

Make get do the right thing for string literals.

optional< Type > `const path_type &` `Translator`

Shorthand for:

    if(optional\<self_type&\> node = get_child_optional(path))
      return node->get_value_optional(tr);
    return boost::null;

That is, return the value if it exists and can be converted, or nil.
optional< Type > `const path_type &`

Shorthand for:

    if(optional\<const self_type&\> node = get_child_optional(path))
      return node->get_value_optional();
    return boost::null;

That is, return the value if it exists and can be converted, or nil.
self_type & `const path_type &` `const Type &` `Translator`

Set the value of the node at the given path to the supplied value, translated to the tree's data type. If the node doesn't exist, it is created, including all its missing parents.

The node that had its value changed.

`ptree_bad_data` if the conversion fails.

self_type & `const path_type &` `const Type &`

Set the value of the node at the given path to the supplied value, translated to the tree's data type. If the node doesn't exist, it is created, including all its missing parents.

The node that had its value changed.

`ptree_bad_data` if the conversion fails.

self_type & `const path_type &

Path to the child. The last fragment must not have an index.

` `const Type &

The value to add.

` `Translator

The translator to use.

`

If the node identified by the path does not exist, create it, including all its missing parents. If the node already exists, add a sibling with the same key. Set the newly created node's value to the given paremeter, translated with the supplied translator.

The node that was added.

`ptree_bad_data` if the conversion fails.

self_type & `const path_type &

Path to the child. The last fragment must not have an index.

` `const Type &

The value to add.

`

If the node identified by the path does not exist, create it, including all its missing parents. If the node already exists, add a sibling with the same key. Set the newly created node's value to the given paremeter, translated with the supplied translator.

The node that was added.

`ptree_bad_data` if the conversion fails.

Creates a node with no children and default-constructed data.

const data_type &

Creates a node with no children and a copy of the given data.

const self_type &
self_type & `const self_type &`

Basic guarantee only.

self_type * `path_type &`
self_type & `path_type &`
Simple implementation of the Translator concept. It does no translation.
boost::optional< T > `const T &`
boost::optional< T > `const T &`
If you want to use a custom key type, specialize this struct for it and give it a 'type' typedef that specifies your path type. The path type must conform to the Path concept described in the documentation. This is already specialized for std::basic_string.
Specialize this struct to specify a default translator between the data in a tree whose data_type is Internal, and the external data_type specified in a get_value, get, put_value or put operation. This is already specialized for Internal being std::basic_string.

Implements a path using a std::string as the key.

`string_path`< std::string, `id_translator`< std::string > >

A property tree with std::string for key and data, and default comparison.

`basic_ptree`< std::string, std::string >

A property tree with std::string for key and data, and case-insensitive comparison.

unspecified

Implements a path using a std::wstring as the key.

`string_path`< std::wstring, `id_translator`< std::wstring > >

A property tree with std::wstring for key and data, and default comparison.

The type only exists if the platform supports `wchar_t`.

`basic_ptree`< std::wstring, std::wstring >

A property tree with std::wstring for key and data, and case-insensitive comparison.

The type only exists if the platform supports `wchar_t`.

unspecified
void ``basic_ptree`< K, D, C > &` ``basic_ptree`< K, D, C > &`

Swap two property tree instances.

void `Archive &

The archive to which to save the serialized property tree. This archive should conform to the concept laid out by the Boost.Serialization library.

` `const `basic_ptree`< K, D, C > &

The property tree to serialize.

` `const unsigned int

file_version for the archive.

`

Serialize the property tree to the given archive.

In addition to serializing to regular archives, this supports serializing to archives requiring name-value pairs, e.g. XML archives. However, the output format in the XML archive is not guaranteed to be the same as that when using the Boost.PropertyTree library's `boost::property_tree::xml_parser::write_xml`.

`ar` will contain the serialized form of `t`.

void `Archive &

The archive from which to load the serialized property tree. This archive should conform to the concept laid out by the Boost.Serialization library.

` ``basic_ptree`< K, D, C > &

The property tree to de-serialize.

` `const unsigned int

file_version for the archive.

`

De-serialize the property tree to the given archive.

In addition to de-serializing from regular archives, this supports loading from archives requiring name-value pairs, e.g. XML archives. The format should be that used by boost::property_tree::save.

`t` will contain the de-serialized data from `ar`.

void `Archive &

The archive from which to load or save the serialized property tree. The type of this archive will determine whether saving or loading is performed.

` ``basic_ptree`< K, D, C > &

The property tree to load or save.

` `const unsigned int

file_version for the archive.

`

Load or store the property tree using the given archive.

void
void `std::basic_ostream< Ch, Traits > &` `const E &`
void `std::basic_istream< Ch, Traits > &` `E &`
Ch
Traits
Ch
void
void `std::basic_ostream< Ch, Traits > &` `Ch`
void `std::basic_istream< Ch, Traits > &` `Ch &`
Ch
Traits
F
typename boost::enable_if< detail::is_inexact< F > >::type
void `std::basic_ostream< Ch, Traits > &` `const F &`
void `std::basic_istream< Ch, Traits > &` `F &`
Ch
Traits
bool
void
void `std::basic_ostream< Ch, Traits > &` `bool`
void `std::basic_istream< Ch, Traits > &` `bool &`
Ch
Traits
signed char
void
void `std::basic_ostream< Ch, Traits > &` `signed char`
void `std::basic_istream< Ch, Traits > &` `signed char &`
Ch
Traits
unsigned char
void
void `std::basic_ostream< Ch, Traits > &` `unsigned char`
void `std::basic_istream< Ch, Traits > &` `unsigned char &`
Implementation of Translator that uses the stream overloads.
std::basic_string< Ch, Traits, Alloc >
E
boost::optional< E > `const internal_type &`
boost::optional< internal_type > `const E &`
std::locale
std::locale()
std::basic_string< Ch
Traits
Alloc >
E
`stream_translator`< Ch, Traits, Alloc, E >

Any Sequence. If the sequence does not support random- access iteration, concatenation of paths assumes that insertions at the end preserve iterator validity.

A translator with internal_type == String.

Default path class. A path is a sequence of values. Groups of values are separated by the separator value, which defaults to '.' cast to the sequence's value type. The group of values is then passed to the translator to get a key.

If instantiated with std::string and `id_translator`<std::string>, it accepts paths of the form "one.two.three.four".

Translator::external_type
String::value_type
(is_same< String, typename Translator::internal_type >::value)
s_c_iter
key_type Take a single element off the path at the front and return it.
bool Test if the path is empty.
bool Test if the path contains a single element, i.e. no separators.
char_type Get the separator used by this path.
std::string
`string_path` & `const `string_path` &` Append a second path to this one.

o's separator is the same as this one's, or o has no separators

char_type
char_type('.')
Create an empty path.
const String &

A sequence, possibly with separators, that describes the path, e.g. "one.two.three".

char_type
char_type('.')

The separator used in parsing. Defaults to '.'.

Translator
Translator()

The translator used by this path to convert the individual parts to keys.

Create a path by parsing the given string.

const char_type *

A zero-terminated array of values. Only use if zero- termination makes sense for your type, and your sequence supports construction from it. Intended for string literals.

char_type
char_type('.')

The separator used in parsing. Defaults to '.'.

Translator
Translator()

The translator used by this path to convert the individual parts to keys.

Create a path by parsing the given string.

const `string_path` &
`string_path` & `const `string_path` &`
std::basic_string< Ch
Traits
Alloc >
std::basic_string< Ch, Traits, Alloc >
`string_path`< _string, `id_translator`< _string > >
`string_path`< String, Translator > ``string_path`< String, Translator >` `const `string_path`< String, Translator > &`
`string_path`< String, Translator > ``string_path`< String, Translator >` `const typename String::value_type *`
`string_path`< String, Translator > `const typename String::value_type *` `const `string_path`< String, Translator > &`
void `std::basic_istream< typename Ptree::key_type::value_type > &

Stream from which to read in the property tree.

` `Ptree &

The property tree to populate.

` `int0

Flags controlling the behaviour of the parser. The following flags are supported:

- `no_concat_text` – Prevents concatenation of text nodes into datastring of property tree. Puts them in separate `<xmltext>` strings instead.

- `no_comments` – Skip XML comments.

- `trim_whitespace` – Trim leading and trailing whitespace from text, and collapse sequences of whitespace.

`

Reads XML from an input stream and translates it to property tree.

Clears existing contents of property tree. In case of error the property tree unmodified.

XML attributes are placed under keys named `<xmlattr>`.

`xml_parser_error` In case of error deserializing the property tree.

void `const std::string &

The file from which to read in the property tree.

` `Ptree &

The property tree to populate.

` `int0

Flags controlling the bahviour of the parser. The following flags are supported:

- `no_concat_text` – Prevents concatenation of text nodes into datastring of property tree. Puts them in separate `<xmltext>` strings instead.

- `no_comments` – Skip XML comments.

` `const std::locale &std::locale()

The locale to use when reading in the file contents.

`

Reads XML from a file using the given locale and translates it to property tree.

Clears existing contents of property tree. In case of error the property tree unmodified.

XML attributes are placed under keys named `<xmlattr>`.

`xml_parser_error` In case of error deserializing the property tree.

void `std::basic_ostream< typename Ptree::key_type::value_type > &

The stream to which to write the XML representation of the property tree.

` `const Ptree &

The property tree to tranlsate to XML and output.

` `const xml_writer_settings< typename Ptree::key_type > &xml_writer_settings< typename Ptree::key_type >()

The settings to use when writing out the property tree as XML.

`

Translates the property tree to XML and writes it the given output stream.

`xml_parser_error` In case of error translating the property tree to XML or writing to the output stream.

void `const std::string &

The file to which to write the XML representation of the property tree.

` `const Ptree &

The property tree to tranlsate to XML and output.

` `const std::locale &std::locale()

The locale to use when writing the output to file.

` `const xml_writer_settings< typename Ptree::key_type > &xml_writer_settings< typename Ptree::key_type >()

The settings to use when writing out the property tree as XML.

`

Translates the property tree to XML and writes it the given file.

`xml_parser_error` In case of error translating the property tree to XML or writing to the output stream.