Mercurial > hg > ucx / changeset

--- a/docs/Writerside/topics/json.h.md	Sat Mar 22 15:29:55 2025 +0100
+++ b/docs/Writerside/topics/json.h.md	Sun Mar 23 11:28:20 2025 +0100
@@ -28,51 +28,18 @@
 
 ### List of Status Codes
 
-<!--
-    /**
-     * Everything is fine.
-     */
-    CX_JSON_NO_ERROR,
-    /**
-     * The input buffer does not contain more data.
-     */
-    CX_JSON_NO_DATA,
-    /**
-     * The input ends unexpectedly.
-     *
-     * Refill the buffer with cxJsonFill() to complete the json data.
-     */
-    CX_JSON_INCOMPLETE_DATA,
-    /**
-     * Not used as a status and never returned by any function.
-     *
-     * You can use this enumerator to check for all "good" status results
-     * by checking if the status is less than @c CX_JSON_OK.
-     *
-     * A "good" status means, that you can refill data and continue parsing.
-     */
-    CX_JSON_OK,
-    /**
-     * The input buffer has never been filled.
-     */
-    CX_JSON_NULL_DATA,
-    /**
-     * Allocating memory for the internal buffer failed.
-     */
-    CX_JSON_BUFFER_ALLOC_FAILED,
-    /**
-     * Allocating memory for a json value failed.
-     */
-    CX_JSON_VALUE_ALLOC_FAILED,
-    /**
-     * A number value is incorrectly formatted.
-     */
-    CX_JSON_FORMAT_ERROR_NUMBER,
-    /**
-     * The tokenizer found something unexpected.
-     */
-    CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN
--->
+Below is a full list of status codes for `cxJsonNext()`.
+
+| Status Code                           | Meaning                                                                                           |
+|---------------------------------------|---------------------------------------------------------------------------------------------------|
+| CX_JSON_NO_ERROR                      | A value was successfully parsed.                                                                  |                                                                                                                                                                                       |
+| CX_JSON_NO_DATA                       | The input buffer does not contain more data.                                                      |
+| CX_JSON_INCOMPLETE_DATA               | The input ends unexpectedly. Use `cxJsonFill()` to add more data before retrying.                 |
+| CX_JSON_NULL_DATA                     | The input buffer was never initialized. Probably you forgot to call `cxJsonFill()` at least once. |
+| CX_JSON_BUFFER_ALLOC_FAILED           | More internal buffer was needed, but could not be allocated.                                      |
+| CX_JSON_VALUE_ALLOC_FAILED            | Allocating memory for a json value failed.                                                        |
+| CX_JSON_FORMAT_ERROR_NUMBER           | A number value is incorrectly formatted.                                                          |
+| CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN | The tokenizer found something unexpected, i.e. the JSON string contains a syntax error.           |
 
 ## Access Values
 
@@ -122,9 +89,37 @@
 CxIterator cxJsonObjIter(const CxJsonValue *value);
 ```
 
-<warning>
-TODO: document
-</warning>
+The `cxJsonIsXYZ()` family functions check the type of the specified JSON value.
+
+The JSON specification only defines numbers, therefore `cxJsonIsNumber()` returns true for both floating point and integer numbers.
+On the other hand, `cxJsonIsInteger()` only returns true for integral numbers.
+
+The function `cxJsonIsBool()` returns true if `cxJsonIsLiteral()` returns true, but `cxJsonIsNull()` does not.
+
+> Since a literal can be `true`, `false`, or `null`, note carefully that `!cxJsonIsTrue(v)`
+> is in general _not_ equivalent to `cxJsonIsFalse(v)`.
+> 
+> Additionally, UCX does implement the Javascript concept of a "falsy" value, meaning that
+> `cxJsonIsFalse()` _only_ returns true, if the value is a literal `false`.
+>{style="note"}
+
+The `cxJsonAsXYZ()` family of functions return the value with its corresponding C type.
+
+The functions `cxJsonAsInteger()` and `cxJsonAsDouble()` can be used for any number value.
+For example, if `cxJsonAsInteger()` is used on a non-integral number, a double-to-int conversion is performed.
+
+The function `cxJsonArraySize()` returns the number of items in an array value,
+which can be accessed via index with `cxJsonArrGet()` or via an iterator created with `cxJsonArrIter()`.
+
+The function `cxJsonObjGet()` returns the member in a JSON object associated with the specified `name`. 
+
+> Both `cxJsonArrGet()` and `cxJsonObjGet()` are safe regarding access to non-existing values.
+> 
+> When `cxJsonArrGet()` is used with an out-of-bounds index, or `cxJsonObjGet()` is used with a non-existent name,
+> they return a JSON value, that returns `false` for any `cxJsonIsXYZ()` function.
+
+> If you don't have full control over the JSON data, you should always check the datatype of a value first, before accessing it.
+>{style="note"}
 
 ## Deallocate Memory