Boost C++ Libraries Home Libraries People FAQ More

PrevUpHomeNext

Class template basic_ptree

boost::property_tree::basic_ptree

Synopsis

// In header: <boost/property_tree/ptree.hpp>

template<typename Key, typename Data, typename KeyCompare> 
class basic_ptree {
public:
  // types
  typedef basic_ptree<  ;  
  typedef                                   ;   
  typedef                                  ;  
  typedef                            ;
  typedef     ; 
  typedef                           ;  
  typedef path_of<                  ;  

  // construct/copy/destruct
  ();
  ();
  ();
   ();
  ~();

  // public member functions
   ();
   () ;
   () ;
   () ;
   ();
   () ;
   ();
   () ;
   ();
   () ;
   ();
   () ;
   ();
   () ;
   ();
   () ;
   (, );
  template<typename It>  (, , );
   ();
   (, );
   ();
   ();
   ();
   ();
   ();
  template<typename Compare>  ();
   ();
   () ;
   () ;
   ();
   () ;
   ();
   () ;
   ();
   () ;
   ();
   
  () ;
   () ;
   ();
   ();
   () ;
   ();
   () ;
   ();
   ();
   () ;
   (, );
   (, ) ;
   ();
   () ;
   (, );
   (, );
  template<typename Type, typename Translator> 
     () ;
  template<typename Type>  () ;
  template<typename Type, typename Translator> 
     (, ) ;
  template<typename Ch, typename Translator> 
     (, ) ;
  template<typename Type>  () ;
  template<typename Ch>  () ;
  template<typename Type, typename Translator> 
     () ;
  template<typename Type>  () ;
  template<typename Type, typename Translator> 
     (, );
  template<typename Type>  ();
  template<typename Type, typename Translator> 
     (, ) ;
  template<typename Type>  () ;
  template<typename Type, typename Translator> 
     (, , ) ;
  template<typename Ch, typename Translator> 
     (, , ) ;
  template<typename Type> 
     (, ) ;
  template<typename Ch>  (, ) ;
  template<typename Type, typename Translator> 
     (, ) ;
  template<typename Type> 
     () ;
  template<typename Type, typename Translator> 
     (, , );
  template<typename Type>  (, );
  template<typename Type, typename Translator> 
     (, , );
  template<typename Type>  (, );

  // private member functions
   () ;
   ();
};

Description

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.

basic_ptree public types

  1. typedef basic_ptree< ;

    Simpler way to refer to this basic_ptree<C,K,P,A> type. Note that this is private, and made public only for doxygen.

basic_ptree public construct/copy/destruct

  1. ();

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

  2. ( data);

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

  3. ( rhs);
  4.  ( rhs);

    Basic guarantee only.

  5. ~();

basic_ptree public member functions

  1.  ( rhs);

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

  2.  () ;

    The number of direct children of this node.

  3.  () ;
  4.  () ;

    Whether there are any direct children.

  5.  ();
  6.  () ;
  7.  ();
  8.  () ;
  9.  ();
  10.  () ;
  11.  ();
  12.  () ;
  13.  ();
  14.  () ;
  15.  ();
  16.  () ;
  17.  ( where,  value);

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

    Returns:

    An iterator to the newly created child.

  18. template<typename It>  ( where,  first,  last);

    Range insert. Equivalent to:

  19.  ( where);

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

    Returns:

    A valid iterator pointing to the element after the erased.

  20.  ( first,  last);

    Range erase. Equivalent to:

  21.  ( value);

    Equivalent to insert(begin(), value).

  22.  ( value);

    Equivalent to insert(end(), value).

  23.  ();

    Equivalent to erase(begin()).

  24.  ();

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

  25.  ();

    Reverses the order of direct children in the property tree.

  26. template<typename Compare>  ( comp);

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

  27.  ();

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

  28.  ( rhs) ;

    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.

  29.  ( rhs) ;
  30.  ();

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

  31.  () ;

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

  32.  ();

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

  33.  () ;

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

  34.  ( key);

    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.

  35.  ( key) ;

    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.

  36.  ( key);

    Find the range of children that have the given key.

  37.  
    ( key) ;

    Find the range of children that have the given key.

  38.  ( key) ;

    Count the number of direct children with the given key.

  39.  ( key);

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

  40.  ( it);

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

    [Note] Note

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

  41.  ( it) ;

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

    [Note] Note

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

  42.  ();

    Reference to the actual data in this node.

  43.  () ;

    Reference to the actual data in this node.

  44.  ();

    Clear this tree completely, of both data and children.

  45.  ( path);

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

    [Note] Note

    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:

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

  46.  ( path) ;

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

  47.  ( path,  default_value);

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

  48.  
    ( path,  default_value) ;

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

  49.  ( path);

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

  50.  ( path) ;

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

  51.  ( path,  value);

    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.

    [Note] Note

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

    [Note] Note

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

    Returns:

    A reference to the inserted subtree.

  52.  ( path,  value);

    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.

    [Note] Note

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

    Parameters:

    path

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

    Returns:

    A reference to the inserted subtree.

  53. template<typename Type, typename Translator> 
       ( tr) ;

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

    Throws:

    ptree_bad_data if the conversion fails.
  54. template<typename Type>  () ;

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

    Throws:

    ptree_bad_data if the conversion fails.
  55. template<typename Type, typename Translator> 
       ( default_value,  tr) ;

    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.

  56. template<typename Ch, typename Translator> 
       ( default_value,  tr) ;

    Make get_value do the right thing for string literals.

  57. template<typename Type> 
       ( default_value) ;

    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.

  58. template<typename Ch>  ( default_value) ;

    Make get_value do the right thing for string literals.

  59. template<typename Type, typename Translator> 
       ( tr) ;

    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.

  60. template<typename 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.

  61. template<typename Type, typename Translator> 
       ( value,  tr);

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

    Throws:

    ptree_bad_data if the conversion fails.
  62. template<typename Type>  ( value);

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

    Throws:

    ptree_bad_data if the conversion fails.
  63. template<typename Type, typename Translator> 
       ( path,  tr) ;

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

  64. template<typename Type>  ( path) ;

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

  65. template<typename Type, typename Translator> 
       ( path,  default_value,  tr) ;

    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.

  66. template<typename Ch, typename Translator> 
       ( path,  default_value, 
                       tr) ;

    Make get do the right thing for string literals.

  67. template<typename Type> 
       ( path,  default_value) ;

    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.

  68. template<typename Ch> 
       ( path,  default_value) ;

    Make get do the right thing for string literals.

  69. template<typename Type, typename Translator> 
       ( path,  tr) ;

    Shorthand for:

    That is, return the value if it exists and can be converted, or nil.

  70. template<typename Type> 
       ( path) ;

    Shorthand for:

    That is, return the value if it exists and can be converted, or nil.

  71. template<typename Type, typename Translator> 
       ( path,  value,  tr);

    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.

    Returns:

    The node that had its value changed.

    Throws:

    ptree_bad_data if the conversion fails.
  72. template<typename Type> 
       ( path,  value);

    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.

    Returns:

    The node that had its value changed.

    Throws:

    ptree_bad_data if the conversion fails.
  73. template<typename Type, typename Translator> 
       ( path,  value,  tr);

    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.

    Parameters:

    path

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

    tr

    The translator to use.

    value

    The value to add.

    Returns:

    The node that was added.

    Throws:

    ptree_bad_data if the conversion fails.
  74. template<typename Type> 
       ( path,  value);

    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.

    Parameters:

    path

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

    value

    The value to add.

    Returns:

    The node that was added.

    Throws:

    ptree_bad_data if the conversion fails.

basic_ptree private member functions

  1.  ( p) ;
  2.  ( p);

PrevUpHomeNext