Ticket #1989: property_tree-doxComments.patch

File property_tree-doxComments.patch, 64.9 KB (added by ryan.gallagher@…, 14 years ago)

patch to property tree public headers to add doxygen comments

  • boost/property_tree/ini_parser.hpp

     
    2222namespace boost { namespace property_tree { namespace ini_parser
    2323{
    2424
    25     static const int skip_ini_validity_check = 1;     // Skip check if ptree is a valid ini
     25    /** Skip check if ptree is a valid ini */
     26    static const int skip_ini_validity_check = 1;
    2627
     28    /**
     29     * Determines whether the @c flags are valid for use with the ini_parser.
     30     * @param flags value to check for validity as flags to ini_parser.
     31     * @return true if the flags are valid, false otherwise.
     32     */
    2733    inline bool validate_flags(int flags)
    2834    {
    2935        return (flags & ~skip_ini_validity_check) == 0;
    3036    }
    3137
    32     //! Ini parser error
     38    /** Indicates an error parsing INI formatted data. */
    3339    class ini_parser_error: public file_parser_error
    3440    {
    3541    public:
     42        /**
     43         * Construct an @c ini_parser_error
     44         * @param message Message describing the parser error.
     45         * @param filename The name of the file being parsed containing the error.
     46         * @param line The line in the given file where an error was encountered.
     47         */
    3648        ini_parser_error(const std::string &message,
    3749                         const std::string &filename,
    3850                         unsigned long line):
    … …  
    4153        }
    4254    };
    4355
    44     //! Read ini from stream
     56    /**
     57     * Read INI from a the given stream and translate it to a property tree.
     58     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     59     * @throw ini_parser_error In case of error deserializing the property tree.
     60     * @param stream Stream from which to read in the property tree.
     61     * @param[out] pt The property tree to populate.
     62     */
    4563    template<class Ptree>
    4664    void read_ini(std::basic_istream<typename Ptree::key_type::value_type> &stream,
    4765                  Ptree &pt)
    … …  
    108126
    109127    }
    110128
    111     //! Read ini from file
     129    /**
     130     * Read INI from a the given file and translate it to a property tree.
     131     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     132     * @throw ini_parser_error In case of error deserializing the property tree.
     133     * @param filename Name of file from which to read in the property tree.
     134     * @param[out] pt The property tree to populate.
     135     * @param loc The locale to use when reading in the file contents.
     136     */
    112137    template<class Ptree>
    113138    void read_ini(const std::string &filename,
    114139                  Ptree &pt,
    … …  
    126151        }
    127152    }
    128153
    129     //! Write ini to stream
     154    /**
     155     * Translates the property tree to INI and writes it the given output stream.
     156     * @pre @e pt cannot have keys with data at its root level.
     157     * @pre @e pt cannot be deaper than two levels.
     158     * @pre There cannot be duplicate keys on any given level of @e pt.
     159     * @throw ini_parser_error In case of error translating the property tree to INI
     160     *                         or writing to the output stream.
     161     * @param stream The stream to which to write the INI representation of the
     162     *               property tree.
     163     * @param pt The property tree to tranlsate to INI and output.
     164     * @param flags The flags to use when writing the INI file.
     165     *              The following flags are supported:
     166     * @li @c skip_ini_validity_check -- Skip check if ptree is a valid ini.  The
     167     *     validity check covers the preconditions but takes <tt>O(n log n)</tt> time.
     168     */
    130169    template<class Ptree>
    131170    void write_ini(std::basic_ostream<typename Ptree::key_type::value_type> &stream,
    132171                   const Ptree &pt,
    … …  
    165204
    166205    }
    167206
    168     // Write ini to file
     207    /**
     208     * Translates the property tree to INI and writes it the given file.
     209     * @pre @e pt cannot have keys with data at its root level.
     210     * @pre @e pt cannot be deaper than two levels.
     211     * @pre There cannot be duplicate keys on any given level of @e pt.
     212     * @throw info_parser_error In case of error translating the property tree to INI
     213     *                          or writing to the file.
     214     * @param filename The name of the file to which to write the INI representation
     215     *                 of the property tree.
     216     * @param pt The property tree to tranlsate to INI and output.
     217     * @param flags The flags to use when writing the INI file.
     218     *              The following flags are supported:
     219     * @li @c skip_ini_validity_check -- Skip check if ptree is a valid ini.  The
     220     *     validity check covers the preconditions but takes <tt>O(n log n)</tt> time.
     221     * @param loc The locale to use when writing the file.
     222     */
    169223    template<class Ptree>
    170224    void write_ini(const std::string &filename,
    171225                   const Ptree &pt,

  • boost/property_tree/ptree_serialization.hpp

     
    2424    ///////////////////////////////////////////////////////////////////////////
    2525    // boost::serialization support
    2626
     27    /**
     28     * Serialize the property tree to the given archive.
     29     * @note In addition to serializing to regular archives, this supports serializing to
     30     *       archives requiring name-value pairs, e.g. XML archives.  However, the output
     31     *       format in the XML archive is not guaranteed to be the same as that when using
     32     *       the Boost.PropertyTree library's @c boost::property_tree::xml_parser::write_xml.
     33     * @param ar The archive to which to save the serialized property tree.  This archive
     34     *           should conform to the concept laid out by the Boost.Serialization library.
     35     * @param t The property tree to serialize.
     36     * @param file_version file_version for the archive.
     37     * @post @c ar will contain the serialized form of @c t.
     38     */
    2739    template<class Archive, class C, class K, class P, class D, class X>
    2840    inline void save(Archive &ar,
    2941                     const basic_ptree<C, K, P, D, X> &t,
    … …  
    3345        ar << serialization::make_nvp("data", t.data());
    3446    }
    3547
     48    /**
     49     * De-serialize the property tree to the given archive.
     50     * @note In addition to de-serializing from regular archives, this supports loading from
     51     *       archives requiring name-value pairs, e.g. XML archives.  The format should be
     52     *       that used by boost::property_tree::save.
     53     * @param ar The archive from which to load the serialized property tree.  This archive
     54     *           should conform to the concept laid out by the Boost.Serialization library.
     55     * @param t The property tree to de-serialize.
     56     * @param file_version file_version for the archive.
     57     * @post @c t will contain the de-serialized data from @c ar.
     58     */
    3659    template<class Archive, class C, class K, class P, class D, class X>
    3760    inline void load(Archive &ar,
    3861                     basic_ptree<C, K, P, D, X> &t,
    … …  
    5376
    5477    }
    5578
     79    /**
     80     * Load or store the property tree using the given archive.
     81     * @param ar The archive from which to load or save the serialized property tree.
     82     *           The type of this archive will determine whether saving or loading is performed.
     83     * @param t The property tree to load or save.
     84     * @param file_version file_version for the archive.
     85     */
    5686    template<class Archive, class C, class K, class P, class D, class X>
    5787    inline void serialize(Archive &ar,
    5888                          basic_ptree<C, K, P, D, X> &t,

  • boost/property_tree/xml_parser.hpp

     
    3636namespace boost { namespace property_tree { namespace xml_parser
    3737{
    3838
    39     // Read XML from stream
     39    /**
     40     * Reads XML from an input stream and translates it to property tree.
     41     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     42     * @note XML attributes are placed under keys named @c <xmlattr>.
     43     * @throw xml_parser_error In case of error deserializing the property tree.
     44     * @param stream Stream from which to read in the property tree.
     45     * @param[out] pt The property tree to populate.
     46     * @param flags Flags controlling the bahviour of the parser.
     47     *              The following flags are supported:
     48     * @li @c no_concat_text -- Prevents concatenation of text nodes into datastring
     49     *                          of property tree.  Puts them in separate @c <xmltext>
     50     *                          strings instead.
     51     * @li @c no_comments -- Skip XML comments.
     52     */
    4053    template<class Ptree>
    4154    void read_xml(std::basic_istream<typename Ptree::key_type::value_type> &stream,
    4255                  Ptree &pt,
    … …  
    4558        read_xml_internal(stream, pt, flags, std::string());
    4659    }
    4760
    48     // Read XML from file
     61    /**
     62     * Reads XML from a file using the given locale and translates it to property tree.
     63     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     64     * @note XML attributes are placed under keys named @c <xmlattr>.
     65     * @throw xml_parser_error In case of error deserializing the property tree.
     66     * @param file The file from which to read in the property tree.
     67     * @param[out] pt The property tree to populate.
     68     * @param flags Flags controlling the bahviour of the parser.
     69     *              The following flags are supported:
     70     * @li @c no_concat_text -- Prevents concatenation of text nodes into datastring
     71     *                          of property tree.  Puts them in separate @c <xmltext>
     72     *                          strings instead.
     73     * @li @c no_comments -- Skip XML comments.
     74     * @param loc The locale to use when reading in the file contents.
     75     */
    4976    template<class Ptree>
    5077    void read_xml(const std::string &filename,
    5178                  Ptree &pt,
    … …  
    6087        read_xml_internal(stream, pt, flags, filename);
    6188    }
    6289
    63     // Write XML to stream
     90    /**
     91     * Translates the property tree to XML and writes it the given output stream.
     92     * @throw xml_parser_error In case of error translating the property tree to XML
     93     *                         or writing to the output stream.
     94     * @param stream The stream to which to write the XML representation of the
     95     *               property tree.
     96     * @param pt The property tree to tranlsate to XML and output.
     97     * @param settings The settings to use when writing out the property tree as XML.
     98     */
    6499    template<class Ptree>
    65100    void write_xml(std::basic_ostream<typename Ptree::key_type::value_type> &stream,
    66101                   const Ptree &pt,
    … …  
    69104        write_xml_internal(stream, pt, std::string(), settings);
    70105    }
    71106
    72     // Write XML to file
     107    /**
     108     * Translates the property tree to XML and writes it the given file.
     109     * @throw xml_parser_error In case of error translating the property tree to XML
     110     *                         or writing to the output stream.
     111     * @param file The file to which to write the XML representation of the
     112     *               property tree.
     113     * @param pt The property tree to tranlsate to XML and output.
     114     * @param loc The locale to use when writing the output to file.
     115     * @param settings The settings to use when writing out the property tree as XML.
     116     */
    73117    template<class Ptree>
    74118    void write_xml(const std::string &filename,
    75119                   const Ptree &pt,

  • boost/property_tree/ptree.hpp

     
    77//
    88// For more information, see www.boost.org
    99// ----------------------------------------------------------------------------
     10
     11/// This header contains definition of basic_ptree class template and supporting definitions.
     12
    1013#ifndef BOOST_PROPERTY_TREE_PTREE_HPP_INCLUDED
    1114#define BOOST_PROPERTY_TREE_PTREE_HPP_INCLUDED
    1215
    … …  
    3538#include <vector>
    3639#include <cstdlib>
    3740
    38 // Throwing macro to avoid no return warnings portably
    39 #define BOOST_PROPERTY_TREE_THROW(e) { throw_exception(e); std::exit(1); }
     41#if !defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
     42    // Throwing macro to avoid no return warnings portably
     43#   define BOOST_PROPERTY_TREE_THROW(e) { throw_exception(e); std::exit(1); }
     44#endif
    4045
    4146namespace boost { namespace property_tree
    4247{
    4348
     49    /**
     50     * Class template implementing property tree.
     51     *
     52     * A property tree can have data associated with it
     53     * along with a sequence of @c (key,basic_ptree) children.
     54     * Iterators provide bidirectional iterative access into children sequence.
     55     *
     56     * @tparam C Key comparison type
     57     * @tparam K Key type
     58     * @tparam P Path type
     59     * @tparam D Data type
     60     * @tparam X Translator type to use for converting values to and from std::string
     61     */
    4462    template<class C, class K, class P, class D, class X>
    4563    class basic_ptree
    4664    {
     65#if defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
     66    public:
     67#endif
     68        // Internal types
     69        /**
     70         * Simpler way to refer to this basic_ptree<C,K,P,D,X> type.
     71         * Do not use in client code; exposed only for documentation purposes.
     72         */
     73        typedef basic_ptree<C, K, P, D, X> self_type;
    4774
    48     private:
    49 
    50         // Internal types
    51         typedef basic_ptree<C, K, P, D, X> self_type;
    52    
    5375    public:
    54 
    5576        // Basic types
    5677        typedef C key_compare;
    5778        typedef K key_type;
    5879        typedef P path_type;
    5980        typedef D data_type;
    6081        typedef X translator_type;
     82
     83        /**
     84         * Property tree stores a sequence of values of this type.
     85         *
     86         * The first element is the key and the second is the child property tree
     87         * stored at this key.
     88         */
    6189        typedef std::pair<key_type, self_type> value_type;
    6290
    6391    private:
    64 
    6592        // Internal types
    6693        typedef std::list<value_type> container_type;
    6794
    6895    public:
    69        
    7096        // Container-related types
    7197        typedef typename container_type::size_type size_type;
    7298        typedef typename container_type::iterator iterator;
    … …  
    75101        typedef typename container_type::const_reverse_iterator const_reverse_iterator;
    76102
    77103    public:
    78        
    79104        ///////////////////////////////////////////////////////////////////////////
    80105        // Construction & destruction
    81106
     107        /** Creates an empty property tree. */
    82108        basic_ptree();
     109
     110        /**
     111         * Creates a property_tree with the given data.
     112         * @param data Data to be assigned to the tree's data field.
     113         */
    83114        explicit basic_ptree(const data_type &data);
     115
     116        /**
     117         * Copy constructor from another property_tree.
     118         * @param rhs The property tree to be copied.
     119         */
    84120        basic_ptree(const self_type &rhs);
     121
     122        /** Destroys the property tree including recusively destoying all children. */
    85123        ~basic_ptree();
    86124
    87125        ///////////////////////////////////////////////////////////////////////////
    88126        // Iterator access
    89127
     128        /**
     129         * Access to the start of the direct children sequence.
     130         * @return iterator pointing to the first element of the direct children sequence.
     131         */
    90132        iterator begin();
     133
     134        /**
     135         * Const access to the start of the direct children sequence.
     136         * @return const_iterator pointing to the first element of the direct children sequence.
     137         */
    91138        const_iterator begin() const;
     139
     140        /**
     141         * Access to the end of the direct children sequence.
     142         * @return iterator pointing just past the end of the direct children sequence.
     143         */
    92144        iterator end();
     145
     146        /**
     147         * Const access to the end of the direct children sequence.
     148         * @return const_iterator pointing just past the end of the direct children sequence.
     149         */
    93150        const_iterator end() const;
     151
     152        /**
     153         * Access to the start of the reversed direct children sequence.
     154         * @return reverse_iterator pointing to first element of the reversed direct children sequence.
     155         */
    94156        reverse_iterator rbegin();
     157
     158        /**
     159         * Const access to the start of the reversed direct children sequence.
     160         * @return const_reverse_iterator pointing to first element of the reversed direct children sequence.
     161         */
    95162        const_reverse_iterator rbegin() const;
     163
     164        /**
     165         * Access to the end of the reverse direct children sequence.
     166         * @return reverse_iterator pointing just past the end of the reversed direct children sequence.
     167         */
    96168        reverse_iterator rend();
     169
     170        /**
     171         * Const access to the end of the reverse direct children sequence.
     172         * @return const_reverse_iterator pointing just past the end of the reversed direct children sequence.
     173         */
    97174        const_reverse_iterator rend() const;
    98        
     175
    99176        ///////////////////////////////////////////////////////////////////////////
    100177        // Data access
    101178
    102         size_type size() const;
     179        /**
     180         * The size fo the direct children sequnce.
     181         * @return Number of direct children of the property tree.
     182         */
     183        size_type size() const;   
     184
    103185        size_type max_size() const;
     186
     187        /**
     188         * Determine whether the children sequence is empty.
     189         * @note empty() should be prefered over <tt>size() == 0</tt>
     190         * @retval true There are no direct children.
     191         * @retval false There is at least one direct child.
     192         */
    104193        bool empty() const;
    105        
     194
     195        /**
     196         * Retruns a reference to the data of a property tree.
     197         * @return Reference to the stored data which can be used to modify the data.
     198         */
    106199        data_type &data();
     200
     201        /**
     202         * Returns a const reference to the data of a property tree.
     203         * @return Const reference to the stored data.
     204         */
    107205        const data_type &data() const;
    108206
     207        /**
     208         * Returns a reference to the first element in the direct children sequence.
     209         * @pre !(this->empty())
     210         * @return Reference to the first element in the direct children sequence.
     211         */
    109212        value_type &front();
     213
     214        /**
     215         * Returns a const reference to the first element in the direct children sequence.
     216         * @pre !(this->empty())
     217         * @return Const reference to the first element in the direct children sequence.
     218         */
    110219        const value_type &front() const;
     220
     221        /**
     222         * Returns a reference to the last element in the direct children sequence.
     223         * @pre !(this->empty())
     224         * @return Reference to the last element in the direct children sequence.
     225         */
    111226        value_type &back();
     227
     228        /**
     229         * Returns a const reference to the last element in the direct children sequence.
     230         * @pre !(this->empty())
     231         * @return Const reference to the last element in the direct children sequence.
     232         */
    112233        const value_type &back() const;
    113234
    114235        ///////////////////////////////////////////////////////////////////////////
    115236        // Operators
    116237
     238        /**
     239         * Replaces current contents of this property tree with another's contents.
     240         * @param rhs The property tree to assign to this property tree.
     241         */
    117242        self_type &operator =(const self_type &rhs);
    118243
     244        /**
     245         * Check for equality of property trees.
     246         * @retval true If both property trees contain the same data values and equivalent
     247         *              children sequences, recusively.
     248         * @retval false Otherwise.
     249         */
    119250        bool operator ==(const self_type &rhs) const;
     251
     252        /**
     253         * Check for inequality of property trees.
     254         * @return !(*this == rhs)
     255         */
    120256        bool operator !=(const self_type &rhs) const;
    121257
    122258        ///////////////////////////////////////////////////////////////////////////
    123259        // Container operations
    124260
     261        /**
     262         * Finds direct child stored at specified key.
     263         *
     264         * If there is more than one child with the same key, the first one is
     265         * returned. Time complexity is <tt>O(log n)</tt>. Keys equivalence is
     266         * tested with a predicate supplied as basic_ptree template parameter.
     267         * If childe is not found, returns end(). Both const and non-const
     268         * versions are provided. To find non-direct children use get_child
     269         * function.
     270         *
     271         * @param key The key to search in the direct children sequence.
     272         * @return iterator pointing to the found sequence element, or end()
     273         *         if no such element exists.
     274         */
    125275        iterator find(const key_type &key);
     276
     277        /**
     278         * Finds direct child stored at specified key.
     279         *
     280         * If there is more than one child with the same key, the first one is
     281         * returned. Time complexity is <tt>O(log n)</tt>. Keys equivalence is
     282         * tested with a predicate supplied as basic_ptree template parameter.
     283         * If child is not found, returns end(). Both const and non-const
     284         * versions are provided. To find non-direct children use get_child
     285         * function.
     286         *
     287         * @param key The key to search in the direct children sequence.
     288         * @return const_iterator pointing to the found sequence element,
     289         *         or end() if no such element exists.
     290         */
    126291        const_iterator find(const key_type &key) const;
    127292
     293        /**
     294         * Count the number of direct children with the given key.
     295         *
     296         * Keys equivalence is tested with a predicate supplied as basic_ptree
     297         * template parameter.
     298         * @param key Key to count.
     299         * @return Number of direct children with given key.
     300         */
    128301        size_type count(const key_type &key) const;
    129302
     303        /**
     304         * Recursively deletes all children of the property tree and clears the
     305         * data from the property tree.
     306         */
    130307        void clear();
    131308
     309        /**
     310         * Inserts a new direct child into the property tree.
     311         *
     312         * @param where Iterator pointing at the position where new element will be
     313         *              inserted. Passing begin() will insert at the front of the
     314         *              list. Passing end() will insert at the back. Any other
     315         *              valid iterator will insert in the appropriate place in the
     316         *              middle.
     317         * @param value value to be inserted.
     318         * @return iterator pointing to newly inserted element of the sequence.
     319         */
    132320        iterator insert(iterator where, const value_type &value);
     321
     322        /**
     323         * Inserts a range of direct children into the property tree.
     324         *
     325         * Time complexity is <tt>O(m log n)</tt>, where @c m is number of inserted
     326         * children, @c n is number of existing children.
     327         *
     328         * @param where Iterator pointing at the position where new elements will be
     329         *              inserted. Passing begin() will insert at the front of the
     330         *              list. Passing end() will insert at the back. Any other
     331         *              valid iterator will insert in the appropriate place in the
     332         *              middle.
     333         * @param first Iterator designating the first element of range to be
     334         *              inserted.
     335         * @param last Iterator referring to just past the end of the range to be
     336         *             inserted.
     337         */
    133338        template<class It> void insert(iterator where, It first, It last);
    134339
     340        /**
     341         * Erases a direct child from the property tree.
     342         *
     343         * @param where Iterator pointing at the child to be erased from the property tree.
     344         * @return Iterator pointing to the element after the erased element of the sequence,
     345         *         or end() if the element erased was the last in the sequence.
     346         */
    135347        iterator erase(iterator where);
     348
     349        /**
     350         * Erases direct children from the property tree matching the given key.
     351         *
     352         * @param key Key designating child or children to erase.
     353         * @return Number of children that were erased.
     354         */
    136355        size_type erase(const key_type &key);
     356
     357        /**
     358         * Erases a range of direct children from the property tree.
     359         *
     360         * @param first Iterator designating the first element of range to be
     361         *              erased.
     362         * @param last Iterator referring to just past the end of the range to be
     363         *             erased.
     364         */
    137365        template<class It> iterator erase(It first, It last);
    138366
     367        /**
     368         * Inserts a new direct child at the front of the sequence.
     369         *
     370         * Equivalent to insert(begin(), value).
     371         * @param value Value to be inserted.
     372         * @return Iterator pointing to newly inserted element of the sequence.
     373         */
    139374        iterator push_front(const value_type &value);
     375
     376        /**
     377         * Inserts a new direct child at the back of the sequence.
     378         *
     379         * Equivalent to insert(end(), value)
     380         * @param value Value to be inserted.
     381         * @return Iterator pointing to newly inserted element of the sequence.
     382         */
    140383        iterator push_back(const value_type &value);
    141384
     385        /**
     386         * Erases the first direct child in the sequence.
     387         *
     388         * Equivalent to erase(begin()).
     389         * @pre !(this->empty())
     390         */
    142391        void pop_front();
     392
     393        /**
     394         * Erases the last direct child in the sequence.
     395         *
     396         * Equivalent to erase(boost::prior(end())).
     397         * @pre !(this->empty())
     398         */
    143399        void pop_back();
    144400
     401        /**
     402         * Swaps contents of this property tree with the contents of another.
     403         *
     404         * Time complexity is <tt>O(1)</tt>.
     405         * @param rhs Property tree with which to swap.
     406         */
    145407        void swap(self_type &rhs);
    146408
     409        /** Reverses the order of direct children in the property tree. */
    147410        void reverse();
     411
     412        /**
     413         * Sorts direct children of the property tree in ascending order.
     414         * @param tr The binary predicate used to sort child values of type @c #value_type.
     415         * @post For each adjacent child of the sequence, @c v1 followed by @c v2,
     416         *       @c tr(v1,v2) evaluates to true.
     417         */
    148418        template<class SortTr> void sort(SortTr tr);
    149419
    150420        ///////////////////////////////////////////////////////////////////////////
    151421        // ptree operations
    152422
    153         // Get child ptree with default separator
     423        /**
     424         * Get a reference to the child property tree at the given path.
     425         *
     426         * Traverses the tree using the given path and retrieves a child property tree
     427         * stored there.  This function will retrieve indirect children if the path contains
     428         * at least one separator.
     429         * @param path A sequence of keys with zero or more separator characters.
     430         *             Can indicate indirect children if path contains at least one separator
     431         *             character.
     432         * @throw ptree_bad_path if child property tree cannot be located.
     433         * @return A reference to the child property tree at the given path relative to this
     434         *         property tree.
     435         */
    154436        self_type &get_child(const path_type &path);
     437
     438        /**
     439         * Get a const reference to the child property tree at the given path.
     440         *
     441         * Traverses the tree using the given path and retrieves a child property tree
     442         * stored there.  This function will retrieve indirect children if the path contains
     443         * at least one separator.
     444         * @param path A sequence of keys with zero or more separator characters.
     445         *             Can indicate indirect children if path contains at least one separator
     446         *             character.
     447         * @throw ptree_bad_path if child property tree cannot be located.
     448         * @return A const reference to the child property tree at the given path relative to this
     449         *         property tree.
     450         */
    155451        const self_type &get_child(const path_type &path) const;
     452
     453        /**
     454         * Get a reference to the child property tree at the given path or a default if none found.
     455         *
     456         * Traverses the tree using the given path and retrieves a child property tree
     457         * stored there.  This function will retrieve indirect children if the path contains
     458         * at least one separator.  If child isn't found then the @c default_value will be returned.
     459         * @param path A sequence of keys with zero or more separator characters.
     460         *             Can indicate indirect children if path contains at least one separator
     461         *             character.
     462         * @param default_value The value to be returned if no child is found at @c path.
     463         * @return A reference to the child property tree at the given path relative to this
     464         *         property tree or the @c default_value if that child isn't found
     465         */
    156466        self_type &get_child(const path_type &path, self_type &default_value);
     467
     468        /**
     469         * Get a const reference to the child property tree at the given path or a default if none found.
     470         *
     471         * Traverses the tree using the given path and retrieves a child property tree
     472         * stored there.  This function will retrieve indirect children if the path contains
     473         * at least one separator.  If child isn't found then the @c default_value will be returned.
     474         * @note One use of default value is to return a reference to empty property tree if the
     475         *       required one is not found. In many cases, the subsequent code using the return
     476         *       value can be then made simpler. @see boost::property_tree::empty_ptree.
     477         * @param path A sequence of keys with zero or more separator characters.
     478         *             Can indicate indirect children if path contains at least one separator
     479         *             character.
     480         * @param default_value The value to be returned if no child is found at @c path.
     481         * @return A const reference to the child property tree at the given path relative to this
     482         *         property tree or the @c default_value if that child isn't found
     483         */
    157484        const self_type &get_child(const path_type &path, const self_type &default_value) const;
     485
     486        /**
     487         * Get a reference to the child property tree at the given path if it exists.
     488         *
     489         * Traverses the tree using the given path and retrieves a child property tree
     490         * stored there.  This function will retrieve indirect children if the path contains
     491         * at least one separator.
     492         * @param path A sequence of keys with zero or more separator characters.
     493         *             Can indicate indirect children if path contains at least one separator
     494         *             character.
     495         * @return If the child is found, the function returns boost::optional initialized  with
     496         *         a reference to it. Otherwise it returns uninitialized boost::optional.
     497         */
    158498        optional<self_type &> get_child_optional(const path_type &path);
     499
     500        /**
     501         * Get a const reference to the child property tree at the given path if it exists.
     502         *
     503         * Traverses the tree using the given path and retrieves a child property tree
     504         * stored there.  This function will retrieve indirect children if the path contains
     505         * at least one separator.
     506         * @param path A sequence of keys with zero or more separator characters.
     507         *             Can indicate indirect children if path contains at least one separator
     508         *             character.
     509         * @return If the child is found, the function returns boost::optional initialized  with
     510         *         a const reference to it. Otherwise it returns uninitialized boost::optional.
     511         */
    159512        optional<const self_type &> get_child_optional(const path_type &path) const;
    160513
    161         // Put child ptree with default separator
     514        /**
     515         * Traverses the tree using given path, and inserts a new property tree or replaces
     516         * existing one.  If any of the intermediate keys specified by path does not exist,
     517         * it is inserted, with empty data and no children, at the back of existing sequence.
     518         *
     519         * For example, if @c path is "key1.key2.key3", the function will find a child designated
     520         * by "key1.key2" path. This child will be checked for presence of "key3" subkey. If it
     521         * exists, it will be replaced with the one specified by value parameter. If it does not
     522         * exist, "key3" will be added at the back of existing sequence (if any). If either
     523         * "key1" or "key1.key2" do not exist, the function will insert them as well.
     524         *
     525         * This function is a complement to @c #get_child. If @c put_child(path,value) was called,
     526         * @c get_child(path) will return a reference to element inserted/replaced by put_child.
     527         *
     528         * @param path Location to place value.  A sequence of keys with zero or more separator
     529         *             characters.
     530         * @param value Property tree to be inserted as a child of this property tree.
     531         * @param do_not_replace If set to true, causes function to always insert a new key,
     532         *                       even if there already exists key with the same name.
     533         * @return Reference to the inserted property tree.
     534         */
    162535        self_type &put_child(const path_type &path, const self_type &value, bool do_not_replace = false);
    163536
    164         // Get value from data of ptree
     537        /**
     538         * Extracts value stored in property tree data and translates it to Type using
     539         * the given translator.
     540         * @throw ptree_bad_data If data cannot be translated to an instance of @c Type
     541         *                       using the given translator_type.
     542         * @param x Translator to use to extract and convert the contained #data_type to @c Type
     543         *          using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
     544         * @return The extracted value as an instance of @c Type.
     545         */
    165546        template<class Type> Type get_value(const translator_type &x = translator_type()) const;
     547
     548        /**
     549         * Extracts value stored in property tree data and translates it to Type using the
     550         * given translator.  If extraction does not succeed then return the given default value.
     551         * @param detaul_value The value to be returned if the the given translator cannot
     552         *                     extract the data as an instance of @c Type.
     553         * @param x Translator to use to extract and convert the contained #data_type to @c Type
     554         *          using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
     555         * @return The extracted value as an instance of @c Type if extraction succeeds.
     556         *         Otherwise it returns the @c default_value.
     557         */
    166558        template<class Type> Type get_value(const Type &default_value, const translator_type &x = translator_type()) const;
     559
     560        /**
     561         * Extracts value stored in property tree data and translates it to @c std::basic_string<CharType>
     562         * using the given translator.  If extraction does not succeed then return the given default string.
     563         * @param detaul_value The string to be returned if the the given translator cannot
     564         *                     extract the data as an instance of @c Type.
     565         * @param x Translator to use to extract and convert the contained #data_type to @c std::basic_string<CharType>
     566         *          using <tt>bool translator_type::get_value(self_type const&, std::basic_string<CharType>&)</tt>.
     567         * @return The extracted value as an instance of @c std::basic_string<CharType> if extraction succeeds.
     568         *         Otherwise it returns the @c default_value.
     569         */
    167570        template<class CharType> std::basic_string<CharType> get_value(const CharType *default_value, const translator_type &x = translator_type()) const;
     571
     572        /**
     573         * Extracts value stored in property tree data and translates it to Type using the
     574         * given translator.
     575         * @param detaul_value The value to be returned if the the given translator cannot
     576         *                     extract the data as an instance of @c Type.
     577         * @param x Translator to use to extract and convert the contained #data_type to @c Type
     578         *          using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
     579         * @return The extracted value as an instance of @c Type if extraction succeeds.
     580         *         Otherwise it returns an uninitialized @c boost::optional<Type>.
     581         */
    168582        template<class Type> optional<Type> get_value_optional(const translator_type &x = translator_type()) const;
    169583
    170         // Get value from data of child ptree (default path separator)
     584        /**
     585         * Get the property tree value at the given path.
     586         *
     587         * Traverses the tree using the given path and retrieves the value stored there.
     588         * This function will retrieve values of indirect children if the path contains at least
     589         * one separator.  The value will be converted to an instance of @c Type using the
     590         * given translator.
     591         * @param path A sequence of keys with zero or more separator characters.
     592         *             Can indicate indirect children if path contains at least one separator
     593         *             character.
     594         * @param x Translator to use to extract and convert the contained #data_type to @c Type
     595         *          using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
     596         * @throw ptree_bad_path if child property tree cannot be located using the given path.
     597         * @return The child property tree's value at the given path relative to this
     598         *         property tree.
     599         */
    171600        template<class Type> Type get(const path_type &path, const translator_type &x = translator_type()) const;
     601
     602        /**
     603         * Get the property tree value at the given path or a default if none found.
     604         *
     605         * Traverses the tree using the given path and retrieves the value stored there
     606         * This function will retrieve values of indirect children if the path contains at least
     607         * one separator.  The value will be converted to an instance of @c Type using the
     608         * given translator.  If child isn't found then the @c default_value will be returned.
     609         * @param path A sequence of keys with zero or more separator characters.
     610         *             Can indicate indirect children if path contains at least one separator
     611         *             character.
     612         * @param default_value The value to be returned if no child is found at @c path
     613         *                      or translation fails.
     614         * @param x Translator to use to extract and convert the contained #data_type to @c Type
     615         *          using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
     616         * @return The child property tree's value at the given path relative to this
     617         *         property tree or the @c default_value if that child is not found.
     618         */
    172619        template<class Type> Type get(const path_type &path, const Type &default_value, const translator_type &x = translator_type()) const;
     620
     621        /**
     622         * Get the property tree value as @c std::basic_string<CharType> at the given path
     623         * or a default if none found.
     624         *
     625         * Traverses the tree using the given path and retrieves the value stored there
     626         * This function will retrieve values of indirect children if the path contains at least
     627         * one separator.  The value will be converted to an instance of
     628         * @c std::basic_string<CharType> using the given translator.  If child isn't
     629         * found then the @c default_value will be returned.
     630         * @param path A sequence of keys with zero or more separator characters.
     631         *             Can indicate indirect children if path contains at least one separator
     632         *             character.
     633         * @param default_value The string to be returned if no child is found at @c path
     634         *                       or translation fails.
     635         * @param x Translator to use to extract and convert the contained #data_type to @c std::basic_string<CharType>
     636         *          using <tt>bool translator_type::get_value(self_type const&, std::basic_string<CharType>&)</tt>.
     637         * @return The child property tree's value as @c std::basic_string<CharType> at
     638         *         the given path relative to this property tree or the @c default_value
     639         *         if that child is not found or translation fails.
     640         */
    173641        template<class CharType> std::basic_string<CharType> get(const path_type &path, const CharType *default_value, const translator_type &x = translator_type()) const;
     642
     643        /**
     644         * Get the property tree value at the given path or an uninitialized
     645         * @c boost::optional<Type> if none found.
     646         *
     647         * Traverses the tree using the given path and retrieves the value stored there
     648         * This function will retrieve values of indirect children if the path contains at least
     649         * one separator.  The value will be converted to an instance of @c Type using the
     650         * given translator.  If child isn't found then an unitialized @c boost::optional<Type>
     651         * will be returned.
     652         * @param path A sequence of keys with zero or more separator characters.
     653         *             Can indicate indirect children if path contains at least one separator
     654         *             character.
     655         * @param x Translator to use to extract and convert the contained #data_type to @c Type
     656         *          using <tt>bool translator_type::get_value(self_type const&, Type&)</tt>.
     657         * @return The child property tree's value at the given path relative to this
     658         *         property tree or an unitialized @c boost::optional<Type> if that child is not
     659         *        found or translation fails.
     660         */
    174661        template<class Type> optional<Type> get_optional(const path_type &path, const translator_type &x = translator_type()) const;
    175662
    176         // Put value in data of ptree
     663        /**
     664         * Store the given value as the data of this property tree.
     665         *
     666         * Translates @c value from @c Type to @c #data_type using the given translator, and stores the
     667         * result as the data value of this property tree.
     668         * @throw ptree_bad_data If the given value cannot be translated to @c #data_type.
     669         * @param value The parameter to store as the data of this property tree.
     670         * @param x Translator to use to convert @c value to an instance of @c #data_type
     671         *          using <tt>bool translator_type::put_value(self_type&,Type const&)</tt>.
     672         */
    177673        template<class Type> void put_value(const Type &value, const translator_type &x = translator_type());
    178674
    179         // Put value in data of child ptree (default path separator)
     675        /**
     676         * Traverses the tree using given path, and inserts a new value or replaces existing one.
     677         * If any of the intermediate keys specified by path does not exist, it is inserted,
     678         * with empty data and no children, at the back of existing sequence.
     679         *
     680         * For example, if @c path is "key1.key2.key3", the function will find a child designated
     681         * by "key1.key2" path. This child will be checked for presence of "key3" subkey. If it
     682         * exists, it will be replaced with the one specified by value parameter. If it does not
     683         * exist, "key3" will be added at the back of existing sequence (if any). If either
     684         * "key1" or "key1.key2" do not exist, the function will insert them as well.
     685         *
     686         * This function is a complement to @c #get. If @c put(path,value) was called,
     687         * @c get(path) will return the value inserted by @c #put.
     688         *
     689         * @param path Location to place value.  A sequence of keys with zero or more separator
     690         *             characters.
     691         * @param value value to be inserted as the data of a child of this property tree.
     692         * @param do_not_replace If set to true, causes function to always insert a new key,
     693         *                       even if there already exists key with the same name.
     694         * @param x Translator to use to convert @c value to an instance of @c #data_type
     695         *          using <tt>bool translator_type::put_value(self_type&,Type const&)</tt>.
     696         * @return Reference to the property tree where the value was inserted.  It is either a
     697         *         newly inserted property tree or an existing one if it was there prior to
     698         *         this call.
     699         */
    180700        template<class Type> self_type &put(const path_type &path, const Type &value, bool do_not_replace = false, const translator_type &x = translator_type());
    181701
    182702    private:
    … …  
    200720    ///////////////////////////////////////////////////////////////////////////
    201721    // basic_path class template
    202722
     723    /** Class template used to represent a path containing a sequence of Key instances. */
    203724    template<class Key>
    204725    class basic_path
    205726    {
    206 
    207     private:
    208 
     727#if defined(BOOST_PROPERTY_TREE_DOXYGEN_INVOKED)
     728    public:
     729#endif
     730        /**
     731         * Simpler way to refer to the Key::value_type type.
     732         * Do not use in client code; exposed only for documentation purposes.
     733         */
    209734        typedef typename Key::value_type char_type;
    210735
    211736    public:
    … …  
    213738        ///////////////////////////////////////////////////////////////////////
    214739        // Construction & destruction
    215740
     741        /** Constructs an empty basic_path<Key> instance */
    216742        basic_path();
     743
     744        /**
     745         * Constructs an path using the given path using the given separator to split it.
     746         * @param path The path to which to initialize the constructed instance.
     747         * @param separator The separator to use to split the @c path parameter.
     748         */
    217749        basic_path(const Key &path, char_type separator = char_type('.'));
     750
     751        /**
     752         * Constructs an path using the given path using the given separator to split it.
     753         * @param path The path to which to initialize the constructed instance.  This
     754         *             path instance must be terminated with char_type('\0');
     755         * @param separator The separator to use to split the @c path parameter.
     756         */
    218757        basic_path(const char_type *path, char_type separator = char_type('.'));
    219        
     758
    220759        ///////////////////////////////////////////////////////////////////////
    221760        // Path manipulation
    222761
     762        /**
     763         * Append the given path to this instance.
     764         * @param rhs The path to append.
     765         * @return A reference to this path instance after appending @c rhs.
     766         */
    223767        basic_path<Key> &operator /=(const basic_path<Key> &rhs);
     768
     769        /**
     770         * Convert this path instance to a @c std::string representation.
     771         * @return A string representation of this path.
     772         */
    224773        std::string to_string() const;
    225774
    226775        ///////////////////////////////////////////////////////////////////////
    227776        // Operations
    228777
     778        /**
     779         * Extract the child subtree of the given property tree at the location indicated
     780         * by this path instance.
     781         * @param root The property tree from which to extract the child subtree.
     782         * @return Pointer to the child subtree of the input property tree indicated by the
     783         *         location given by this path instance.  If no child exists at the indicated
     784         *         location then NULL is returned.
     785         */
    229786        template<class C, class D, class X>
    230787        basic_ptree<C, Key, basic_path<Key>, D, X> *get_child(basic_ptree<C, Key, basic_path<Key>, D, X> &root) const;
    231        
     788
     789        /**
     790         * Extract the child subtree of the given property tree at the location indicated
     791         * by this path instance.
     792         * @param root The property tree from which to extract the child subtree.
     793         * @return Pointer to the constant child subtree of the input property tree indicated by the
     794         *         location given by this path instance.  If no child exists at the indicated
     795         *         location then NULL is returned.
     796         */
    232797        template<class C, class D, class X>
    233798        const basic_ptree<C, Key, basic_path<Key>, D, X> *get_child(const basic_ptree<C, Key, basic_path<Key>, D, X> &root) const;
    234799
     800        /**
     801         * Insert or replace in the given property tree at the location indicated by this path
     802         * instance the second given property tree as a child.
     803         * @param root The property tree in which to insert or replace the child.
     804         * @param child The property tree to insert within the tree given by that @c root parameter.
     805         * @param do_not_replace If set to true, causes function to always insert a new key,
     806         *                       even if there already exists key with the same name.  Otherwise
     807         * @return Pointer to the child property tree inserted at the given location
     808         *         location given by this path instance.  If this path is empty then return NULL.
     809         */
    235810        template<class C, class D, class X>
    236811        basic_ptree<C, Key, basic_path<Key>, D, X> *put_child(basic_ptree<C, Key, basic_path<Key>, D, X> &root,
    237812                                                              const basic_ptree<C, Key, basic_path<Key>, D, X> &child,
    … …  
    255830    {
    256831
    257832    public:
     833        /** Default construct a translator instance. */
     834        translator();
    258835
    259         translator();
     836        /**
     837         * Construct a translator instance setting the internal locale state using
     838         * the given input locale.
     839         * @param loc The locale to use in this instance.
     840         */
    260841        translator(const std::locale &loc);
    261842
     843        /**
     844         * Extract data value from the given property tree and convert it to an
     845         * instance of type @c T.
     846         * @param pt Property tree from which to retrieve the data value.
     847         * @param[out] value The variable in which to store the retrieved data value.
     848         * @return @c true If the data value was sucessfully converted and retrieved.
     849         *         Otherwise return @c false.
     850         */
    262851        template<class Ptree, class T> bool get_value(const Ptree &pt, T &value) const;
     852
     853        /**
     854         * Insert the given value as the data member in the given property tree after
     855         * converting it to instance of type @c Ptree::data_type.
     856         * @param pt Property tree in which to insert the given value as data.
     857         * @param value The value to store as data in the given property tree.
     858         * @return @c true If the data value was sucessfully converted and retrieved.
     859         *         Otherwise return @c false.
     860         */
    263861        template<class Ptree, class T> bool put_value(Ptree &pt, const T &value) const;
    264862
    265863    private:
    … …  
    271869    ///////////////////////////////////////////////////////////////////////////
    272870    // exceptions
    273871
    274     // Base error class
     872    /// Base class for all property tree errors. Derives from @c std::runtime_error.
     873    /// Call member function @c what to get human readable message associated with the error.
    275874    class ptree_error: public std::runtime_error
    276875    {
    277    
    278876    public:
    279    
     877        /// Instantiate a ptree_error instance with the given message.
     878        /// @param what The message to associate with this error.
    280879        ptree_error(const std::string &what);
     880
    281881        ~ptree_error() throw();
    282 
    283882    };
    284883
    285     // Bad data
     884
     885    /// Error indicating that translation from given value to the property tree data_type
     886    /// (or vice versa) failed. Derives from ptree_error.
    286887    class ptree_bad_data: public ptree_error
    287888    {
    288    
    289889    public:
    290    
     890        /// Instantiate a ptree_bad_data instance with the given message and data.
     891        /// @param what The message to associate with this error.
     892        /// @param data The value associated with this error that was the source of the
     893        ///             translation failure.
    291894        template<class T> ptree_bad_data(const std::string &what, const T &data);
     895
    292896        ~ptree_bad_data() throw();
     897
     898        /// Retrieve the data associated with this error.  This is the source value that
     899        /// failed to be translated.
    293900        template<class T> T data();
    294    
    295901    private:
    296 
    297902        boost::any m_data;
     903    };
    298904
    299     };
    300    
    301     // Bad path
     905
     906    /// Error indicating that specified path does not exist. Derives from ptree_error.
    302907    class ptree_bad_path: public ptree_error
    303908    {
    304    
    305909    public:
    306    
     910        /// Instantiate a ptree_bad_path with the given message and path data.
     911        /// @param what The message to associate with this error.
     912        /// @param path The path that could not be found in the property_tree.
    307913        template<class T> ptree_bad_path(const std::string &what, const T &path);
     914
    308915        ~ptree_bad_path() throw();
     916
     917        /// Retrieve the invalid path.
    309918        template<class T> T path();
    310 
    311919    private:
    312 
    313920        boost::any m_path;
    314 
    315921    };
    316922
    317923} }

  • boost/property_tree/ptree_fwd.hpp

     
    3131    ///////////////////////////////////////////////////////////////////////////
    3232    // Typedefs
    3333
     34    /** Implements a path using a std::string as the key. */
    3435    typedef basic_path<std::string> path;
     36
     37    /** Implements a path using a std::wstring as the key. */
    3538    typedef basic_path<std::wstring> wpath;
    3639
     40    /**
     41     * A property tree that uses a path type based upon std::string.
     42     * Comparisons of keys are performed in a case-sensitive manner.
     43     */
    3744    typedef basic_ptree<std::less<std::string>, std::string, path, std::string, translator> ptree;
     45
     46    /**
     47     * A property tree that uses a path type based upon std::string.
     48     * Comparisons of keys are performed in a case-insensitive manner.
     49     */
    3850    typedef basic_ptree<detail::less_nocase<std::string>, std::string, path, std::string, translator> iptree;
     51
    3952#ifndef BOOST_NO_CWCHAR
     53    /**
     54     * A property tree that uses a wide-character path type based upon std::wstring.
     55     * Comparisons of keys are performed in a case-sensitive manner.
     56     * @note The type only exists if the platform supports @c wchar_t.
     57     */
    4058    typedef basic_ptree<std::less<std::wstring>, std::wstring, wpath, std::wstring, translator> wptree;
     59
     60    /**
     61     * A property tree that uses a wide-character path type based upon std::wstring.
     62     * Comparisons of keys are performed in a case-insensitive manner.
     63     * @note The type only exists if the platform supports @c wchar_t.
     64     */
    4165    typedef basic_ptree<detail::less_nocase<std::wstring>, std::wstring, wpath, std::wstring, translator> wiptree;
    4266#endif
    4367
    4468    ///////////////////////////////////////////////////////////////////////////
    4569    // Free functions
    4670
    47     template<class C, class K, class P, class D, class X> void swap(basic_ptree<C, K, P, D, X> &pt1, basic_ptree<C, K, P, D, X> &pt2);
     71    /**
     72     * Swap two property tree instances.
     73     * @param pt1 Reference to first property tree involved in swap.
     74     * @param[in/out] pt2 Reference to second property tree involved in swap.
     75     */
     76    template<class C, class K, class P, class D, class X>
     77    void swap(basic_ptree<C, K, P, D, X> &pt1, basic_ptree<C, K, P, D, X> &pt2);
     78
     79    /**
     80     * Reference to empty property tree. Can be used as a default value of get_child.
     81     * See empty_ptree_trick.cpp for example of usage.
     82     */
    4883    template<class Ptree> const Ptree &empty_ptree();
     84
     85    /** Join two path objects. */
    4986    path operator /(const path &p1, const path &p2);
     87
     88    /** Join two wide-path objects. */
    5089    wpath operator /(const wpath &p1, const wpath &p2);
    5190
    5291} }

  • boost/property_tree/json_parser.hpp

     
    2222namespace boost { namespace property_tree { namespace json_parser
    2323{
    2424
    25     // Read json from stream
     25    /**
     26     * Read JSON from a the given stream and translate it to a property tree.
     27     * @note Clears existing contents of property tree.  In case of error the
     28     *       property tree unmodified.
     29     * @note Items of JSON arrays are translated into ptree keys with empty
     30     *       names. Members of objects are translated into named keys.
     31     * @note JSON data can be a string, a numeric value, or one of literals
     32     *       "null", "true" and "false". During parse, any of the above is copied
     33     *       verbatim into ptree data string.
     34     * @throw json_parser_error In case of error deserializing the property tree.
     35     * @param stream Stream from which to read in the property tree.
     36     * @param[out] pt The property tree to populate.
     37     */
    2638    template<class Ptree>
    2739    void read_json(std::basic_istream<typename Ptree::key_type::value_type> &stream,
    2840                   Ptree &pt)
    … …  
    3042        read_json_internal(stream, pt, std::string());
    3143    }
    3244
    33     // Read json from file
     45    /**
     46     * Read JSON from a the given file and translate it to a property tree.
     47     * @note Clears existing contents of property tree.  In case of error the
     48     *       property tree unmodified.
     49     * @note Items of JSON arrays are translated into ptree keys with empty
     50     *       names. Members of objects are translated into named keys.
     51     * @note JSON data can be a string, a numeric value, or one of literals
     52     *       "null", "true" and "false". During parse, any of the above is copied
     53     *       verbatim into ptree data string.
     54     * @throw json_parser_error In case of error deserializing the property tree.
     55     * @param filename Name of file from which to read in the property tree.
     56     * @param[out] pt The property tree to populate.
     57     * @param loc The locale to use when reading in the file contents.
     58     */
    3459    template<class Ptree>
    3560    void read_json(const std::string &filename,
    3661                   Ptree &pt,
    … …  
    4368        read_json_internal(stream, pt, filename);
    4469    }
    4570
    46     // Write json to stream
     71    /**
     72     * Translates the property tree to JSON and writes it the given output stream.
     73     * @note Any property tree key containing only unnamed subkeys will be rendered
     74     *       as JSON arrays.
     75     * @pre @e pt cannot contain keys that have both subkeys and non-empty data.
     76     * @throw json_parser_error In case of error translating the property tree to JSON
     77     *                         or writing to the output stream.
     78     * @param stream The stream to which to write the JSON representation of the
     79     *               property tree.
     80     * @param pt The property tree to tranlsate to JSON and output.
     81     */
    4782    template<class Ptree>
    4883    void write_json(std::basic_ostream<typename Ptree::key_type::value_type> &stream,
    4984                    const Ptree &pt)
    … …  
    5186        write_json_internal(stream, pt, std::string());
    5287    }
    5388
    54     // Write json to file
     89    /**
     90     * Translates the property tree to JSON and writes it the given file.
     91     * @note Any property tree key containing only unnamed subkeys will be rendered
     92     *       as JSON arrays.
     93     * @pre @e pt cannot contain keys that have both subkeys and non-empty data.
     94     * @throw json_parser_error In case of error translating the property tree to JSON
     95     *                         or writing to the file.
     96     * @param filename The name of the file to which to write the JSON representation
     97     *                 of the property tree.
     98     * @param pt The property tree to tranlsate to JSON and output.
     99     * @param loc The locale to use when writing out to the output file.
     100     */
    55101    template<class Ptree>
    56102    void write_json(const std::string &filename,
    57103                    const Ptree &pt,

  • boost/property_tree/info_parser.hpp

     
    2020namespace boost { namespace property_tree { namespace info_parser
    2121{
    2222
    23     // Read info from stream
     23    /**
     24     * Read INFO from a the given stream and translate it to a property tree.
     25     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     26     * @throw info_parser_error On error translating the INFO stream to a property tree.
     27     * @param stream Stream from which to read in the property tree.
     28     * @param[out] pt The property tree to populate.
     29     */
    2430    template<class Ptree, class Ch>
    2531    void read_info(std::basic_istream<Ch> &stream,
    2632                   Ptree &pt)
    … …  
    3036        pt.swap(local);
    3137    }
    3238
    33     // Read info from stream with default
     39    /**
     40     * Read INFO from a the given stream and translate it to a property tree.
     41     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     42     * @param stream Stream from which to read in the property tree.
     43     * @param[out] pt The property tree to populate.
     44     * @param default_ptree The property tree to which to set @c pt on error reading the INFO stream.
     45     */
    3446    template<class Ptree, class Ch>
    3547    void read_info(std::basic_istream<Ch> &stream,
    3648                   Ptree &pt,
    … …  
    4658        }
    4759    }
    4860
    49     // Read info from file
     61    /**
     62     * Read INFO from a the given file and translate it to a property tree.
     63     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     64     * @throw info_parser_error On error translating the INFO stream to a property tree.
     65     * @param filename Name of file from which to read in the property tree.
     66     * @param[out] pt The property tree to populate.
     67     * @param loc The locale to use when reading in the file contents.
     68     */
    5069    template<class Ptree>
    5170    void read_info(const std::string &filename,
    5271                   Ptree &pt,
    … …  
    6180        pt.swap(local);
    6281    }
    6382
    64     // Read info from file with default
     83    /**
     84     * Read INFO from a the given file and translate it to a property tree.
     85     * @note Clears existing contents of property tree.  In case of error the property tree unmodified.
     86     * @param filename Name of file from which to read in the property tree.
     87     * @param[out] pt The property tree to populate.
     88     * @param loc The locale to use when reading in the file contents.
     89     * @param default_ptree The property tree to which to set @c pt on error reading the INFO stream.
     90     */
    6591    template<class Ptree>
    6692    void read_info(const std::string &filename,
    6793                   Ptree &pt,
    … …  
    78104        }
    79105    }
    80106
    81     // Write info to stream
     107    /**
     108     * Translates the property tree to INFO and writes it the given output stream.
     109     * @throw info_parser_error In case of error translating the property tree to INFO
     110     *                          or writing to the output stream.
     111     * @param stream The stream to which to write the INFO representation of the
     112     *               property tree.
     113     * @param pt The property tree to tranlsate to INFO and output.
     114     * @param settings The settings to use when writing the INFO data.
     115     */
    82116    template<class Ptree, class Ch>
    83117    void write_info(std::basic_ostream<Ch> &stream,
    84118                    const Ptree &pt,
    … …  
    87121        write_info_internal(stream, pt, std::string(), settings);
    88122    }
    89123
    90     // Write info to file
     124    /**
     125     * Translates the property tree to INFO and writes it the given file.
     126     * @throw info_parser_error In case of error translating the property tree to INFO
     127     *                          or writing to the file.
     128     * @param filename The name of the file to which to write the INFO representation
     129     *                 of the property tree.
     130     * @param pt The property tree to tranlsate to INFO and output.
     131     * @param settings The settings to use when writing the INFO data.
     132     * @param loc The locale to use when writing the file.
     133     */
    91134    template<class Ptree>
    92135    void write_info(const std::string &filename,
    93136                    const Ptree &pt,