idav: comparison ucx/cx/json.h

-:81c4f73236a4
+:c3f2f16fa4b8
 /**
 * A string token.
 */
 CX_JSON_TOKEN_STRING,
 /**
-* A number token that can be represented as integer.
+* A number token that can be represented as an integer.
 */
 CX_JSON_TOKEN_INTEGER,
 /**
-* A number token that cannot be represented as integer.
+* A number token that cannot be represented as an integer.
 */
 CX_JSON_TOKEN_NUMBER,
 /**
 * A literal token.
 */
 /**
 * Type alias for a JSON string.
 */
 typedef struct cx_mutstr_s CxJsonString;
 /**
-* Type alias for a number that can be represented as 64-bit signed integer.
+* Type alias for a number that can be represented as a 64-bit signed integer.
 */
 typedef int64_t CxJsonInteger;
 /**
-* Type alias for number that is not an integer.
+* Type alias for a number that is not an integer.
 */
 typedef double CxJsonNumber;
 /**
 * Type alias for a JSON literal.
 */
 /**
 * The value data.
 */
 union {
 /**
-* The array data if type is #CX_JSON_ARRAY.
+* The array data if the type is #CX_JSON_ARRAY.
 */
 CxJsonArray array;
 /**
-* The object data if type is #CX_JSON_OBJECT.
+* The object data if the type is #CX_JSON_OBJECT.
 */
 CxJsonObject object;
 /**
-* The string data if type is #CX_JSON_STRING.
+* The string data if the type is #CX_JSON_STRING.
 */
 CxJsonString string;
 /**
-* The integer if type is #CX_JSON_INTEGER.
+* The integer if the type is #CX_JSON_INTEGER.
 */
 CxJsonInteger integer;
 /**
-* The number if type is #CX_JSON_NUMBER.
+* The number if the type is #CX_JSON_NUMBER.
 */
 CxJsonNumber number;
 /**
-* The literal type if type is #CX_JSON_LITERAL.
+* The literal type if the type is #CX_JSON_LITERAL.
 */
 CxJsonLiteral literal;
 } value;
 };
 */
 CxJsonValue* vbuf_internal[8];
 };
 /**
-* Status codes for the json interface.
+* Status codes for the JSON interface.
 */
 enum cx_json_status {
 /**
 * Everything is fine.
 */
 */
 CX_JSON_NO_DATA,
 /**
 * The input ends unexpectedly.
 *
-* Refill the buffer with cxJsonFill() to complete the json data.
+* 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.
+* A "good" status means that you can refill data and continue parsing.
 */
 CX_JSON_OK,
 /**
 * The input buffer has never been filled.
 */
 /**
 * Allocating memory for the internal buffer failed.
 */
 CX_JSON_BUFFER_ALLOC_FAILED,
 /**
-* Allocating memory for a json value failed.
+* Allocating memory for a JSON value failed.
 */
 CX_JSON_VALUE_ALLOC_FAILED,
 /**
 * A number value is incorrectly formatted.
 */
 */
 CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN
 };
 /**
-* Typedef for the json status enum.
+* Typedef for the JSON status enum.
 */
 typedef enum cx_json_status CxJsonStatus;
 /**
 * The JSON writer settings.
 */
 bool sort_members;
 /**
 * The maximum number of fractional digits in a number value.
 * The default value is 6 and values larger than 15 are reduced to 15.
-* Note, that the actual number of digits may be lower, depending on the concrete number.
+* Note that the actual number of digits may be lower, depending on the concrete number.
 */
 uint8_t frac_max_digits;
 /**
 * Set true to use spaces instead of tab characters.
 * Indentation is only used in pretty output.
 */
 bool escape_slash;
 };
 /**
-* Typedef for the json writer.
+* Typedef for the JSON writer.
 */
 typedef struct cx_json_writer_s CxJsonWriter;
 /**
 * Creates a default writer configuration for compact output.
 * This function blocks until either all data is written, or an error occurs.
 * The write operation is not atomic in the sense that it might happen
 * that the data is only partially written when an error occurs with no
 * way to indicate how much data was written.
 * To avoid this problem, you can use a CxBuffer as @p target which is
-* unlikely to fail a write operation and either use the buffer's flush
+* unlikely to fail a write operation. You can, for example, use the buffer's flush
-* feature to relay the data or use the data in the buffer manually to
+* feature to relay the data.
-* write it to the actual target.
 *
 * @param target the buffer or stream where to write to
 * @param value the value that shall be written
 * @param wfunc the write function to use
 * @param settings formatting settings (or @c NULL to use a compact default)
 cx_write_func wfunc,
 const CxJsonWriter* settings
 );
 /**
-* Initializes the json interface.
+* Initializes the JSON interface.
 *
-* @param json the json interface
+* @param json the JSON interface
 * @param allocator the allocator that shall be used for the produced values
 * @see cxJsonDestroy()
 */
 cx_attr_nonnull_arg(1)
 cx_attr_export
 void cxJsonInit(CxJson *json, const CxAllocator *allocator);
 /**
-* Destroys the json interface.
+* Destroys the JSON interface.
 *
-* @param json the json interface
+* @param json the JSON interface
 * @see cxJsonInit()
 */
 cx_attr_nonnull
 cx_attr_export
 void cxJsonDestroy(CxJson *json);
 /**
-* Destroys and re-initializes the json interface.
+* Destroys and re-initializes the JSON interface.
 *
-* You might want to use this, to reset the parser after
+* You might want to use this to reset the parser after
 * encountering a syntax error.
 *
-* @param json the json interface
+* @param json the JSON interface
 */
 cx_attr_nonnull
 static inline void cxJsonReset(CxJson *json) {
 const CxAllocator *allocator = json->allocator;
 cxJsonDestroy(json);
 * pointer to the data in that case. When you invoke the fill
 * function more than once before calling cxJsonNext(),
 * the additional data is appended - inevitably leading to
 * an allocation of a new buffer and copying the previous contents.
 *
-* @param json the json interface
+* @param json the JSON interface
 * @param buf the source buffer
 * @param len the length of the source buffer
 * @retval zero success
 * @retval non-zero internal allocation error
 * @see cxJsonFill()
 cx_attr_nonnull
 cx_attr_access_r(2, 3)
 cx_attr_export
 int cxJsonFilln(CxJson *json, const char *buf, size_t len);
-#ifdef __cplusplus
-} // extern "C"
+/**
+* Internal function, do not use.
-cx_attr_nonnull
+*
-static inline int cxJsonFill(
+* @param json the JSON interface
-CxJson *json,
+* @param str the string
-cxstring str
+* @retval zero success
-) {
+* @retval non-zero internal allocation error
+*/
+cx_attr_nonnull
+static inline int cx_json_fill(CxJson *json, cxstring str) {
 return cxJsonFilln(json, str.ptr, str.length);
 }
-cx_attr_nonnull
-static inline int cxJsonFill(
-CxJson *json,
-cxmutstr str
-) {
-return cxJsonFilln(json, str.ptr, str.length);
-}
-cx_attr_nonnull
-cx_attr_cstr_arg(2)
-static inline int cxJsonFill(
-CxJson *json,
-const char *str
-) {
-return cxJsonFilln(json, str, strlen(str));
-}
-extern "C" {
-#else // __cplusplus
 /**
 * Fills the input buffer.
 *
 * The JSON interface tries to avoid copying the input data.
 * When you use this function and cxJsonNext() interleaving,
 * pointer to the data in that case. When you invoke the fill
 * function more than once before calling cxJsonNext(),
 * the additional data is appended - inevitably leading to
 * an allocation of a new buffer and copying the previous contents.
 *
-* @param json the json interface
+* @param json the JSON interface
 * @param str the source string
 * @retval zero success
 * @retval non-zero internal allocation error
 * @see cxJsonFilln()
 */
-#define cxJsonFill(json, str) _Generic((str), \
+#define cxJsonFill(json, str) cx_json_fill(json, cx_strcast(str))
-cxstring: cx_json_fill_cxstr,             \
-cxmutstr: cx_json_fill_mutstr,            \
-char*: cx_json_fill_str,                  \
-const char*: cx_json_fill_str)            \
-(json, str)
-/**
-* @copydoc cxJsonFill()
-*/
-cx_attr_nonnull
-static inline int cx_json_fill_cxstr(
-CxJson *json,
-cxstring str
-) {
-return cxJsonFilln(json, str.ptr, str.length);
-}
-/**
-* @copydoc cxJsonFill()
-*/
-cx_attr_nonnull
-static inline int cx_json_fill_mutstr(
-CxJson *json,
-cxmutstr str
-) {
-return cxJsonFilln(json, str.ptr, str.length);
-}
-/**
-* @copydoc cxJsonFill()
-*/
-cx_attr_nonnull
-cx_attr_cstr_arg(2)
-static inline int cx_json_fill_str(
-CxJson *json,
-const char *str
-) {
-return cxJsonFilln(json, str, strlen(str));
-}
-#endif
 /**
 * Creates a new (empty) JSON object.
 *
 * @param allocator the allocator to use
 /**
 * Recursively deallocates the memory of a JSON value.
 *
 * @remark The type of each deallocated value will be changed
-* to #CX_JSON_NOTHING and values of such type will be skipped
+* to #CX_JSON_NOTHING, and values of such a type will be skipped
-* by the de-allocation. That means, this function protects
+* by the deallocation. That means this function protects
 * you from double-frees when you are accidentally freeing
 * a nested value and then the parent value (or vice versa).
 *
 * @param value the value
 */
 *
 * When this function returns #CX_JSON_INCOMPLETE_DATA, you can
 * add the missing data with another invocation of cxJsonFill()
 * and then repeat the call to cxJsonNext().
 *
-* @param json the json interface
+* @param json the JSON interface
 * @param value a pointer where the next value shall be stored
 * @retval CX_JSON_NO_ERROR successfully retrieve the @p value
 * @retval CX_JSON_NO_DATA there is no (more) data in the buffer to read from
 * @retval CX_JSON_INCOMPLETE_DATA an incomplete value was read
 * and more data needs to be filled
 }
 /**
 * Checks if the specified value is a JSON number.
 *
-* This function will return true for both floating point and
+* This function will return true for both floating-point and
 * integer numbers.
 *
 * @param value a pointer to the value
 * @retval true the value is a JSON number
 * @retval false otherwise
 }
 /**
 * Checks if the specified value is @c true.
 *
-* @remark Be advised, that this is not the same as
+* @remark Be advised that this is different from
 * testing @c !cxJsonIsFalse(v).
 *
 * @param value a pointer to the value
 * @retval true the value is @c true
 * @retval false otherwise
 }
 /**
 * Checks if the specified value is @c false.
 *
-* @remark Be advised, that this is not the same as
+* @remark Be advised that this is different from
 * testing @c !cxJsonIsTrue(v).
 *
 * @param value a pointer to the value
 * @retval true the value is @c false
 * @retval false otherwise
 static inline cxmutstr cxJsonAsCxMutStr(const CxJsonValue *value) {
 return value->value.string;
 }
 /**
-* Obtains a double-precision floating point value from the given JSON value.
+* Obtains a double-precision floating-point value from the given JSON value.
 *
 * If the @p value is not a JSON number, the behavior is undefined.
 *
 * @param value the JSON value
 * @return the value represented as double
 cx_attr_returns_nonnull
 cx_attr_export
 CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index);
 /**
+* Removes an element from a JSON array.
+*
+* If the @p value is not a JSON array, the behavior is undefined.
+*
+* This function, in contrast to cxJsonArrayGet(), returns @c NULL
+* when the index is out of bounds.
+*
+* @param value the JSON value
+* @param index the index in the array
+* @return the removed value from the specified index or @c NULL when the index was out of bounds
+* @see cxJsonIsArray()
+*/
+cx_attr_nonnull
+cx_attr_export
+CxJsonValue *cxJsonArrRemove(CxJsonValue *value, size_t index);
+/**
 * Returns an iterator over the JSON array elements.
 *
 * The iterator yields values of type @c CxJsonValue* .
 *
 * If the @p value is not a JSON array, the behavior is undefined.
 cx_attr_nodiscard
 cx_attr_export
 CxIterator cxJsonObjIter(const CxJsonValue *value);
 /**
-* @copydoc cxJsonObjGet()
+* Internal function, do not use.
+* @param value the JSON object
+* @param name the key to look up
+* @return the value corresponding to the key
 */
 cx_attr_nonnull
 cx_attr_returns_nonnull
 cx_attr_export
-CxJsonValue *cx_json_obj_get_cxstr(const CxJsonValue *value, cxstring name);
+CxJsonValue *cx_json_obj_get(const CxJsonValue *value, cxstring name);
-#ifdef __cplusplus
-} // extern "C"
-static inline CxJsonValue *cxJsonObjGet(const CxJsonValue *value, cxstring name) {
-return cx_json_obj_get_cxstr(value, name);
-}
-static inline CxJsonValue *cxJsonObjGet(const CxJsonValue *value, cxmutstr name) {
-return cx_json_obj_get_cxstr(value, cx_strcast(name));
-}
-static inline CxJsonValue *cxJsonObjGet(const CxJsonValue *value, const char *name) {
-return cx_json_obj_get_cxstr(value, cx_str(name));
-}
-extern "C" {
-#else
 /**
 * Returns a value corresponding to a key in a JSON object.
 *
 * If the @p value is not a JSON object, the behavior is undefined.
 *
 * @param value the JSON object
 * @param name the key to look up
 * @return the value corresponding to the key
 * @see cxJsonIsObject()
 */
-#define cxJsonObjGet(value, name) _Generic((name), \
+#define cxJsonObjGet(value, name) cx_json_obj_get(value, cx_strcast(name))
-cxstring: cx_json_obj_get_cxstr,           \
-cxmutstr: cx_json_obj_get_mutstr,          \
+/**
-char*: cx_json_obj_get_str,                \
+* Internal function, do not use.
-const char*: cx_json_obj_get_str)          \
+* @param value the JSON object
-(value, name)
+* @param name the key to look up
+* @return the value corresponding to the key or @c NULL when the key is not part of the object
-/**
+*/
-* @copydoc cxJsonObjGet()
+cx_attr_nonnull
-*/
+cx_attr_export
-cx_attr_nonnull
+CxJsonValue *cx_json_obj_remove(CxJsonValue *value, cxstring name);
-cx_attr_returns_nonnull
-static inline CxJsonValue *cx_json_obj_get_mutstr(const CxJsonValue *value, cxmutstr name) {
+/**
-return cx_json_obj_get_cxstr(value, cx_strcast(name));
+* Removes and returns a value corresponding to a key in a JSON object.
-}
+*
+* If the @p value is not a JSON object, the behavior is undefined.
-/**
+*
-* @copydoc cxJsonObjGet()
+* This function, in contrast to cxJsonObjGet() returns @c NULL when the
-*/
+* object does not contain @p name.
-cx_attr_nonnull
+*
-cx_attr_returns_nonnull
+* @param value the JSON object
-cx_attr_cstr_arg(2)
+* @param name the key to look up
-static inline CxJsonValue *cx_json_obj_get_str(const CxJsonValue *value, const char *name) {
+* @return the value corresponding to the key or @c NULL when the key is not part of the object
-return cx_json_obj_get_cxstr(value, cx_str(name));
+* @see cxJsonIsObject()
+*/
+#define cxJsonObjRemove(value, name) cx_json_obj_remove(value, cx_strcast(name))
+#ifdef __cplusplus
 }
 #endif
-#ifdef __cplusplus
-}
-#endif
 #endif /* UCX_JSON_H */

Mercurial > hg > idav / file comparison

comparison: ucx/cx/json.h

ucx/cx/json.h