Couple some string and number information from the RFC conformance
chapter in the API reference, and refer to the RFC conformance chapter
from API reference for more information.
Also, state more clearly that a JSON text must have an array or object
as the top-level value, and better document the string comparison
performed by json_equal().
Provide an example usage pattern for reference stealing functions.
This way the user (hopely) sees more clearly how the reference
stealing functions are meant to be used.
When encoding an array or object ends in an error, the visited flag
wasn't zeroed, causing subsequent encoding attempts to fail. This
patch fixes the problem by always zeroing the visited flag.
Encoding an empty array or object worked, but encoding it again
(possibly after adding some items) failed, because the visited flag
(used for detecting circular references) wasn't zeroed.
Initialize their reference counts to (unsigned int)-1 to disable
reference counting on them. It already was meant to work like this,
but the reference counts were just initialized to 1 instead of -1.
Thanks to Andrew Thompson for reporting this issue.
With this encoding flag, the object key-value pairs in output are in
the same order in which they were first inserted into the object.
To make this possible, a key of an object is now a serial number plus
a string. An object keeps an increasing counter which is used to
assign serial number to the keys. Hashing, comparison and public API
functions were changed to act only on the string part, i.e. the serial
number is ignored everywhere else but in the encoder, where it's used
to order object keys if JSON_PRESERVE_ORDER flag is used.
When the property already exists in the object, we can store an
iterator pointing to that property, instead of duplicating the key.
When the property (key) is not present in the object, we still have to
duplicate the key.
If a user happens to store an ElementProxy or a PropertyProxy
instance, we need to take a reference to the JSON value they point to.
With PropertyProxy, the key needs to be copied as well.
