src/cx/json.h

/*
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
 *
 * Copyright 2024 Mike Becker, Olaf Wintermann All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 *   1. Redistributions of source code must retain the above copyright
 *      notice, this list of conditions and the following disclaimer.
 *
 *   2. Redistributions in binary form must reproduce the above copyright
 *      notice, this list of conditions and the following disclaimer in the
 *      documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */
/**
 * @file json.h
 * @brief Interface for parsing data from JSON files.
 * @author Mike Becker
 * @author Olaf Wintermann
 * @copyright 2-Clause BSD License
 */

#ifndef UCX_JSON_H
#define UCX_JSON_H

#include "common.h"
#include "allocator.h"
#include "string.h"
#include "buffer.h"
#include "array_list.h"
#include "map.h"

#ifdef __cplusplus
extern "C" {
#endif


/**
 * The type of the parsed token.
 */
enum cx_json_token_type {
    /**
     * No complete token parsed, yet.
     */
    CX_JSON_NO_TOKEN,
    /**
     * The presumed token contains syntactical errors.
     */
    CX_JSON_TOKEN_ERROR,
    /**
     * A "begin of array" '[' token.
     */
    CX_JSON_TOKEN_BEGIN_ARRAY,
    /**
     * A "begin of object" '{' token.
     */
    CX_JSON_TOKEN_BEGIN_OBJECT,
    /**
     * An "end of array" ']' token.
     */
    CX_JSON_TOKEN_END_ARRAY,
    /**
     * An "end of object" '}' token.
     */
    CX_JSON_TOKEN_END_OBJECT,
    /**
     * A colon ':' token separating names and values.
     */
    CX_JSON_TOKEN_NAME_SEPARATOR,
    /**
     * A comma ',' token separating object entries or array elements.
     */
    CX_JSON_TOKEN_VALUE_SEPARATOR,
    /**
     * A string token.
     */
    CX_JSON_TOKEN_STRING,
    /**
     * A number token that can be represented as an integer.
     */
    CX_JSON_TOKEN_INTEGER,
    /**
     * A number token that cannot be represented as an integer.
     */
    CX_JSON_TOKEN_NUMBER,
    /**
     * A literal token.
     */
    CX_JSON_TOKEN_LITERAL,
    /**
     * A white-space token.
     */
    CX_JSON_TOKEN_SPACE
};

/**
 * The type of some JSON value.
 */
enum cx_json_value_type {
    /**
     * Reserved.
     */
    CX_JSON_NOTHING, // this allows us to always return non-NULL values
    /**
     * A JSON object.
     */
    CX_JSON_OBJECT,
    /**
     * A JSON array.
     */
    CX_JSON_ARRAY,
    /**
     * A string.
     */
    CX_JSON_STRING,
    /**
     * A number that contains an integer.
     */
    CX_JSON_INTEGER,
    /**
     * A number, not necessarily an integer.
     */
    CX_JSON_NUMBER,
    /**
     * A literal (true, false, null).
     */
    CX_JSON_LITERAL
};

/**
 * JSON literal types.
 */
enum cx_json_literal {
    /**
     * The @c null literal.
     */
    CX_JSON_NULL,
    /**
     * The @c true literal.
     */
    CX_JSON_TRUE,
    /**
     * The @c false literal.
     */
    CX_JSON_FALSE
};

/**
 * Type alias for the token type enum.
 */
typedef enum cx_json_token_type CxJsonTokenType;
/**
 * Type alias for the value type enum.
 */
typedef enum cx_json_value_type CxJsonValueType;

/**
 * Type alias for the JSON parser interface.
 */
typedef struct cx_json_s CxJson;

/**
 * Type alias for the token struct.
 */
typedef struct cx_json_token_s CxJsonToken;

/**
 * Type alias for the JSON value struct.
 */
typedef struct cx_json_value_s CxJsonValue;

/**
 * Type alias for the map representing a JSON object.
 * The map contains pointers of type @c CxJsonValue.
 */
typedef CxMap* CxJsonObject;
/**
 * Type alias for a JSON string.
 */
typedef struct cx_mutstr_s CxJsonString;
/**
 * Type alias for a number that can be represented as a 64-bit signed integer.
 */
typedef int64_t CxJsonInteger;
/**
 * Type alias for a number that is not an integer.
 */
typedef double CxJsonNumber;
/**
 * Type alias for a JSON literal.
 */
typedef enum cx_json_literal CxJsonLiteral;

/**
 * Structure for a JSON value.
 */
struct cx_json_value_s {
    /**
     * The allocator with which the value was allocated.
     *
     * Required for recursively deallocating memory of objects and arrays.
     */
    const CxAllocator *allocator;
    /**
     * The type of this value.
     *
     * Specifies how the @c value union shall be resolved.
     */
    CxJsonValueType type;
    /**
     * The value data.
     */
    union {
        /**
         * The array data if the type is #CX_JSON_ARRAY.
         */
        CX_ARRAY(CxJsonValue*, array);
        /**
         * The object data if the type is #CX_JSON_OBJECT.
         */
        CxJsonObject object;
        /**
         * The string data if the type is #CX_JSON_STRING.
         */
        CxJsonString string;
        /**
         * The integer if the type is #CX_JSON_INTEGER.
         */
        CxJsonInteger integer;
        /**
         * The number if the type is #CX_JSON_NUMBER.
         */
        CxJsonNumber number;
        /**
         * The literal type if the type is #CX_JSON_LITERAL.
         */
        CxJsonLiteral literal;
    };
};

/**
 * Internally used structure for a parsed token.
 * 
 * You should never need to use this in your code.
 */
struct cx_json_token_s {
    /**
     * The token type.
     */
    CxJsonTokenType tokentype;
    /**
     * True, if the @c content must be passed to cx_strfree().
     */
    bool allocated;
    /**
     * The token text, if any.
     *
     * This is not necessarily set when the token type already
     * uniquely identifies the content.
     */
    cxmutstr content;
};

/**
 * The JSON parser interface.
 */
struct cx_json_s {
    /**
     * The allocator used for produced JSON values.
     */
    const CxAllocator *allocator;

    /**
     * The input buffer.
     */
    CxBuffer buffer;

    /**
     * A pointer to an intermediate state of the currently parsed value.
     *
     * Never access this value manually.
     */
    CxJsonValue *parsed;

    /**
     * The name of a not yet completely parsed object member.
     *
     * Never access this value manually.
     */
    cxmutstr uncompleted_member_name;

    /**
     * Internal buffer for uncompleted tokens.
     */
    cxmutstr uncompleted_content;

    /**
     * The expected type of the currently parsed, uncompleted token.
     */
    CxJsonTokenType uncompleted_tokentype;

    /**
     * State stack.
     */
    CX_ARRAY(int, states);

    /**
     * Value buffer stack.
     */
    CX_ARRAY(CxJsonValue*, vbuf);

    /**
     * Internally reserved memory for the state stack.
     */
    int states_internal[8];

    /**
     * Internally reserved memory for the value buffer stack.
     */
    CxJsonValue* vbuf_internal[8];
};

/**
 * Status codes for the JSON interface.
 */
enum cx_json_status {
    /**
     * 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
};

/**
 * Typedef for the JSON status enum.
 */
typedef enum cx_json_status CxJsonStatus;

/**
 * The JSON writer settings.
 */
struct cx_json_writer_s {
    /**
     * Set true to enable pretty output.
     */
    bool pretty;
    /**
     * 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.
     */
    uint8_t frac_max_digits;
    /**
     * Set true to use spaces instead of tab characters.
     * Indentation is only used in pretty output.
     */
    bool indent_space;
    /**
     * If @c indent_space is true, this is the number of spaces per tab.
     * Indentation is only used in pretty output.
     */
    uint8_t indent;
    /**
     * Set true to enable escaping of the slash character (solidus).
     */
    bool escape_slash;
};

/**
 * Typedef for the JSON writer.
 */
typedef struct cx_json_writer_s CxJsonWriter;

/**
 * Creates a default writer configuration for compact output.
 *
 * @return new JSON writer settings
 */
cx_attr_nodiscard
CX_EXPORT CxJsonWriter cxJsonWriterCompact(void);

/**
 * Creates a default writer configuration for pretty output.
 *
 * @param use_spaces false if you want tabs, true if you want four spaces instead
 * @return new JSON writer settings
 */
cx_attr_nodiscard
CX_EXPORT CxJsonWriter cxJsonWriterPretty(bool use_spaces);

/**
 * Writes a JSON value to a buffer or stream.
 *
 * 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. You can, for example, use the buffer's flush
 * feature to relay the data.
 *
 * @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)
 * @retval zero success
 * @retval non-zero when no or not all data could be written
 */
cx_attr_nonnull_arg(1, 2, 3)
CX_EXPORT int cxJsonWrite(void* target, const CxJsonValue* value,
        cx_write_func wfunc, const CxJsonWriter* settings);


/**
 * Produces a compact string representation of the specified JSON value.
 *
 * @param allocator the allocator for the string
 * @param value the JSON value
 * @return the produced string
 * @see cxJsonWrite()
 * @see cxJsonWriterCompact()
 * @see cxJsonToPrettyString()
 */
cx_attr_nonnull_arg(2)
CX_EXPORT cxmutstr cxJsonToString(const CxAllocator *allocator, CxJsonValue *value);

/**
 * Produces a pretty string representation of the specified JSON value.
 *
 * @param allocator the allocator for the string
 * @param value the JSON value
 * @return the produced string
 * @see cxJsonWrite()
 * @see cxJsonWriterPretty()
 * @see cxJsonToString()
 */
cx_attr_nonnull_arg(2)
CX_EXPORT cxmutstr cxJsonToPrettyString(const CxAllocator *allocator, CxJsonValue *value);

/**
 * Initializes 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_EXPORT void cxJsonInit(CxJson *json, const CxAllocator *allocator);

/**
 * Destroys the JSON interface.
 *
 * @param json the JSON interface
 * @see cxJsonInit()
 */
cx_attr_nonnull
CX_EXPORT void cxJsonDestroy(CxJson *json);

/**
 * Destroys and re-initializes the JSON interface.
 *
 * You must use this to reset the parser after encountering a syntax error
 * if you want to continue using it.
 *
 * @param json the JSON interface
 */
cx_attr_nonnull
CX_EXPORT void cxJsonReset(CxJson *json);

/**
 * Fills the input buffer.
 *
 * @remark The JSON interface tries to avoid copying the input data.
 * When you use this function and cxJsonNext() interleaving,
 * no copies are performed. However, you must not free the
 * 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 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_arg(1) cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonFilln(CxJson *json, const char *buf, size_t len);


/**
 * Internal function, do not use.
 *
 * @param json the JSON interface
 * @param str the string
 * @retval zero success
 * @retval non-zero internal allocation error
 */
cx_attr_nonnull
CX_INLINE int cx_json_fill(CxJson *json, cxstring str) {
    return cxJsonFilln(json, str.ptr, str.length);
}

/**
 * Fills the input buffer.
 *
 * The JSON interface tries to avoid copying the input data.
 * When you use this function and cxJsonNext() interleaving,
 * no copies are performed. However, you must not free the
 * 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 str the source string
 * @retval zero success
 * @retval non-zero internal allocation error
 * @see cxJsonFilln()
 */
#define cxJsonFill(json, str) cx_json_fill(json, cx_strcast(str))


/**
 * Internal function - use cxJsonFromString() instead.
 *
 * @param allocator the allocator for the JSON value
 * @param str the string to parse
 * @param value a pointer where the JSON value shall be stored to
 * @return status code
 */
cx_attr_nonnull_arg(3)
CX_EXPORT CxJsonStatus cx_json_from_string(const CxAllocator *allocator,
            cxstring str, CxJsonValue **value);

/**
 * Parses a string into a JSON value.
 *
 * @param allocator (@c CxAllocator*) the allocator for the JSON value
 * @param str (any string) the string to parse
 * @param value (@c CxJsonValue**) a pointer where the JSON value shall be stored to
 * @retval CX_JSON_NO_ERROR success
 * @retval CX_JSON_NO_DATA the string was empty or blank
 * @retval CX_JSON_INCOMPLETE_DATA the string unexpectedly ended
 * @retval CX_JSON_BUFFER_ALLOC_FAILED allocating internal buffer space failed
 * @retval CX_JSON_VALUE_ALLOC_FAILED allocating memory for the CxJsonValue failed
 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number
 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error
 */
#define cxJsonFromString(allocator, str, value) \
        cx_json_from_string(allocator, cx_strcast(str), value)

/**
 * Creates a new (empty) JSON object.
 *
 * @param allocator the allocator to use
 * @return the new JSON object or @c NULL if allocation fails
 * @see cxJsonObjPutObj()
 * @see cxJsonArrAddValues()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator);

/**
 * Creates a new (empty) JSON array.
 *
 * Optionally, this function already allocates memory with the given capacity.
 *
 * @param allocator the allocator to use
 * @param capacity optional capacity or zero if it's unknown how many elements the array will have
 * @return the new JSON array or @c NULL if allocation fails
 * @see cxJsonObjPutArr()
 * @see cxJsonArrAddValues()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator, size_t capacity);

/**
 * Creates a new JSON number value.
 *
 * @param allocator the allocator to use
 * @param num the numeric value
 * @return the new JSON value or @c NULL if allocation fails
 * @see cxJsonObjPutNumber()
 * @see cxJsonArrAddNumbers()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cxJsonCreateNumber(const CxAllocator* allocator, double num);

/**
 * Creates a new JSON number value based on an integer.
 *
 * @param allocator the allocator to use
 * @param num the numeric value
 * @return the new JSON value or @c NULL if allocation fails
 * @see cxJsonObjPutInteger()
 * @see cxJsonArrAddIntegers()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cxJsonCreateInteger(const CxAllocator* allocator, int64_t num);

/**
 * Creates a new JSON string.
 *
 * Internal function - use cxJsonCreateString() instead.
 *
 * @param allocator the allocator to use
 * @param str the string data
 * @return the new JSON value or @c NULL if allocation fails
 * @see cxJsonObjPutString()
 * @see cxJsonArrAddCxStrings()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cx_json_create_string(const CxAllocator* allocator, cxstring str);

/**
 * Creates a new JSON string.
 *
 * @param allocator (@c CxAllocator*) the allocator to use
 * @param str the string
 * @return (@c CxJsonValue*) the new JSON value or @c NULL if allocation fails
 * @see cxJsonObjPutString()
 * @see cxJsonArrAddCxStrings()
 */
#define cxJsonCreateString(allocator, str) cx_json_create_string(allocator, cx_strcast(str))

/**
 * Creates a new JSON literal.
 *
 * @param allocator the allocator to use
 * @param lit the type of literal
 * @return the new JSON value or @c NULL if allocation fails
 * @see cxJsonObjPutLiteral()
 * @see cxJsonArrAddLiterals()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cxJsonCreateLiteral(const CxAllocator* allocator, CxJsonLiteral lit);

/**
 * Adds number values to a JSON array.
 *
 * @param arr the JSON array
 * @param num the array of values
 * @param count the number of elements
 * @retval zero success
 * @retval non-zero allocation failure
 */
cx_attr_nonnull cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonArrAddNumbers(CxJsonValue* arr, const double* num, size_t count);

/**
 * Adds number values, of which all are integers, to a JSON array.
 *
 * @param arr the JSON array
 * @param num the array of values
 * @param count the number of elements
 * @retval zero success
 * @retval non-zero allocation failure
 */
cx_attr_nonnull cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonArrAddIntegers(CxJsonValue* arr, const int64_t* num, size_t count);

/**
 * Adds strings to a JSON array.
 *
 * The strings will be copied with the allocator of the array.
 *
 * @param arr the JSON array
 * @param str the array of strings
 * @param count the number of elements
 * @retval zero success
 * @retval non-zero allocation failure
 * @see cxJsonArrAddCxStrings()
 */
cx_attr_nonnull cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonArrAddStrings(CxJsonValue* arr, const char* const* str, size_t count);

/**
 * Adds strings to a JSON array.
 *
 * The strings will be copied with the allocator of the array.
 *
 * @param arr the JSON array
 * @param str the array of strings
 * @param count the number of elements
 * @retval zero success
 * @retval non-zero allocation failure
 * @see cxJsonArrAddStrings()
 */
cx_attr_nonnull cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonArrAddCxStrings(CxJsonValue* arr, const cxstring* str, size_t count);

/**
 * Adds literals to a JSON array.
 *
 * @param arr the JSON array
 * @param lit the array of literal types
 * @param count the number of elements
 * @retval zero success
 * @retval non-zero allocation failure
 */
cx_attr_nonnull cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonArrAddLiterals(CxJsonValue* arr, const CxJsonLiteral* lit, size_t count);

/**
 * Add arbitrary values to a JSON array.
 *
 * @attention In contrast to all other add functions, this function adds the values
 * directly to the array instead of copying them.
 *
 * @param arr the JSON array
 * @param val the values
 * @param count the number of elements
 * @retval zero success
 * @retval non-zero allocation failure
 */
cx_attr_nonnull cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonArrAddValues(CxJsonValue* arr, CxJsonValue* const* val, size_t count);

/**
 * Adds or replaces a value within a JSON object.
 *
 * Internal function - use cxJsonObjPut().
 *
 * @param obj the JSON object
 * @param name the name of the value
 * @param child the value
 * @retval zero success
 * @retval non-zero allocation failure
 */
cx_attr_nonnull
CX_EXPORT int cx_json_obj_put(CxJsonValue* obj, cxstring name, CxJsonValue* child);

/**
 * Adds or replaces a value within a JSON object.
 *
 * The value will be directly added and not copied.
 *
 * @note If a value with the specified @p name already exists,
 * it will be (recursively) freed with its own allocator.
 *
 * @param obj (@c CxJsonValue*) the JSON object
 * @param name (any string) the name of the value
 * @param child (@c CxJsonValue*) the value
 * @retval zero success
 * @retval non-zero allocation failure
 */
#define cxJsonObjPut(obj, name, child) cx_json_obj_put(obj, cx_strcast(name), child)

/**
 * Creates a new JSON object and adds it to an existing object.
 *
 * Internal function - use cxJsonObjPutObj().
 *
 * @param obj the target JSON object
 * @param name the name of the new value
 * @return the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateObj()
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue* cx_json_obj_put_obj(CxJsonValue* obj, cxstring name);

/**
 * Creates a new JSON object and adds it to an existing object.
 *
 * @param obj (@c CxJsonValue*) the target JSON object
 * @param name (any string) the name of the new value
 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateObj()
 */
#define cxJsonObjPutObj(obj, name) cx_json_obj_put_obj(obj, cx_strcast(name))

/**
 * Creates a new JSON array and adds it to an object.
 *
 * Internal function - use cxJsonObjPutArr().
 *
 * @param obj the target JSON object
 * @param name the name of the new value
 * @param capacity optional initial capacity
 * @return the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateArr()
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue* cx_json_obj_put_arr(CxJsonValue* obj, cxstring name, size_t capacity);

/**
 * Creates a new JSON array and adds it to an object.
 *
 * @param obj (@c CxJsonValue*) the target JSON object
 * @param name (any string) the name of the new value
 * @param capacity (@c size_t) optional initial capacity
 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateArr()
 */
#define cxJsonObjPutArr(obj, name, capacity) cx_json_obj_put_arr(obj, cx_strcast(name), capacity)

/**
 * Creates a new JSON number and adds it to an object.
 *
 * Internal function - use cxJsonObjPutNumber().
 *
 * @param obj the target JSON object
 * @param name the name of the new value
 * @param num the numeric value
 * @return the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateNumber()
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue* cx_json_obj_put_number(CxJsonValue* obj, cxstring name, double num);

/**
 * Creates a new JSON number and adds it to an object.
 *
 * @param obj (@c CxJsonValue*) the target JSON object
 * @param name (any string) the name of the new value
 * @param num (@c double) the numeric value
 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateNumber()
 */
#define cxJsonObjPutNumber(obj, name, num) cx_json_obj_put_number(obj, cx_strcast(name), num)

/**
 * Creates a new JSON number, based on an integer, and adds it to an object.
 *
 * Internal function - use cxJsonObjPutInteger().
 *
 * @param obj the target JSON object
 * @param name the name of the new value
 * @param num the numeric value
 * @return the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateInteger()
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue* cx_json_obj_put_integer(CxJsonValue* obj, cxstring name, int64_t num);

/**
 * Creates a new JSON number, based on an integer, and adds it to an object.
 *
 * @param obj (@c CxJsonValue*) the target JSON object
 * @param name (any string) the name of the new value
 * @param num (@c int64_t) the numeric value
 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateInteger()
 */
#define cxJsonObjPutInteger(obj, name, num) cx_json_obj_put_integer(obj, cx_strcast(name), num)

/**
 * Creates a new JSON string and adds it to an object.
 *
 * Internal function - use cxJsonObjPutString()
 *
 * @param obj the target JSON object
 * @param name the name of the new value
 * @param str the string data
 * @return the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateString()
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue* cx_json_obj_put_string(CxJsonValue* obj, cxstring name, cxstring str);

/**
 * Creates a new JSON string and adds it to an object.
 *
 * The string data is copied.
 *
 * @param obj (@c CxJsonValue*) the target JSON object
 * @param name (any string) the name of the new value
 * @param str (any string) the string data
 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateString()
 */
#define cxJsonObjPutString(obj, name, str) cx_json_obj_put_string(obj, cx_strcast(name), cx_strcast(str))

/**
 * Creates a new JSON literal and adds it to an object.
 *
 * Internal function - use cxJsonObjPutLiteral().
 *
 * @param obj the target JSON object
 * @param name the name of the new value
 * @param lit the type of literal
 * @return the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateLiteral()
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue* cx_json_obj_put_literal(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);

/**
 * Creates a new JSON literal and adds it to an object.
 *
 * @param obj (@c CxJsonValue*) the target JSON object
 * @param name (any string) the name of the new value
 * @param lit (@c CxJsonLiteral) the type of literal
 * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
 * @see cxJsonObjPut()
 * @see cxJsonCreateLiteral()
 */
#define cxJsonObjPutLiteral(obj, name, lit) cx_json_obj_put_literal(obj, cx_strcast(name), lit)

/**
 * 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 a type will be skipped
 * 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
 */
CX_EXPORT void cxJsonValueFree(CxJsonValue *value);

/**
 * Tries to obtain the next JSON value.
 *
 * Before this function can be called, the input buffer needs
 * to be filled with cxJsonFill().
 *
 * 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 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
 * @retval CX_JSON_NULL_DATA the buffer was never initialized
 * @retval CX_JSON_BUFFER_ALLOC_FAILED allocating internal buffer space failed
 * @retval CX_JSON_VALUE_ALLOC_FAILED allocating memory for a CxJsonValue failed
 * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number
 * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error
 */
cx_attr_nonnull cx_attr_access_w(2)
CX_EXPORT CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value);

/**
 * Checks if the specified value is a JSON object.
 *
 * @param value a pointer to the value
 * @retval true the value is a JSON object
 * @retval false otherwise
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsObject(const CxJsonValue *value) {
    return value->type == CX_JSON_OBJECT;
}

/**
 * Checks if the specified value is a JSON array.
 *
 * @param value a pointer to the value
 * @retval true the value is a JSON array
 * @retval false otherwise
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsArray(const CxJsonValue *value) {
    return value->type == CX_JSON_ARRAY;
}

/**
 * Checks if the specified value is a string.
 *
 * @param value a pointer to the value
 * @retval true the value is a string
 * @retval false otherwise
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsString(const CxJsonValue *value) {
    return value->type == CX_JSON_STRING;
}

/**
 * Checks if the specified value is a JSON number.
 *
 * 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
 * @see cxJsonIsInteger()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsNumber(const CxJsonValue *value) {
    return value->type == CX_JSON_NUMBER || value->type == CX_JSON_INTEGER;
}

/**
 * Checks if the specified value is an integer number.
 *
 * @param value a pointer to the value
 * @retval true the value is an integer number
 * @retval false otherwise
 * @see cxJsonIsNumber()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsInteger(const CxJsonValue *value) {
    return value->type == CX_JSON_INTEGER;
}

/**
 * Checks if the specified value is a JSON literal.
 *
 * JSON literals are @c true, @c false, and @c null.
 *
 * @param value a pointer to the value
 * @retval true the value is a JSON literal
 * @retval false otherwise
 * @see cxJsonIsTrue()
 * @see cxJsonIsFalse()
 * @see cxJsonIsNull()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsLiteral(const CxJsonValue *value) {
    return value->type == CX_JSON_LITERAL;
}

/**
 * Checks if the specified value is a Boolean literal.
 *
 * @param value a pointer to the value
 * @retval true the value is either @c true or @c false
 * @retval false otherwise
 * @see cxJsonIsTrue()
 * @see cxJsonIsFalse()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsBool(const CxJsonValue *value) {
    return cxJsonIsLiteral(value) && value->literal != CX_JSON_NULL;
}

/**
 * Checks if the specified value is @c true.
 *
 * @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
 * @see cxJsonIsBool()
 * @see cxJsonIsFalse()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsTrue(const CxJsonValue *value) {
    return cxJsonIsLiteral(value) && value->literal == CX_JSON_TRUE;
}

/**
 * Checks if the specified value is @c false.
 *
 * @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
 * @see cxJsonIsBool()
 * @see cxJsonIsTrue()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsFalse(const CxJsonValue *value) {
    return cxJsonIsLiteral(value) && value->literal == CX_JSON_FALSE;
}

/**
 * Checks if the specified value is @c null.
 *
 * @param value a pointer to the value
 * @retval true the value is @c null
 * @retval false otherwise
 * @see cxJsonIsLiteral()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonIsNull(const CxJsonValue *value) {
    return cxJsonIsLiteral(value) && value->literal == CX_JSON_NULL;
}

/**
 * Obtains a C string from the given JSON value.
 *
 * If the @p value is not a string, the behavior is undefined.
 *
 * @param value the JSON value
 * @return the value represented as C string
 * @see cxJsonIsString()
 */
cx_attr_nonnull  cx_attr_returns_nonnull
CX_EXPORT char *cxJsonAsString(const CxJsonValue *value);

/**
 * Obtains a UCX string from the given JSON value.
 *
 * If the @p value is not a string, the behavior is undefined.
 *
 * @param value the JSON value
 * @return the value represented as UCX string
 * @see cxJsonIsString()
 */
cx_attr_nonnull
CX_EXPORT cxstring cxJsonAsCxString(const CxJsonValue *value);

/**
 * Obtains a mutable UCX string from the given JSON value.
 *
 * If the @p value is not a string, the behavior is undefined.
 *
 * @param value the JSON value
 * @return the value represented as mutable UCX string
 * @see cxJsonIsString()
 */
cx_attr_nonnull
CX_EXPORT cxmutstr cxJsonAsCxMutStr(const CxJsonValue *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
 * @see cxJsonIsNumber()
 */
cx_attr_nonnull
CX_EXPORT double cxJsonAsDouble(const CxJsonValue *value);

/**
 * Obtains a 64-bit signed integer from the given JSON value.
 *
 * If the @p value is not a JSON number, the behavior is undefined.
 * If it is a JSON number, but not an integer, the value will be
 * converted to an integer, possibly losing precision.
 *
 * @param value the JSON value
 * @return the value represented as double
 * @see cxJsonIsNumber()
 * @see cxJsonIsInteger()
 */
cx_attr_nonnull
CX_EXPORT int64_t cxJsonAsInteger(const CxJsonValue *value);

/**
 * Obtains a Boolean value from the given JSON value.
 *
 * If the @p value is not a JSON literal, the behavior is undefined.
 * The @c null literal is interpreted as @c false.
 *
 * @param value the JSON value
 * @return the value represented as double
 * @see cxJsonIsLiteral()
 */
cx_attr_nonnull
CX_INLINE bool cxJsonAsBool(const CxJsonValue *value) {
    return value->literal == CX_JSON_TRUE;
}

/**
 * Returns the size of a JSON array.
 *
 * If the @p value is not a JSON array, the behavior is undefined.
 *
 * @param value the JSON value
 * @return the size of the array
 * @see cxJsonIsArray()
 */
cx_attr_nonnull
CX_INLINE size_t cxJsonArrSize(const CxJsonValue *value) {
    return value->array.size;
}

/**
 * Returns an element from a JSON array.
 *
 * If the @p value is not a JSON array, the behavior is undefined.
 *
 * This function guarantees to return a value. If the index is
 * out of bounds, the returned value will be of type
 * #CX_JSON_NOTHING, but never @c NULL.
 *
 * @param value the JSON value
 * @param index the index in the array
 * @return the value at the specified index
 * @see cxJsonIsArray()
 */
cx_attr_nonnull cx_attr_returns_nonnull
CX_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_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.
 *
 * @param value the JSON value
 * @return an iterator over the array elements
 * @see cxJsonIsArray()
 */
cx_attr_nonnull cx_attr_nodiscard
CX_EXPORT CxIterator cxJsonArrIter(const CxJsonValue *value);

/**
 * Returns the size of a JSON object.
 *
 * If the @p value is not a JSON object, the behavior is undefined.
 *
 * @param value the JSON value
 * @return the size of the object, i.e., the number of key/value pairs
 * @see cxJsonIsObject()
 */
cx_attr_nonnull
CX_INLINE size_t cxJsonObjSize(const CxJsonValue *value) {
    return cxCollectionSize(value->object);
}

/**
 * Returns a map iterator over the JSON object members.
 *
 * The iterator yields values of type @c CxMapEntry* which
 * contain the name and the @c CxJsonObjValue* of the member.
 *
 * If the @p value is not a JSON object, the behavior is undefined.
 *
 * @param value the JSON value
 * @return an iterator over the object members
 * @see cxJsonIsObject()
 */
cx_attr_nonnull cx_attr_nodiscard
CX_EXPORT CxMapIterator cxJsonObjIter(const CxJsonValue *value);

/**
 * 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_EXPORT CxJsonValue *cx_json_obj_get(const CxJsonValue *value, cxstring name);

/**
 * Returns a value corresponding to a key in a JSON object.
 *
 * If the @p value is not a JSON object, the behavior is undefined.
 *
 * This function guarantees to return a JSON value. If the
 * object does not contain @p name, the returned JSON value
 * will be of type #CX_JSON_NOTHING, but never @c NULL.
 *
 * @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) cx_json_obj_get(value, cx_strcast(name))

/**
 * Internal function, do not use.
 * @param value the JSON object
 * @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
 */
cx_attr_nonnull
CX_EXPORT CxJsonValue *cx_json_obj_remove(CxJsonValue *value, cxstring 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.
 *
 * This function, in contrast to cxJsonObjGet() returns @c NULL when the
 * object does not contain @p name.
 *
 * @param value the JSON object
 * @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
 * @see cxJsonIsObject()
 */
#define cxJsonObjRemove(value, name) cx_json_obj_remove(value, cx_strcast(name))

/**
 * Performs a deep comparison of two JSON values.
 *
 * The order of object members is ignored during comparison.
 *
 * @param json the JSON value
 * @param other the other JSON value that the JSON value is compared to
 * @retval zero the values are equal (except for ordering of object members)
 * @retval non-zero the values differ
 */
CX_EXPORT int cxJsonCompare(const CxJsonValue *json, const CxJsonValue *other);


/**
 * Creates a deep copy of the specified JSON value.
 *
 * If you need a @c cx_clone_func compatible version, see cxJsonCloneFunc().
 *
 * @note when you are cloning @c NULL, you will get a pointer to a statically
 * allocated value which represents nothing.
 *
 * @param value the value to be cloned
 * @param allocator the allocator for the new value
 * @return the new value or @c NULL if any allocation was unsuccessful
 * @see cxJsonCloneFunc()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cxJsonClone(const CxJsonValue* value,
        const CxAllocator* allocator);


/**
 * A @c cx_clone_func compatible version of cxJsonClone().
 *
 * Internal function - use cxJsonCloneFunc() to get a properly casted function pointer.
 *
 * @param target the target memory or @c NULL
 * @param source the value to be cloned
 * @param allocator the allocator for the new value
 * @param data unused
 * @return the new value or @c NULL if any allocation was unsuccessful
 * @see cxJsonClone()
 */
cx_attr_nodiscard
CX_EXPORT CxJsonValue* cx_json_clone_func(
        CxJsonValue* target, const CxJsonValue* source,
        const CxAllocator* allocator, void *data);

/**
 * A @c cx_clone_func compatible version of cxJsonClone().
 *
 * @param target (@c CxJsonValue*) the target memory or @c NULL
 * @param source (@c CxJsonValue*) the value to be cloned
 * @param allocator (@c CxAllocator*) the allocator for the new value
 * @param data unused
 * @return the new value or @c NULL if any allocation was unsuccessful
 * @see cxJsonClone()
 */
#define cxJsonCloneFunc  ((cx_clone_func) cx_json_clone_func)

#ifdef __cplusplus
}
#endif

#endif /* UCX_JSON_H */