Type Casting and Coercion

Relevant source files

The following files were used as context for generating this wiki page:

• tests/test_cast.c
• json_object.c
• json_object.h
• json_util.c
• json_tokener.c

Type casting and coercion in libfastjson refers to the library's ability to interpret a JSON object of one internal type as another type when requested via the API. This mechanism allows developers to retrieve data in a specific C format (e.g., int, double, boolean) even if the underlying JSON representation differs.

The library implements a "liberal" approach to type handling, where functions like fjson_object_get_boolean or fjson_object_get_int perform internal conversions based on predefined logic. This ensures robustness when dealing with loosely typed JSON data or when strict schema adherence is not guaranteed.

Type Identification and Validation

Before performing coercion, the library provides mechanisms to identify the actual type of a fjson_object.

• fjson_object_get_type(obj): Returns the internal fjson_type enum value for the object.
• fjson_object_is_type(obj, type): Returns a boolean indicating if the object matches a specific type.

The following table lists the primary types supported by the library:

Type Enum	Description
fjson_type_null	Represents a JSON null value.
fjson_type_boolean	Represents true or false.
fjson_type_double	Represents floating point numbers.
fjson_type_int	Represents 64-bit signed integers.
fjson_type_object	Represents a JSON object (key-value pairs).
fjson_type_array	Represents an ordered list of JSON objects.
fjson_type_string	Represents a UTF-8 string.

Sources: json_object.h:173-181, json_object.c:166-177, json_util.c:283-291

Coercion Logic and Rules

When a getter function is called for a type that does not match the object's internal type, libfastjson applies specific coercion rules.

Boolean Coercion

The fjson_object_get_boolean function coerces various types to a boolean value.

This diagram illustrates the logic used to determine truthiness across different JSON types.
Sources: json_object.c:500-519, json_object.h:482-493

Integer and Double Coercion

Numeric coercion involves parsing strings or casting between different numeric representations.

• Strings to Numbers: When fjson_object_get_int or fjson_object_get_double is called on a string object, the library attempts to parse the string using fjson_parse_int64 or strtod.
• Out of Range Handling: If a value is too large for a 32-bit integer, the library returns INT32_MAX or INT32_MIN.
• NaN and Infinity: fjson_object_get_double handles special floating-point values. If a string cannot be converted, it returns NaN and sets errno to EINVAL.

Sources: json_object.c:548-577, json_object.c:719-760, json_util.c:168-251

String Coercion

The fjson_object_get_string function provides the most common form of coercion:

1. If the object is a string, it returns the raw character data.
2. If the object is not a string, it invokes the object's _to_json_string method to generate a JSON-formatted string representation of the object.

Sources: json_object.c:836-843, json_object.h:601-619

Technical Implementation Details

The implementation of coercion is distributed between json_object.c (high-level getters) and json_util.c (low-level parsing).

Integer Parsing Utility

The function fjson_parse_int64 is used internally to convert strings to 64-bit integers. It includes workarounds for broken sscanf implementations on certain platforms to ensure accurate range checking.

int fjson_parse_int64(const char *buf, int64_t *retval)
{
    // ... logic to handle leading spaces and signs ...
    if (sscanf(buf, "%" SCNd64, &num64) != 1)
    {
        return 1;
    }
    // ... additional validation for ERANGE and broken sscanf ...
    *retval = num64;
    return 0;
}

Sources: json_util.c:168-251

Type Comparison Sequence

The library allows for case-insensitive comparison of keys, which affects how objects are retrieved and subsequently coerced.

This sequence shows the data flow during an integer retrieval request from a non-integer object.
Sources: json_object.c:548-577, json_object.c:120-124

Summary

Type casting and coercion in libfastjson provide a flexible layer for accessing JSON data in C. By implementing truthiness rules for booleans, robust string-to-number parsing with error handling, and fallback JSON serialization for string access, the library enables developers to safely consume data even when the input format varies from the expected type.

Sources: tests/test_cast.c:1-100, json_object.h:1-700