Merge remote branch 'elanthis/c++-docs' into c++-api

doc/apiref.rst

@@ -800,3 +800,148 @@ copied in a recursive fashion.
    Returns a deep copy of *value*, or *NULL* on error.
 
    .. versionadded:: 1.2
+
+
+C++ Interface
+=============
+
+A simple C++ wrapper around the Jansson interface exists in the header
+:file:`jansson.hpp`.
+
+The C++ interface consists of the :ctype:`Value` class in the ``json``
+namespace.
+
+.. ctype:: json::Value
+
+   Wrapper around the :ctype:`json_t` type of the C API, with automatic
+   reference counting.
+
+.. ctype:: proxy
+
+   An unspecified type used for proxying array element and object
+   property accesses.  This type should never be used by the client.
+
+   Warning: using C++0x's ``auto`` keyword may result in creating
+   objects of the proxy type.  It is recommended that uses always
+   explicitly declare variables with the type :ctype:`json::Value`.
+
+.. cfunction:: json::Value::Value()
+
+   Constructs a new :ctype:`json::Value` of undefined type.
+
+.. cfunction:: bool json::Value::is_undefined()
+
+   Returns ``true`` if the type of the :ctype:`Value` is undefined.
+
+.. cfunction:: bool json::Value::is_null()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_NULL`.
+
+.. cfunction:: bool json::Value::is_string()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_STRING`.
+
+.. cfunction:: bool json::Value::is_object()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_OBJECT`.
+
+.. cfunction:: bool json::Value::is_array()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_ARRAY`.
+
+.. cfunction:: bool json::Value::is_real()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_REAL`.
+
+.. cfunction:: bool json::Value::is_number()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_REAL`.
+
+.. cfunction:: bool json::Value::is_integer()
+
+   Returns ``true`` if the type of the :ctype:`Value` is :const:`JSON_INTEGER`.
+ 
+.. cfunction:: proxy json::Value::operator[](const char* key)
+
+   Synonym for `json::Value::get(const char*)`.
+
+.. cfunction:: const char* json::Value::as_cstring()
+
+   Fetch the value as a C string, if the stored value is of type
+   :const:`JSON_STRING`.  Otherwise, :const:`NULL` is returned.
+
+.. cfunction:: std::string json::Value::as_string()
+
+   Fetch the value as a C++ string, if the stored value is of type
+   :const:`JSON_STRING`.  An empty string is returned if the value
+   is not a string type.
+
+.. cfunction:: int json::Value::as_integer()
+
+   Fetch the value as an integer, if the stored value is of type
+   :const:`JSON_INTEGER`.
+
+.. cfunction:: double json::Value::as_real()
+
+   Fetch the value as a double, if the stored value is of type
+   :const:`JSON_REAL`.
+
+.. cfunction:: double json::Value::as_number()
+
+   Fetch the value as a double, if the stored value is of type
+   :const:`JSON_REAL`.
+
+.. cfunction:: bool json::Value::as_boolean()
+
+   Fetch the value as a bool, if the stored value is of type
+   :const:`JSON_TRUE` or :const:`JSON_FALSE`.
+
+.. cfunction:: void json::Value::clear()
+
+   Delete all object properties or array elements within the value.
+
+.. cfunction:: proxy json::Value::at(int index)
+
+   Returns a proxy object referencing a specific array element.
+
+.. cfunction:: proxy json::Value::get(const char* key)
+
+   Returns a proxy object referencing a specific object property.
+
+.. cfunction:: proxy json::Value::get(const std::string& key)
+
+   Returns a proxy object referencing a specific object property.
+
+.. cfunction:: Value json::Value::set_at(unsigned int index, json::Value value)
+
+   Assigns the given value to the specified index within the value if the
+   value is an array.  The index must be 0 <= index <= size.  If the index
+   is equal to the size, the value is appended to the array and the size
+   is increased by one.
+
+.. cfunction:: Value json::Value::set_key(const char* key, json::Value value)
+
+   Assigns the given value to the specified key within the value if the
+   value is an object.
+
+.. cfunction:: Value json::Value::set_key(const std::string& key, json::Value value)
+
+   Assigns the given value to the specified key within the value if the
+   value is an object.
+
+.. cfunction:: Value json::Value::del_at(unsigned int index)
+
+   Deletes the value within the array at the given index.  Elements are
+   shifted down after deletion.  The index must be 0 <= index < size.
+
+.. cfunction:: Value json::Value::del_key(const char* key)
+
+   Deletes the property with the given key.
+
+.. cfunction:: Value json::Value::del_key(const std::string& key)
+
+   Deletes the property with the given key.
+ 
+.. cfunction:: proxy json::Value::operator[](int index)
+
+   Synonym for `json::Value::at(int index)`.