Removes the element in *array* at position *index*, shifting the
elements after *index* one position towards the start of the array.
- Returns 0 on success and -1 on error.
+ Returns 0 on success and -1 on error. The reference count of the
+ removed value is decremented.
.. function:: int json_array_clear(json_t *array)
Removes all elements from *array*. Returns 0 on sucess and -1 on
- error.
+ error. The reference count of all removed values are decremented.
.. function:: int json_array_extend(json_t *array, json_t *other_array)
.. function:: int json_object_del(json_t *object, const char *key)
Delete *key* from *object* if it exists. Returns 0 on success, or
- -1 if *key* was not found.
-
+ -1 if *key* was not found. The reference count of the removed value
+ is decremented.
.. function:: int json_object_clear(json_t *object)
Remove all elements from *object*. Returns 0 on success and -1 if
- *object* is not a JSON object.
+ *object* is not a JSON object. The reference count of all removed
+ values are decremented.
.. function:: int json_object_update(json_t *object, json_t *other)
The following functions implement an iteration protocol for objects,
allowing to iterate through all key-value pairs in an object. The
items are not returned in any particular order, as this would require
-sorting due to the internal object representation.
+sorting due to the internal hashtable implementation.
.. function:: void *json_object_iter(json_t *object)
to the JSON specification. It explains many design decisions that
affect especially the behavior of the decoder.
+Each function takes a *flags* parameter that can be used to control
+the behavior of the decoder. Its default value is 0. The following
+macros can be ORed together to obtain *flags*.
+
+``JSON_REJECT_DUPLICATES``
+ Issue a decoding error if any JSON object in the input text
+ contains duplicate keys. Without this flag, the value of the last
+ occurence of each key ends up in the result. Key equivalence is
+ checked byte-by-byte, without special Unicode comparison
+ algorithms.
+
+ .. versionadded:: 2.1
+
+``JSON_DISABLE_EOF_CHECK``
+ By default, the decoder expects that its whole input constitutes a
+ valid JSON text, and issues an error if there's extra data after
+ the otherwise valid JSON input. With this flag enabled, the decoder
+ stops after decoding a valid JSON array or object, and thus allows
+ extra data after the JSON text.
+
+ .. versionadded:: 2.1
+
+The following functions perform the actual JSON decoding.
+
.. function:: json_t *json_loads(const char *input, size_t flags, json_error_t *error)
.. refcounting:: new
Decodes the JSON string *input* and returns the array or object it
contains, or *NULL* on error, in which case *error* is filled with
- information about the error. *flags* is currently unused, and
- should be set to 0.
+ information about the error. *flags* is described above.
.. function:: json_t *json_loadb(const char *buffer, size_t buflen, size_t flags, json_error_t *error)
returns the array or object it contains, or *NULL* on error, in
which case *error* is filled with information about the error. This
is similar to :func:`json_loads()` except that the string doesn't
- need to be null-terminated. *flags* is currently unused, and should
- be set to 0.
+ need to be null-terminated. *flags* is described above.
.. versionadded:: 2.1
Decodes the JSON text in stream *input* and returns the array or
object it contains, or *NULL* on error, in which case *error* is
- filled with information about the error. *flags* is currently
- unused, and should be set to 0.
+ filled with information about the error. *flags* is described
+ above.
.. function:: json_t *json_load_file(const char *path, size_t flags, json_error_t *error)
Decodes the JSON text in file *path* and returns the array or
object it contains, or *NULL* on error, in which case *error* is
- filled with information about the error. *flags* is currently
- unused, and should be set to 0.
+ filled with information about the error. *flags* is described
+ above.
.. _apiref-pack:
Building Values
===============
-This sectinon describes functions that help to create, or *pack*,
+This section describes functions that help to create, or *pack*,
complex JSON values, especially nested objects and arrays. Value
building is based on a *format string* that is used to tell the
functions about the expected arguments.
For example, the format string ``"i"`` specifies a single integer
value, while the format string ``"[ssb]"`` or the equivalent ``"[s, s,
-b]"`` specifies an array value with two integers and a boolean as its
+b]"`` specifies an array value with two strings and a boolean as its
items::
/* Create the JSON integer 42 */
``o`` (any value) [json_t \*]
Output any given JSON value as-is. If the value is added to an
array or object, the reference to the value passed to ``o`` is
- stealed by the container.
+ stolen by the container.
``O`` (any value) [json_t \*]
Like ``o``, but the argument's reference count is incremented.
json_pack("{}");
/* Build the JSON object {"foo": 42, "bar": 7} */
- json_pack("{sisb}", "foo", 42, "bar", 7);
+ json_pack("{sisi}", "foo", 42, "bar", 7);
/* Like above, ':', ',' and whitespace are ignored */
- json_pack("{s:i, s:b}", "foo", 42, "bar", 7);
+ json_pack("{s:i, s:i}", "foo", 42, "bar", 7);
/* Build the JSON array [[1, 2], {"cool": true}] */
json_pack("[[i,i],{s:b]]", 1, 2, "cool", 1);
projects / jansson.git / blobdiff