include/json/value.h

#pragma once

#include "adt/make.h"
#include "forwards.h"

#include <map>
#include <string>
#include <vector>

/** \brief JSON (JavaScript Object Notation).
 */
namespace Json
{
  /** \brief Type of the value held by a Value object.
   */
  enum ValueType
  {
    nullValue = 0,   ///< 'null' value */
    intValue,        ///< signed integer value */
    uintValue,       ///< unsigned integer value */
    realValue,       ///< double value */
    stringValue,     ///< UTF-8 string value */
    booleanValue,    ///< bool value */
    arrayValue,      ///< array value (ordered list) */
    objectValue      ///< object value (collection of name/value pairs). */
  };

  enum CommentPlacement
  {
    commentBefore = 0,          ///< a comment placed on the line before a value */
    commentAfterOnSameLine,     ///< a comment just after a value on the same line */
    commentAfter,               ///< a comment on the line after a value (only make sense for root value) */
    numberOfCommentPlacement
  };

  /** \brief Lightweight wrapper to tag static string.
   *
   * Value constructor and objectValue member assignement takes advantage of the
   * StaticString and avoid the cost of string duplication when storing the
   * string or the member name.
   *
   * Example of usage:
   * \code
   * Json::Value aValue( StaticString("some text") );
   * Json::Value object;
   * static const StaticString code("code");
   * object[code] = 1234;
   * \endcode
   */
  class JSON_API StaticString
  {
  public:
    explicit StaticString (const char *czstring)
      : str_ (czstring)
    {
    }

    const char *c_str () const
    {
      return str_;
    }

  private:
    const char *str_;
  };

  /** \brief Represents a <a href="http://www.json.org">JSON</a> value.
   *
   * This class is a discriminated union wrapper that can represents a:
   * - signed integer [range: Value::minInt - Value::maxInt]
   * - unsigned integer (range: 0 - Value::maxUInt)
   * - double
   * - UTF-8 string
   * - boolean
   * - 'null'
   * - an ordered list of Value
   * - collection of name/value pairs (javascript object)
   *
   * The type of the held value is represented by a #ValueType and
   * can be obtained using type().
   *
   * values of an #objectValue or #arrayValue can be accessed using operator[]() methods.
   * Non const methods will automatically create the a #nullValue element
   * if it does not exist.
   * The sequence of an #arrayValue will be automatically resize and initialized
   * with #nullValue. resize() can be used to enlarge or truncate an #arrayValue.
   *
   * The get() methods can be used to obtanis default value in the case the required element
   * does not exist.
   *
   * It is possible to iterate over the list of a #objectValue values using
   * the getMemberNames() method.
   */
  class JSON_API Value
  {
    friend class ValueIteratorBase;

  public:
    typedef std::vector<std::string> Members;
    typedef ValueIterator iterator;
    typedef ValueConstIterator const_iterator;
    typedef Json::UInt UInt;
    typedef Json::Int Int;
    typedef UInt ArrayIndex;

    static const Value null;
    static const Int minInt;
    static const Int maxInt;
    static const UInt maxUInt;

  private:
    class CZString
    {
    public:
      enum DuplicationPolicy
      {
        noDuplication = 0,
        duplicate,
        duplicateOnCopy
      };
      CZString (int index);
      CZString (const char *cstr, DuplicationPolicy allocate);
      CZString (const CZString &other);
      ~CZString ();
      CZString &operator = (const CZString &other);
      bool operator < (const CZString &other) const;
      bool operator == (const CZString &other) const;
      int index () const;
      const char *c_str () const;
      bool isStaticString () const;

    private:
      void swap (CZString &other);
      const char *cstr_;
      long index_;
    };

  public:
    typedef std::map<CZString, Value> ObjectValues;

  public:
    /** \brief Create a default Value of the given type.
     *
     * This is a very useful constructor.
     * To create an empty array, pass arrayValue.
     * To create an empty object, pass objectValue.
     * Another Value can then be set to this one by assignment.
     * This is useful since clear() and resize() will not alter types.
     *
     * Examples:
     * \code
     * Json::Value null_value; // null
     * Json::Value arr_value(Json::arrayValue); // []
     * Json::Value obj_value(Json::objectValue); // {}
     * \endcode
     */
    Value (ValueType type = nullValue);
    Value (Int value);
    Value (UInt value);
    Value (double value);
    Value (const char *value);
    Value (const char *beginValue, const char *endValue);
    Value (make::array const &value);
    Value (make::map const &value);
    /** \brief Constructs a value from a static string.
     *
     * Like other value string constructor but do not duplicate the string for
     * internal storage. The given string must remain alive after the call to this
     * constructor.
     * Example of usage:
     * \code
     * Json::Value aValue( StaticString("some text") );
     * \endcode
     */
    Value (const StaticString &value);
    Value (const std::string &value);
    Value (bool value);
    Value (const Value &other);
    ~Value ();

    Value &operator = (const Value &other);
    /*
     * / Swap values.
     * / \note Currently, comments are intentionally not swapped, for
     * / both logic and efficiency.
     */
    void swap (Value &other);

    ValueType type () const;

    bool operator < (const Value &other) const;
    bool operator <= (const Value &other) const;
    bool operator >= (const Value &other) const;
    bool operator > (const Value &other) const;

    bool operator == (const Value &other) const;
    bool operator != (const Value &other) const;

    int compare (const Value &other);

    const char *asCString () const;
    std::string asString () const;
    Int asInt () const;
    UInt asUInt () const;
    double asDouble () const;
    bool asBool () const;

    bool isNull () const;
    bool isBool () const;
    bool isInt () const;
    bool isUInt () const;
    bool isIntegral () const;
    bool isDouble () const;
    bool isNumeric () const;
    bool isString () const;
    bool isArray () const;
    bool isObject () const;

    bool isConvertibleTo (ValueType other) const;

    /* / Number of values in array or object */
    UInt size () const;

    /*
     * / \brief Return true if empty array, empty object, or null;
     * / otherwise, false.
     */
    bool empty () const;

    /* / Return isNull() */
    bool operator ! () const;

    /*
     * / Remove all object members and array elements.
     * / \pre type() is arrayValue, objectValue, or nullValue
     * / \post type() is unchanged
     */
    void clear ();

    /*
     * / Resize the array to size elements.
     * / New elements are initialized to null.
     * / May only be called on nullValue or arrayValue.
     * / \pre type() is arrayValue or nullValue
     * / \post type() is arrayValue
     */
    void resize (UInt size);

    /*
     * / Access an array element (zero based index ).
     * / If the array contains less than index element, then null value are inserted
     * / in the array so that its size is index+1.
     * / (You may need to say 'value[0u]' to get your compiler to distinguish
     * /  this from the operator[] which takes a string.)
     */
    Value &operator [] (UInt index);
    Value &operator [] (int index) { return (*this)[UInt (index)]; }
    /*
     * / Access an array element (zero based index )
     * / (You may need to say 'value[0u]' to get your compiler to distinguish
     * /  this from the operator[] which takes a string.)
     */
    const Value &operator [] (UInt index) const;
    /*
     * / If the array contains at least index+1 elements, returns the element value,
     * / otherwise returns defaultValue.
     */
    Value get (UInt index, const Value &defaultValue) const;
    /* / Return true if index < size(). */
    bool isValidIndex (UInt index) const;
    /*
     * / \brief Append value to array at the end.
     * /
     * / Equivalent to jsonvalue[jsonvalue.size()] = value;
     */
    Value &append (const Value &value);

    /* / Access an object value by name, create a null member if it does not exist. */
    Value &operator [] (const char *key);
    /* / Access an object value by name, returns null if there is no member with that name. */
    const Value &operator [] (const char *key) const;
    /* / Access an object value by name, create a null member if it does not exist. */
    Value &operator [] (const std::string &key);
    /* / Access an object value by name, returns null if there is no member with that name. */
    const Value &operator [] (const std::string &key) const;
    /** \brief Access an object value by name, create a null member if it does not exist.
     *
     * If the object as no entry for that name, then the member name used to store
     * the new entry is not duplicated.
     * Example of use:
     * \code
     * Json::Value object;
     * static const StaticString code("code");
     * object[code] = 1234;
     * \endcode
     */
    Value &operator [] (const StaticString &key);
    /* / Return the member named key if it exist, defaultValue otherwise. */
    Value get (const char *key, const Value &defaultValue) const;
    /* / Return the member named key if it exist, defaultValue otherwise. */
    Value get (const std::string &key, const Value &defaultValue) const;
    /*
     * / \brief Remove and return the named member.
     * /
     * / Do nothing if it did not exist.
     * / \return the removed Value, or null.
     * / \pre type() is objectValue or nullValue
     * / \post type() is unchanged
     */
    Value removeMember (const char *key);
    /* / Same as removeMember(const char*) */
    Value removeMember (const std::string &key);

    /* / Return true if the object has a member named key. */
    bool isMember (const char *key) const;
    /* / Return true if the object has a member named key. */
    bool isMember (const std::string &key) const;

    /*
     * / \brief Return a list of the member names.
     * /
     * / If null, return an empty list.
     * / \pre type() is objectValue or nullValue
     * / \post if type() was nullValue, it remains nullValue
     */
    Members getMemberNames () const;

    /* / Comments must be //... or / * ... * / */
    void setComment (const char *comment, CommentPlacement placement);
    /* / Comments must be //... or / * ... * / */
    void setComment (const std::string &comment, CommentPlacement placement);
    bool hasComment (CommentPlacement placement) const;
    /* / Include delimiters and embedded newlines. */
    std::string getComment (CommentPlacement placement) const;

    std::string toStyledString () const;

    const_iterator begin () const;
    const_iterator end () const;

    iterator begin ();
    iterator end ();

  private:
    Value &resolveReference (const char *key, bool isStatic);

  private:
    struct CommentInfo
    {
      CommentInfo ();
      ~CommentInfo ();

      void setComment (const char *text);

      char *comment_;
    };

    /*
     * struct MemberNamesTransform
     * {
     *   typedef const char *result_type;
     *   const char *operator()( const CZString &name ) const
     *   {
     *      return name.c_str();
     *   }
     * };
     */

    union ValueHolder
    {
      Int int_;
      UInt uint_;
      double real_;
      bool bool_;
      char *string_;
      ObjectValues *map_;
    } value_;
    CommentInfo *comments_;
    ValueType type_;
    bool allocated_;
  };


  /** \brief Experimental and untested: represents an element of the "path" to access a node.
   */
  class PathArgument
  {
  public:
    friend class Path;

    PathArgument ();
    PathArgument (UInt index);
    PathArgument (const char *key);
    PathArgument (const std::string &key);

  private:
    enum Kind
    {
      kindNone = 0,
      kindIndex,
      kindKey
    };
    std::string key_;
    UInt index_;
    Kind kind_;
  };

  /** \brief Experimental and untested: represents a "path" to access a node.
   *
   * Syntax:
   * - "." => root node
   * - ".[n]" => elements at index 'n' of root node (an array value)
   * - ".name" => member named 'name' of root node (an object value)
   * - ".name1.name2.name3"
   * - ".[0][1][2].name1[3]"
   * - ".%" => member name is provided as parameter
   * - ".[%]" => index is provied as parameter
   */
  class Path
  {
  public:
    Path (const std::string &path, const PathArgument &a1 = PathArgument (), const PathArgument &a2 = PathArgument (), const PathArgument &a3 = PathArgument (), const PathArgument &a4 = PathArgument (), const PathArgument &a5 = PathArgument ());

    const Value &resolve (const Value &root) const;
    Value resolve (const Value &root, const Value &defaultValue) const;
    /* / Creates the "path" to access the specified node and returns a reference on the node. */
    Value &make (Value &root) const;

  private:
    typedef std::vector<const PathArgument *> InArgs;
    typedef std::vector<PathArgument> Args;

    void makePath (const std::string &path, const InArgs &in);
    void addPathInArg (const std::string &path, const InArgs &in, InArgs::const_iterator &itInArg, PathArgument::Kind kind);
    void invalidPath (const std::string &path, int location);

    Args args_;
  };

  /** \brief Experimental do not use: Allocator to customize member name and string value memory management done by Value.
   *
   * - makeMemberName() and releaseMemberName() are called to respectively duplicate and
   *   free an Json::objectValue member name.
   * - duplicateStringValue() and releaseStringValue() are called similarly to
   *   duplicate and free a Json::stringValue value.
   */
  class ValueAllocator
  {
  public:
    enum {
      unknown = (unsigned)-1
    };

    virtual
    ~ValueAllocator ();

    virtual char *makeMemberName (const char *memberName) = 0;
    virtual void releaseMemberName (char *memberName) = 0;
    virtual char *duplicateStringValue (const char *value, unsigned int length = unknown) = 0;
    virtual void releaseStringValue (char *value) = 0;
  };

  /** \brief base class for Value iterators.
   *
   */
  class ValueIteratorBase
  {
  public:
    typedef unsigned int size_t;
    typedef int difference_type;
    typedef ValueIteratorBase SelfType;

    ValueIteratorBase ();
    explicit ValueIteratorBase (const Value::ObjectValues::iterator &current);

    bool operator == (const SelfType &other) const
    {
      return isEqual (other);
    }

    bool operator != (const SelfType &other) const
    {
      return !isEqual (other);
    }

    difference_type operator - (const SelfType &other) const
    {
      return computeDistance (other);
    }

    /* / Return either the index or the member name of the referenced value as a Value. */
    Value key () const;

    /* / Return the index of the referenced Value. -1 if it is not an arrayValue. */
    UInt index () const;

    /* / Return the member name of the referenced Value. "" if it is not an objectValue. */
    const char *memberName () const;

  protected:
    Value &deref () const;

    void increment ();

    void decrement ();

    difference_type computeDistance (const SelfType &other) const;

    bool isEqual (const SelfType &other) const;

    void copy (const SelfType &other);

  private:
    Value::ObjectValues::iterator current_;
    /* Indicates that iterator is for a null value. */
    bool isNull_;
  };

  /** \brief const iterator for object and array value.
   *
   */
  class ValueConstIterator
    : public ValueIteratorBase
  {
    friend class Value;

  public:
    typedef unsigned int size_t;
    typedef int difference_type;
    typedef const Value &reference;
    typedef const Value *pointer;
    typedef ValueConstIterator SelfType;

    ValueConstIterator ();

  private:
    /*! \internal Use by Value to create an iterator.
     */
    explicit ValueConstIterator (const Value::ObjectValues::iterator &current);

  public:
    SelfType & operator = (const ValueIteratorBase &other);

    SelfType operator ++ (int)
    {
      SelfType temp (*this);

      ++*this;
      return temp;
    }

    SelfType operator -- (int)
    {
      SelfType temp (*this);

      --*this;
      return temp;
    }

    SelfType &operator -- ()
    {
      decrement ();
      return *this;
    }

    SelfType &operator ++ ()
    {
      increment ();
      return *this;
    }

    reference operator * () const
    {
      return deref ();
    }
  };


  /** \brief Iterator for object and array value.
   */
  class ValueIterator
    : public ValueIteratorBase
  {
    friend class Value;

  public:
    typedef unsigned int size_t;
    typedef int difference_type;
    typedef Value &reference;
    typedef Value *pointer;
    typedef ValueIterator SelfType;

    ValueIterator ();
    ValueIterator (const ValueConstIterator &other);
    ValueIterator (const ValueIterator &other);

  private:
    /*! \internal Use by Value to create an iterator.
     */
    explicit ValueIterator (const Value::ObjectValues::iterator &current);

  public:
    SelfType &operator = (const SelfType &other);

    SelfType operator ++ (int)
    {
      SelfType temp (*this);

      ++*this;
      return temp;
    }

    SelfType operator -- (int)
    {
      SelfType temp (*this);

      --*this;
      return temp;
    }

    SelfType &operator -- ()
    {
      decrement ();
      return *this;
    }

    SelfType &operator ++ ()
    {
      increment ();
      return *this;
    }

    reference operator * () const
    {
      return deref ();
    }
  };
} /* namespace Json */
Revision:	1.1
Committed:	Sun Oct 17 08:14:54 2010 UTC (16 years ago) by sf-pippijn
Content type:	text/plain
Branch:	MAIN
CVS Tags:	HEAD
Log Message:	initial import
#	User	Rev	Content
1	sf-pippijn	1.1	#pragma once
2
3			#include "adt/make.h"
4			#include "forwards.h"
5
6			#include <map>
7			#include <string>
8			#include <vector>
9
10			/** \brief JSON (JavaScript Object Notation).
11			*/
12			namespace Json
13			{
14			/** \brief Type of the value held by a Value object.
15			*/
16			enum ValueType
17			{
18			nullValue = 0, ///< 'null' value */
19			intValue, ///< signed integer value */
20			uintValue, ///< unsigned integer value */
21			realValue, ///< double value */
22			stringValue, ///< UTF-8 string value */
23			booleanValue, ///< bool value */
24			arrayValue, ///< array value (ordered list) */
25			objectValue ///< object value (collection of name/value pairs). */
26			};
27
28			enum CommentPlacement
29			{
30			commentBefore = 0, ///< a comment placed on the line before a value */
31			commentAfterOnSameLine, ///< a comment just after a value on the same line */
32			commentAfter, ///< a comment on the line after a value (only make sense for root value) */
33			numberOfCommentPlacement
34			};
35
36			/** \brief Lightweight wrapper to tag static string.
37			*
38			* Value constructor and objectValue member assignement takes advantage of the
39			* StaticString and avoid the cost of string duplication when storing the
40			* string or the member name.
41			*
42			* Example of usage:
43			* \code
44			* Json::Value aValue( StaticString("some text") );
45			* Json::Value object;
46			* static const StaticString code("code");
47			* object[code] = 1234;
48			* \endcode
49			*/
50			class JSON_API StaticString
51			{
52			public:
53			explicit StaticString (const char *czstring)
54			: str_ (czstring)
55			{
56			}
57
58			const char *c_str () const
59			{
60			return str_;
61			}
62
63			private:
64			const char *str_;
65			};
66
67			/** \brief Represents a <a href="http://www.json.org">JSON</a> value.
68			*
69			* This class is a discriminated union wrapper that can represents a:
70			* - signed integer [range: Value::minInt - Value::maxInt]
71			* - unsigned integer (range: 0 - Value::maxUInt)
72			* - double
73			* - UTF-8 string
74			* - boolean
75			* - 'null'
76			* - an ordered list of Value
77			* - collection of name/value pairs (javascript object)
78			*
79			* The type of the held value is represented by a #ValueType and
80			* can be obtained using type().
81			*
82			* values of an #objectValue or #arrayValue can be accessed using operator[]() methods.
83			* Non const methods will automatically create the a #nullValue element
84			* if it does not exist.
85			* The sequence of an #arrayValue will be automatically resize and initialized
86			* with #nullValue. resize() can be used to enlarge or truncate an #arrayValue.
87			*
88			* The get() methods can be used to obtanis default value in the case the required element
89			* does not exist.
90			*
91			* It is possible to iterate over the list of a #objectValue values using
92			* the getMemberNames() method.
93			*/
94			class JSON_API Value
95			{
96			friend class ValueIteratorBase;
97
98			public:
99			typedef std::vector<std::string> Members;
100			typedef ValueIterator iterator;
101			typedef ValueConstIterator const_iterator;
102			typedef Json::UInt UInt;
103			typedef Json::Int Int;
104			typedef UInt ArrayIndex;
105
106			static const Value null;
107			static const Int minInt;
108			static const Int maxInt;
109			static const UInt maxUInt;
110
111			private:
112			class CZString
113			{
114			public:
115			enum DuplicationPolicy
116			{
117			noDuplication = 0,
118			duplicate,
119			duplicateOnCopy
120			};
121			CZString (int index);
122			CZString (const char *cstr, DuplicationPolicy allocate);
123			CZString (const CZString &other);
124			~CZString ();
125			CZString &operator = (const CZString &other);
126			bool operator < (const CZString &other) const;
127			bool operator == (const CZString &other) const;
128			int index () const;
129			const char *c_str () const;
130			bool isStaticString () const;
131
132			private:
133			void swap (CZString &other);
134			const char *cstr_;
135			long index_;
136			};
137
138			public:
139			typedef std::map<CZString, Value> ObjectValues;
140
141			public:
142			/** \brief Create a default Value of the given type.
143			*
144			* This is a very useful constructor.
145			* To create an empty array, pass arrayValue.
146			* To create an empty object, pass objectValue.
147			* Another Value can then be set to this one by assignment.
148			* This is useful since clear() and resize() will not alter types.
149			*
150			* Examples:
151			* \code
152			* Json::Value null_value; // null
153			* Json::Value arr_value(Json::arrayValue); // []
154			* Json::Value obj_value(Json::objectValue); // {}
155			* \endcode
156			*/
157			Value (ValueType type = nullValue);
158			Value (Int value);
159			Value (UInt value);
160			Value (double value);
161			Value (const char *value);
162			Value (const char beginValue, const char endValue);
163			Value (make::array const &value);
164			Value (make::map const &value);
165			/** \brief Constructs a value from a static string.
166			*
167			* Like other value string constructor but do not duplicate the string for
168			* internal storage. The given string must remain alive after the call to this
169			* constructor.
170			* Example of usage:
171			* \code
172			* Json::Value aValue( StaticString("some text") );
173			* \endcode
174			*/
175			Value (const StaticString &value);
176			Value (const std::string &value);
177			Value (bool value);
178			Value (const Value &other);
179			~Value ();
180
181			Value &operator = (const Value &other);
182			/*
183			* / Swap values.
184			* / \note Currently, comments are intentionally not swapped, for
185			* / both logic and efficiency.
186			*/
187			void swap (Value &other);
188
189			ValueType type () const;
190
191			bool operator < (const Value &other) const;
192			bool operator <= (const Value &other) const;
193			bool operator >= (const Value &other) const;
194			bool operator > (const Value &other) const;
195
196			bool operator == (const Value &other) const;
197			bool operator != (const Value &other) const;
198
199			int compare (const Value &other);
200
201			const char *asCString () const;
202			std::string asString () const;
203			Int asInt () const;
204			UInt asUInt () const;
205			double asDouble () const;
206			bool asBool () const;
207
208			bool isNull () const;
209			bool isBool () const;
210			bool isInt () const;
211			bool isUInt () const;
212			bool isIntegral () const;
213			bool isDouble () const;
214			bool isNumeric () const;
215			bool isString () const;
216			bool isArray () const;
217			bool isObject () const;
218
219			bool isConvertibleTo (ValueType other) const;
220
221			/* / Number of values in array or object */
222			UInt size () const;
223
224			/*
225			* / \brief Return true if empty array, empty object, or null;
226			* / otherwise, false.
227			*/
228			bool empty () const;
229
230			/* / Return isNull() */
231			bool operator ! () const;
232
233			/*
234			* / Remove all object members and array elements.
235			* / \pre type() is arrayValue, objectValue, or nullValue
236			* / \post type() is unchanged
237			*/
238			void clear ();
239
240			/*
241			* / Resize the array to size elements.
242			* / New elements are initialized to null.
243			* / May only be called on nullValue or arrayValue.
244			* / \pre type() is arrayValue or nullValue
245			* / \post type() is arrayValue
246			*/
247			void resize (UInt size);
248
249			/*
250			* / Access an array element (zero based index ).
251			* / If the array contains less than index element, then null value are inserted
252			* / in the array so that its size is index+1.
253			* / (You may need to say 'value[0u]' to get your compiler to distinguish
254			* / this from the operator[] which takes a string.)
255			*/
256			Value &operator [] (UInt index);
257			Value &operator [] (int index) { return (*this)[UInt (index)]; }
258			/*
259			* / Access an array element (zero based index )
260			* / (You may need to say 'value[0u]' to get your compiler to distinguish
261			* / this from the operator[] which takes a string.)
262			*/
263			const Value &operator [] (UInt index) const;
264			/*
265			* / If the array contains at least index+1 elements, returns the element value,
266			* / otherwise returns defaultValue.
267			*/
268			Value get (UInt index, const Value &defaultValue) const;
269			/* / Return true if index < size(). */
270			bool isValidIndex (UInt index) const;
271			/*
272			* / \brief Append value to array at the end.
273			* /
274			* / Equivalent to jsonvalue[jsonvalue.size()] = value;
275			*/
276			Value &append (const Value &value);
277
278			/* / Access an object value by name, create a null member if it does not exist. */
279			Value &operator [] (const char *key);
280			/* / Access an object value by name, returns null if there is no member with that name. */
281			const Value &operator [] (const char *key) const;
282			/* / Access an object value by name, create a null member if it does not exist. */
283			Value &operator [] (const std::string &key);
284			/* / Access an object value by name, returns null if there is no member with that name. */
285			const Value &operator [] (const std::string &key) const;
286			/** \brief Access an object value by name, create a null member if it does not exist.
287			*
288			* If the object as no entry for that name, then the member name used to store
289			* the new entry is not duplicated.
290			* Example of use:
291			* \code
292			* Json::Value object;
293			* static const StaticString code("code");
294			* object[code] = 1234;
295			* \endcode
296			*/
297			Value &operator [] (const StaticString &key);
298			/* / Return the member named key if it exist, defaultValue otherwise. */
299			Value get (const char *key, const Value &defaultValue) const;
300			/* / Return the member named key if it exist, defaultValue otherwise. */
301			Value get (const std::string &key, const Value &defaultValue) const;
302			/*
303			* / \brief Remove and return the named member.
304			* /
305			* / Do nothing if it did not exist.
306			* / \return the removed Value, or null.
307			* / \pre type() is objectValue or nullValue
308			* / \post type() is unchanged
309			*/
310			Value removeMember (const char *key);
311			/* / Same as removeMember(const char) /
312			Value removeMember (const std::string &key);
313
314			/* / Return true if the object has a member named key. */
315			bool isMember (const char *key) const;
316			/* / Return true if the object has a member named key. */
317			bool isMember (const std::string &key) const;
318
319			/*
320			* / \brief Return a list of the member names.
321			* /
322			* / If null, return an empty list.
323			* / \pre type() is objectValue or nullValue
324			* / \post if type() was nullValue, it remains nullValue
325			*/
326			Members getMemberNames () const;
327
328			/* / Comments must be //... or / * ... * / */
329			void setComment (const char *comment, CommentPlacement placement);
330			/* / Comments must be //... or / * ... * / */
331			void setComment (const std::string &comment, CommentPlacement placement);
332			bool hasComment (CommentPlacement placement) const;
333			/* / Include delimiters and embedded newlines. */
334			std::string getComment (CommentPlacement placement) const;
335
336			std::string toStyledString () const;
337
338			const_iterator begin () const;
339			const_iterator end () const;
340
341			iterator begin ();
342			iterator end ();
343
344			private:
345			Value &resolveReference (const char *key, bool isStatic);
346
347			private:
348			struct CommentInfo
349			{
350			CommentInfo ();
351			~CommentInfo ();
352
353			void setComment (const char *text);
354
355			char *comment_;
356			};
357
358			/*
359			* struct MemberNamesTransform
360			* {
361			* typedef const char *result_type;
362			* const char *operator()( const CZString &name ) const
363			* {
364			* return name.c_str();
365			* }
366			* };
367			*/
368
369			union ValueHolder
370			{
371			Int int_;
372			UInt uint_;
373			double real_;
374			bool bool_;
375			char *string_;
376			ObjectValues *map_;
377			} value_;
378			CommentInfo *comments_;
379			ValueType type_;
380			bool allocated_;
381			};
382
383
384			/** \brief Experimental and untested: represents an element of the "path" to access a node.
385			*/
386			class PathArgument
387			{
388			public:
389			friend class Path;
390
391			PathArgument ();
392			PathArgument (UInt index);
393			PathArgument (const char *key);
394			PathArgument (const std::string &key);
395
396			private:
397			enum Kind
398			{
399			kindNone = 0,
400			kindIndex,
401			kindKey
402			};
403			std::string key_;
404			UInt index_;
405			Kind kind_;
406			};
407
408			/** \brief Experimental and untested: represents a "path" to access a node.
409			*
410			* Syntax:
411			* - "." => root node
412			* - ".[n]" => elements at index 'n' of root node (an array value)
413			* - ".name" => member named 'name' of root node (an object value)
414			* - ".name1.name2.name3"
415			* - ".[0][1][2].name1[3]"
416			* - ".%" => member name is provided as parameter
417			* - ".[%]" => index is provied as parameter
418			*/
419			class Path
420			{
421			public:
422			Path (const std::string &path, const PathArgument &a1 = PathArgument (), const PathArgument &a2 = PathArgument (), const PathArgument &a3 = PathArgument (), const PathArgument &a4 = PathArgument (), const PathArgument &a5 = PathArgument ());
423
424			const Value &resolve (const Value &root) const;
425			Value resolve (const Value &root, const Value &defaultValue) const;
426			/* / Creates the "path" to access the specified node and returns a reference on the node. */
427			Value &make (Value &root) const;
428
429			private:
430			typedef std::vector<const PathArgument *> InArgs;
431			typedef std::vector<PathArgument> Args;
432
433			void makePath (const std::string &path, const InArgs &in);
434			void addPathInArg (const std::string &path, const InArgs &in, InArgs::const_iterator &itInArg, PathArgument::Kind kind);
435			void invalidPath (const std::string &path, int location);
436
437			Args args_;
438			};
439
440			/** \brief Experimental do not use: Allocator to customize member name and string value memory management done by Value.
441			*
442			* - makeMemberName() and releaseMemberName() are called to respectively duplicate and
443			* free an Json::objectValue member name.
444			* - duplicateStringValue() and releaseStringValue() are called similarly to
445			* duplicate and free a Json::stringValue value.
446			*/
447			class ValueAllocator
448			{
449			public:
450			enum {
451			unknown = (unsigned)-1
452			};
453
454			virtual
455			~ValueAllocator ();
456
457			virtual char makeMemberName (const char memberName) = 0;
458			virtual void releaseMemberName (char *memberName) = 0;
459			virtual char duplicateStringValue (const char value, unsigned int length = unknown) = 0;
460			virtual void releaseStringValue (char *value) = 0;
461			};
462
463			/** \brief base class for Value iterators.
464			*
465			*/
466			class ValueIteratorBase
467			{
468			public:
469			typedef unsigned int size_t;
470			typedef int difference_type;
471			typedef ValueIteratorBase SelfType;
472
473			ValueIteratorBase ();
474			explicit ValueIteratorBase (const Value::ObjectValues::iterator &current);
475
476			bool operator == (const SelfType &other) const
477			{
478			return isEqual (other);
479			}
480
481			bool operator != (const SelfType &other) const
482			{
483			return !isEqual (other);
484			}
485
486			difference_type operator - (const SelfType &other) const
487			{
488			return computeDistance (other);
489			}
490
491			/* / Return either the index or the member name of the referenced value as a Value. */
492			Value key () const;
493
494			/* / Return the index of the referenced Value. -1 if it is not an arrayValue. */
495			UInt index () const;
496
497			/* / Return the member name of the referenced Value. "" if it is not an objectValue. */
498			const char *memberName () const;
499
500			protected:
501			Value &deref () const;
502
503			void increment ();
504
505			void decrement ();
506
507			difference_type computeDistance (const SelfType &other) const;
508
509			bool isEqual (const SelfType &other) const;
510
511			void copy (const SelfType &other);
512
513			private:
514			Value::ObjectValues::iterator current_;
515			/* Indicates that iterator is for a null value. */
516			bool isNull_;
517			};
518
519			/** \brief const iterator for object and array value.
520			*
521			*/
522			class ValueConstIterator
523			: public ValueIteratorBase
524			{
525			friend class Value;
526
527			public:
528			typedef unsigned int size_t;
529			typedef int difference_type;
530			typedef const Value &reference;
531			typedef const Value *pointer;
532			typedef ValueConstIterator SelfType;
533
534			ValueConstIterator ();
535
536			private:
537			/*! \internal Use by Value to create an iterator.
538			*/
539			explicit ValueConstIterator (const Value::ObjectValues::iterator &current);
540
541			public:
542			SelfType & operator = (const ValueIteratorBase &other);
543
544			SelfType operator ++ (int)
545			{
546			SelfType temp (*this);
547
548			++*this;
549			return temp;
550			}
551
552			SelfType operator -- (int)
553			{
554			SelfType temp (*this);
555
556			--*this;
557			return temp;
558			}
559
560			SelfType &operator -- ()
561			{
562			decrement ();
563			return *this;
564			}
565
566			SelfType &operator ++ ()
567			{
568			increment ();
569			return *this;
570			}
571
572			reference operator * () const
573			{
574			return deref ();
575			}
576			};
577
578
579			/** \brief Iterator for object and array value.
580			*/
581			class ValueIterator
582			: public ValueIteratorBase
583			{
584			friend class Value;
585
586			public:
587			typedef unsigned int size_t;
588			typedef int difference_type;
589			typedef Value &reference;
590			typedef Value *pointer;
591			typedef ValueIterator SelfType;
592
593			ValueIterator ();
594			ValueIterator (const ValueConstIterator &other);
595			ValueIterator (const ValueIterator &other);
596
597			private:
598			/*! \internal Use by Value to create an iterator.
599			*/
600			explicit ValueIterator (const Value::ObjectValues::iterator &current);
601
602			public:
603			SelfType &operator = (const SelfType &other);
604
605			SelfType operator ++ (int)
606			{
607			SelfType temp (*this);
608
609			++*this;
610			return temp;
611			}
612
613			SelfType operator -- (int)
614			{
615			SelfType temp (*this);
616
617			--*this;
618			return temp;
619			}
620
621			SelfType &operator -- ()
622			{
623			decrement ();
624			return *this;
625			}
626
627			SelfType &operator ++ ()
628			{
629			increment ();
630			return *this;
631			}
632
633			reference operator * () const
634			{
635			return deref ();
636			}
637			};
638			} /* namespace Json */