Generic API

Introduction

For an overview of the generic runtime, read Generics Guide first. It uses fy_generic as the starting point, then covers the runtime type model, schema choices, and lifetime rules assumed by the API reference below.

Generic Storage Types

type fy_generic_indirect

Wrapper attaching YAML metadata to a generic value.

An indirect is allocated out-of-place and pointed to by a tagged fy_generic word with type tag FY_INDIRECT_V. It stores the actual value plus optional metadata controlled by the FYGIF_* flag bits. An alias is encoded as an indirect with value set to fy_invalid and anchor holding the alias target name.

type fy_generic_sequence

Out-of-place storage for a generic sequence.

A contiguous block of count fy_generic items follows the header. The allocation must remain 16-byte aligned; the layout is shared with fy_generic_collection and is relied on by low-level generic helpers.

type fy_generic_mapping

Out-of-place storage for a generic mapping.

Stores count key/value pairs as a contiguous flexible array of fy_generic_map_pair elements. The allocation must remain 16-byte aligned.

type fy_generic_collection

Generic view over a sequence or mapping buffer.

Shares the same memory layout as fy_generic_sequence; for mappings, count is the number of pairs and items contains 2 * count interleaved key/value generics.

Generic Type System

A compact, efficient runtime type system for representing arbitrary YAML and JSON values in C, bringing Python/Rust-like dynamically-typed data literals to C programs.

The core type is fy_generic, a single machine word (64 or 32 bit) that encodes one of nine value types via pointer tagging:

  • null, bool, int, float, string — scalar types

  • sequence, mapping — ordered arrays and key/value collections

  • indirect, alias — YAML-specific wrappers (anchor, tag, style, …)

Small values are stored inline in the pointer word with zero heap allocation: 61-bit integers, 7-byte strings, and 32-bit floats all fit in a single machine word.

Three API tiers for different storage lifetimes:

Stack-based (fy_sequence(…), fy_mapping(…), fy_to_generic(x)): values live for the duration of the enclosing function. C11 _Generic dispatch automatically selects the right conversion from native C types. Zero heap allocation for scalars and small composite values:

fy_generic config = fy_mapping(
    "host", "localhost",
    "port", 8080,
    "tls",  true);

Low-level (fy_sequence_alloca(), fy_mapping_alloca()): build from pre-constructed fy_generic arrays; the caller controls all allocation.

Builder (fy_gb_sequence(), fy_gb_mapping()): fy allocator created values that survive beyond the current function. Automatically internalises any stack-based sub-values passed to it.

Immutability and thread safety: generics are immutable — all operations produce new values. Multiple threads may safely read the same generic concurrently without locking; only the builder’s allocator requires synchronisation for writes.

Conversion: fy_document_to_generic() and fy_generic_to_document() convert between YAML document trees and generic values, enabling the generic API to serve as an efficient in-memory representation for parsed YAML and JSON.

enum fy_generic_type

enum fy_generic_type

Type discriminator for fy_generic values.

Definition

enum fy_generic_type {
    FYGT_INVALID,
    FYGT_NULL,
    FYGT_BOOL,
    FYGT_INT,
    FYGT_FLOAT,
    FYGT_STRING,
    FYGT_SEQUENCE,
    FYGT_MAPPING,
    FYGT_INDIRECT,
    FYGT_ALIAS
};

Constants

FYGT_INVALID

Sentinel representing an invalid or unset value.

FYGT_NULL

YAML/JSON null.

FYGT_BOOL

Boolean (true or false).

FYGT_INT

Signed or unsigned integer.

FYGT_FLOAT

Floating-point (double).

FYGT_STRING

UTF-8 string.

FYGT_SEQUENCE

Ordered sequence of generic values.

FYGT_MAPPING

Key/value mapping of generic values.

FYGT_INDIRECT

Value wrapped with metadata (anchor, tag, style, …).

FYGT_ALIAS

YAML alias (anchor reference).

Description

Identifies the runtime type stored in an struct fy_generic word. The ordering INT < FLOAT < STRING must be preserved; internal bithacks depend on consecutive placement.

fy_generic_type_is_scalar

bool fy_generic_type_is_scalar(const enum fy_generic_type type)

Test whether a type is a scalar type.

Parameters:

Return

true if type is one of FYGT_NULL, FYGT_BOOL, FYGT_INT, FYGT_FLOAT, or FYGT_STRING; false otherwise.

fy_generic_type_is_collection

bool fy_generic_type_is_collection(const enum fy_generic_type type)

Test whether a type is a collection type.

Parameters:

Return

true if type is FYGT_SEQUENCE or FYGT_MAPPING; false otherwise.

enum fy_generic_type_mask

enum fy_generic_type_mask

Bitmask constants for sets of generic types.

Definition

enum fy_generic_type_mask {
    FYGTM_INVALID,
    FYGTM_NULL,
    FYGTM_BOOL,
    FYGTM_INT,
    FYGTM_FLOAT,
    FYGTM_STRING,
    FYGTM_SEQUENCE,
    FYGTM_MAPPING,
    FYGTM_INDIRECT,
    FYGTM_ALIAS,
    FYGTM_COLLECTION,
    FYGTM_SCALAR,
    FYGTM_ANY
};

Constants

FYGTM_INVALID

Bit for FYGT_INVALID.

FYGTM_NULL

Bit for FYGT_NULL.

FYGTM_BOOL

Bit for FYGT_BOOL.

FYGTM_INT

Bit for FYGT_INT.

FYGTM_FLOAT

Bit for FYGT_FLOAT.

FYGTM_STRING

Bit for FYGT_STRING.

FYGTM_SEQUENCE

Bit for FYGT_SEQUENCE.

FYGTM_MAPPING

Bit for FYGT_MAPPING.

FYGTM_INDIRECT

Bit for FYGT_INDIRECT.

FYGTM_ALIAS

Bit for FYGT_ALIAS.

FYGTM_COLLECTION

Combined mask for sequences and mappings.

FYGTM_SCALAR

Combined mask for all scalar types (null through string).

FYGTM_ANY

Combined mask for all non-invalid, non-alias types.

Description

Each enumerator is a single bit corresponding to the matching enum fy_generic_type value. Combine them with bitwise OR to test for membership in a set of types.

typedef fy_generic_value

type fy_generic_value

Unsigned word used as the raw tagged-pointer storage.

Description

The low 3 bits hold the type tag; the remaining bits hold either an inplace value (integer, short string, 32-bit float on 64-bit) or an aligned pointer to heap/stack-allocated storage.

typedef fy_generic_value_signed

type fy_generic_value_signed

Signed variant of fy_generic_value.

Description

Used when arithmetic sign-extension of the raw word is needed, e.g. when decoding inplace signed integers.

macro FY_STRING_SHIFT7

FY_STRING_SHIFT7(_v0, _v1, _v2, _v3, _v4, _v5, _v6)

Build a 7-byte inplace string encoding word (64-bit).

Parameters:

  • _v0 – First character byte (or 0 for padding).

  • _v1 – Second character byte.

  • _v2 – Third character byte.

  • _v3 – Fourth character byte.

  • _v4 – Fifth character byte.

  • _v5 – Sixth character byte.

  • _v6 – Seventh character byte.

Description

Packs up to seven character bytes into the upper 56 bits of a struct fy_generic_value in the byte order expected by the host so that the low 8 bits remain free for the type tag and length field. Endian-specific: little-endian stores _v0 at bits 8-15, big-endian stores _v0 at bits 55-48.

Return

A fy_generic_value with the seven bytes packed in, ready to be OR-ed with the type tag and string length.

macro FY_STRING_SHIFT3

FY_STRING_SHIFT3(_v0, _v1, _v2)

Build a 3-byte inplace string encoding word (32-bit).

Parameters:

  • _v0 – First character byte (or 0 for padding).

  • _v1 – Second character byte.

  • _v2 – Third character byte.

Description

Packs up to three character bytes into the upper 24 bits of a struct fy_generic_value, leaving the low 8 bits free for tag and length. Endian-specific like FY_STRING_SHIFT7().

Return

A fy_generic_value with the three bytes packed in.

macro FY_MAX_ALIGNOF

FY_MAX_ALIGNOF(_v, _min)

Return the larger of _Alignof(@_v) and _min.

Parameters:

  • _v – Expression whose alignment is queried.

  • _min – Minimum alignment to enforce.

Note

evaluates _v twice; avoid expressions with side-effects.

Return

The larger of _Alignof(@_v) and _min as a size_t.

typedef fy_generic

type fy_generic

A space-efficient tagged-union value.

Description

A single pointer-sized word encoding any YAML/JSON value without heap allocation for small scalars (integers up to 61 bits, strings up to 7 bytes on 64-bit, 32-bit floats on 64-bit). Larger values are stored out-of-place; the word holds an aligned pointer with the low 3 bits used as a type tag.

Access the raw word via .v (unsigned) or .vs (signed). Always use the provided accessor functions rather than reading the raw fields.

fy_generic_is_direct

bool fy_generic_is_direct(fy_generic v)

Test whether a generic value is encoded directly.

Parameters:

Description

A direct value stores its type and data entirely in the word (inplace scalars, escape constants, and out-of-place pointers). The opposite of indirect (%FYGT_INDIRECT).

Return

true if v is not an indirect (no wrapping metadata); false otherwise.

fy_generic_is_indirect

bool fy_generic_is_indirect(fy_generic v)

Test whether a generic value is an indirect.

Parameters:

Description

An indirect points to a struct fy_generic_indirect holding the actual value plus optional metadata (anchor, tag, style, diagnostics, …).

Return

true if v is an indirect (%FYGT_INDIRECT); false otherwise.

fy_generic_is_direct_valid

bool fy_generic_is_direct_valid(const fy_generic v)

Test whether a direct generic value is not invalid.

Parameters:

  • v (const fy_generic) – The generic value to test.

Description

Only meaningful for direct (non-indirect) values.

Return

true if v is not the fy_invalid sentinel; false if it is.

fy_generic_is_direct_invalid

bool fy_generic_is_direct_invalid(const fy_generic v)

Test whether a direct generic value is invalid.

Parameters:

  • v (const fy_generic) – The generic value to test.

Description

Only meaningful for direct (non-indirect) values.

Return

true if v equals the fy_invalid sentinel; false otherwise.

fy_generic_resolve_ptr

const void *fy_generic_resolve_ptr(fy_generic ptr)

Extract the raw pointer from a non-collection generic.

Parameters:

  • ptr (fy_generic) – An out-of-place non-collection generic value.

Description

Strips the 3-bit type tag from ptr to recover the original aligned pointer for out-of-place scalars (int, float, string, indirect). Not valid for collection values — use fy_generic_resolve_collection_ptr() instead.

Return

The 8-byte-aligned pointer stored in ptr.

fy_generic_resolve_collection_ptr

const void *fy_generic_resolve_collection_ptr(fy_generic ptr)

Extract the raw pointer from a collection generic.

Parameters:

  • ptr (fy_generic) – An out-of-place sequence or mapping generic value.

Description

Strips the 4-bit collection mask (type tag + collection discriminator bit) from ptr to recover the 16-byte-aligned pointer for sequences and mappings.

Return

The 16-byte-aligned pointer stored in ptr.

fy_generic_relocate_ptr

fy_generic fy_generic_relocate_ptr(fy_generic v, ptrdiff_t d)

Adjust an out-of-place scalar pointer by a byte delta.

Parameters:

  • v (fy_generic) – An out-of-place non-collection generic value.

  • d (ptrdiff_t) – Byte delta to add to the embedded pointer.

Description

Adds d to the pointer embedded in v while preserving the type tag. Used when moving the backing buffer (e.g. realloc). Asserts that the resulting pointer is still correctly aligned.

Return

A new struct fy_generic with the adjusted pointer and the same type tag.

fy_generic_relocate_collection_ptr

fy_generic fy_generic_relocate_collection_ptr(fy_generic v, ptrdiff_t d)

Adjust a collection pointer by a byte delta.

Parameters:

  • v (fy_generic) – An out-of-place sequence or mapping generic value.

  • d (ptrdiff_t) – Byte delta to add to the embedded pointer.

Description

Like fy_generic_relocate_ptr() but for sequence and mapping values, stripping and restoring the wider 4-bit collection mask.

Return

A new struct fy_generic with the adjusted pointer and the same collection tag.

fy_generic_get_direct_type_table

enum fy_generic_type fy_generic_get_direct_type_table(fy_generic v)

Determine the type of a direct generic (table lookup).

Parameters:

  • v (fy_generic) – A direct (non-indirect) generic value.

Description

Uses a 16-entry lookup table indexed by the low 4 bits of v to classify the value. Handles escape codes for null, true, and false. Prefer fy_generic_get_direct_type_bithack() in hot paths.

Return

The enum fy_generic_type of v, or FYGT_INVALID for unknown escape codes.

fy_generic_get_direct_type_bithack

enum fy_generic_type fy_generic_get_direct_type_bithack(fy_generic v)

Determine the type of a direct generic (bithack).

Parameters:

  • v (fy_generic) – A direct (non-indirect) generic value.

Description

Fast branch-optimised implementation that decodes the type from the low 4 bits using arithmetic rather than a table. For INT, FLOAT, and STRING it exploits the consecutive ordering of the inplace/outplace tag pairs to compute the type in a single expression. This is the preferred implementation used by fy_generic_get_direct_type().

Return

The enum fy_generic_type of v, or FYGT_INVALID for unknown escape codes.

fy_generic_is_in_place_normal

bool fy_generic_is_in_place_normal(fy_generic v)

Test whether a generic value is stored inplace (switch impl).

Parameters:

Description

Returns true when the entire value fits inside the word with no external allocation. Uses a readable switch-based approach; prefer fy_generic_is_in_place_bithack() in hot paths.

Return

true if v requires no heap/stack allocation; false otherwise.

fy_generic_is_in_place_bithack

bool fy_generic_is_in_place_bithack(fy_generic v)

Test whether a generic value is stored inplace (bithack).

Parameters:

Description

Fast branch-friendly implementation. The escape constants (null, true, false, invalid) and empty collections are always inplace. For int, float, and string, bit 0 of the type tag distinguishes inplace (odd) from out-of-place (even).

Return

true if v requires no heap/stack allocation; false otherwise.

fy_generic_is_in_place

bool fy_generic_is_in_place(fy_generic v)

Test whether a generic value is stored inplace.

Parameters:

Description

Preferred alias for fy_generic_is_in_place_bithack().

Return

true if v requires no heap/stack allocation; false otherwise.

fy_generic_get_type_indirect

enum fy_generic_type fy_generic_get_type_indirect(fy_generic v)

Get the type of an indirect generic value.

Parameters:

Description

Dereferences the struct fy_generic_indirect to read the type of the wrapped value. Only call this when fy_generic_is_indirect() returns true.

Return

The enum fy_generic_type of the value wrapped by the indirect.

fy_generic_indirect_get

void fy_generic_indirect_get(fy_generic v, fy_generic_indirect *gi)

Populate a fy_generic_indirect from an indirect value.

Parameters:

Description

Copies all fields of the struct fy_generic_indirect pointed to by v into gi.

fy_genericp_indirect_get_valuep_nocheck

const fy_generic *fy_genericp_indirect_get_valuep_nocheck(const fy_generic *vp)

Get a pointer to the value inside an indirect.

Parameters:

  • vp (const fy_generic*) – Pointer to an indirect generic value.

Description

Returns a pointer into the struct fy_generic_indirect‘s value field without validating that FYGIF_VALUE is set. Only use when the flag is known to be set.

Return

Pointer to the value field of the underlying struct fy_generic_indirect.

fy_genericp_indirect_get_valuep

const fy_generic *fy_genericp_indirect_get_valuep(const fy_generic *vp)

Get a pointer to the value inside an indirect.

Parameters:

  • vp (const fy_generic*) – Pointer to an indirect generic value.

Description

Like fy_genericp_indirect_get_valuep_nocheck() but checks that vp is a valid indirect and that FYGIF_VALUE is set; returns NULL on failure.

Return

Pointer to the value field, or NULL if vp is not a valid indirect with a value.

fy_generic_indirect_get_value_nocheck

fy_generic fy_generic_indirect_get_value_nocheck(const fy_generic v)

Get the value wrapped by an indirect.

Parameters:

  • v (const fy_generic) – An indirect generic value.

Description

Dereferences the indirect without checking flags. Only use when FYGIF_VALUE is known to be set.

Return

The wrapped struct fy_generic value.

fy_generic_indirect_get_value

fy_generic fy_generic_indirect_get_value(const fy_generic v)

Get the value wrapped by an indirect.

Parameters:

  • v (const fy_generic) – An indirect generic value.

Description

Checks that v is a valid indirect with FYGIF_VALUE set.

Return

The wrapped struct fy_generic value, or fy_invalid if not available.

fy_generic_indirect_get_anchor

fy_generic fy_generic_indirect_get_anchor(fy_generic v)

Get the anchor from an indirect.

Parameters:

Return

The anchor as a string struct fy_generic, or fy_null if FYGIF_ANCHOR is not set.

fy_generic_indirect_get_tag

fy_generic fy_generic_indirect_get_tag(fy_generic v)

Get the tag from an indirect.

Parameters:

Return

The tag as a string struct fy_generic, or fy_null if FYGIF_TAG is not set.

fy_generic_indirect_get_diag

fy_generic fy_generic_indirect_get_diag(fy_generic v)

Get the diagnostics from an indirect.

Parameters:

Return

The diagnostics as a struct fy_generic, or fy_null if FYGIF_DIAG is not set.

fy_generic_indirect_get_marker

fy_generic fy_generic_indirect_get_marker(fy_generic v)

Get the source-position marker from an indirect.

Parameters:

Return

The marker as a struct fy_generic, or fy_null if FYGIF_MARKER is not set.

fy_generic_indirect_get_style

fy_generic fy_generic_indirect_get_style(fy_generic v)

Get the source style from an indirect.

Parameters:

Return

The style as a struct fy_generic, or fy_null if FYGIF_STYLE is not set.

fy_generic_indirect_get_comment

fy_generic fy_generic_indirect_get_comment(fy_generic v)

Get the attached comment from an indirect.

Parameters:

Return

The comment as a struct fy_generic, or fy_null if FYGIF_COMMENT is not set.

fy_generic_get_anchor

fy_generic fy_generic_get_anchor(fy_generic v)

Get the anchor from any generic value.

Parameters:

Description

Handles both direct and indirect values; for direct values there is no anchor, so fy_null is returned.

Return

The anchor string struct fy_generic, or fy_null if none.

fy_generic_get_tag

fy_generic fy_generic_get_tag(fy_generic v)

Get the tag from any generic value.

Parameters:

Return

The tag string struct fy_generic, or fy_null if none.

fy_generic_get_diag

fy_generic fy_generic_get_diag(fy_generic v)

Get the diagnostics from any generic value.

Parameters:

Return

The diagnostics struct fy_generic, or fy_null if none.

fy_generic_get_marker

fy_generic fy_generic_get_marker(fy_generic v)

Get the source-position marker from any generic value.

Parameters:

Return

The marker struct fy_generic, or fy_null if none.

fy_generic_get_style

fy_generic fy_generic_get_style(fy_generic v)

Get the source style from any generic value.

Parameters:

Return

The style struct fy_generic, or fy_null if none.

fy_generic_get_comment

fy_generic fy_generic_get_comment(fy_generic v)

Get the attached comment from any generic value.

Parameters:

Return

The comment struct fy_generic, or fy_null if none.

fy_generic_get_type

enum fy_generic_type fy_generic_get_type(fy_generic v)

Get the type of any generic value.

Parameters:

  • v (fy_generic) – Any generic value (direct or indirect).

Description

Dispatches to the indirect or direct type accessor as appropriate. This is the preferred single entry-point for type queries.

Return

The enum fy_generic_type of v.

typedef fy_generic_map_pair

type fy_generic_map_pair

A key/value pair within a generic mapping.

Description

The union allows access either as named key / value fields or as a two-element items array (index 0 = key, index 1 = value). Do not change the layout — code iterates mappings as flat item arrays.

typedef fy_generic_sized_string

type fy_generic_sized_string

A string with an explicit byte count.

Description

Used when passing strings that may contain embedded NUL bytes or when avoiding a strlen() call. The data pointer and size byte count need not be NUL-terminated.

typedef fy_generic_decorated_int

type fy_generic_decorated_int

An integer paired with encoding flags.

Description

Wraps a 64-bit integer value with a flags word (%FYGDIF_*) that controls how the integer is encoded (e.g. whether it should be treated as unsigned even when the value fits in the signed range). Access the value as sv (signed) or uv (unsigned). The value union must be first for correct ABI — do not reorder.

fy_sequence_storage_size

size_t fy_sequence_storage_size(const size_t count)

Compute bytes needed for a sequence of count items.

Parameters:

  • count (const size_t) – Number of items.

Description

Computes the total allocation size for a struct fy_generic_sequence header plus count struct fy_generic items, checking for overflow.

Return

The required byte count, or SIZE_MAX on integer overflow.

fy_mapping_storage_size

size_t fy_mapping_storage_size(const size_t count)

Compute bytes needed for a mapping of count pairs.

Parameters:

  • count (const size_t) – Number of key/value pairs.

Description

Computes the total allocation size for a struct fy_generic_mapping header plus count struct fy_generic_map_pair entries, checking for overflow.

Return

The required byte count, or SIZE_MAX on integer overflow.

fy_collection_storage_size

size_t fy_collection_storage_size(bool is_map, const size_t count)

Compute bytes for a sequence or mapping.

Parameters:

  • is_map (bool) – true for a mapping, false for a sequence.

  • count (const size_t) – Number of items (pairs for mappings).

Description

Dispatches to fy_sequence_storage_size() or fy_mapping_storage_size() depending on is_map.

Return

The required byte count, or SIZE_MAX on integer overflow.

macro fy_generic_typeof

fy_generic_typeof(_v)

Yield the canonical C type for a generic-compatible expression.

Parameters:

  • _v – An expression whose type is to be normalised.

Description

Uses C11 _Generic to map _v to its canonical type: char* and const char* pass through unchanged, fy_generic_builder* passes through, and everything else yields the type of _v itself. Used internally to normalise argument types before encoding them as fy_generic values.

Return

An expression of the canonical type (for use with __typeof__).

fy_generic_is_valid

bool fy_generic_is_valid(const fy_generic v)

Test whether any generic value is not invalid.

Parameters:

Description

Handles both direct and indirect values. For an indirect, the wrapped value is checked.

Return

true if v (or its wrapped value for indirects) is not fy_invalid.

fy_generic_is_invalid

bool fy_generic_is_invalid(const fy_generic v)

Test whether any generic value is invalid.

Parameters:

Description

Handles both direct and indirect values. For an indirect, the wrapped value is checked.

Return

true if v (or its wrapped value for indirects) equals fy_invalid.

macro FY_GENERIC_IS_TEMPLATE_INLINE

FY_GENERIC_IS_TEMPLATE_INLINE(_gtype)

Generate inline type-check functions for a generic type.

Parameters:

  • _gtype – Type suffix (e.g. null_type, bool_type, int_type, string, sequence, …).

Description

Instantiates three functions for the type suffix _gtype:

  • fy_generic_is_indirect_##_gtype##_nocheck(): checks the type of an indirect’s wrapped value without validating that the indirect flag is set.

  • fy_generic_is_indirect_##_gtype(): safe version with validation.

  • fy_generic_is_##_gtype(): inline dispatcher handling both direct and indirect values.

macro FY_GENERIC_IS_TEMPLATE_NON_INLINE

FY_GENERIC_IS_TEMPLATE_NON_INLINE(_gtype)

Generate out-of-line type-check function bodies.

Parameters:

Description

Companion to FY_GENERIC_IS_TEMPLATE_INLINE() used in .c files to emit the actual function bodies for fy_generic_is_indirect_##_gtype##_nocheck() and fy_generic_is_indirect_##_gtype().

fy_generic_is_direct_null_type

bool fy_generic_is_direct_null_type(const fy_generic v)

Test whether a direct generic is null.

Parameters:

  • v (const fy_generic) – A direct generic value.

Return

true if v is the null escape constant.

fy_generic_is_direct_bool_type

bool fy_generic_is_direct_bool_type(const fy_generic v)

Test whether a direct generic is a boolean.

Parameters:

  • v (const fy_generic) – A direct generic value.

Return

true if v is fy_true or fy_false.

fy_generic_is_direct_int_type

bool fy_generic_is_direct_int_type(const fy_generic v)

Test whether a direct generic is a signed integer.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

Checks for both inplace (%FY_INT_INPLACE_V) and out-of-place (%FY_INT_OUTPLACE_V) integer tag values using an unsigned range trick.

Return

true if v holds an integer (signed or unsigned).

fy_generic_is_direct_uint_type

bool fy_generic_is_direct_uint_type(const fy_generic v)

Test whether a direct generic is an unsigned integer.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

Signed and unsigned integers share the same tag bits; this is an alias for fy_generic_is_direct_int_type().

Return

true if v holds an integer value.

fy_generic_is_direct_float_type

bool fy_generic_is_direct_float_type(const fy_generic v)

Test whether a direct generic is a float.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

Checks for both inplace (%FY_FLOAT_INPLACE_V, 64-bit only) and out-of-place (%FY_FLOAT_OUTPLACE_V) float tag values.

Return

true if v holds a floating-point value.

fy_generic_is_direct_string

bool fy_generic_is_direct_string(const fy_generic v)

Test whether a direct generic is a string.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

Checks for both inplace (%FY_STRING_INPLACE_V) and out-of-place (%FY_STRING_OUTPLACE_V) string tag values.

Return

true if v holds a string value.

fy_generic_is_direct_string_type

bool fy_generic_is_direct_string_type(const fy_generic v)

Alias for fy_generic_is_direct_string().

Parameters:

  • v (const fy_generic) – A direct generic value.

Return

true if v holds a string value.

fy_generic_is_direct_sequence

bool fy_generic_is_direct_sequence(const fy_generic v)

Test whether a direct generic is a sequence.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

A direct sequence has the low 4 bits all zero (pointer or empty sentinel).

Return

true if v is a sequence (possibly empty).

fy_generic_is_direct_sequence_type

bool fy_generic_is_direct_sequence_type(const fy_generic v)

Alias for fy_generic_is_direct_sequence().

Parameters:

  • v (const fy_generic) – A direct generic value.

Return

true if v is a sequence.

fy_generic_is_direct_mapping

bool fy_generic_is_direct_mapping(const fy_generic v)

Test whether a direct generic is a mapping.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

A direct mapping has bit 3 set and the low 3 bits zero (low 4 bits == 8).

Return

true if v is a mapping (possibly empty).

fy_generic_is_direct_mapping_type

bool fy_generic_is_direct_mapping_type(const fy_generic v)

Alias for fy_generic_is_direct_mapping().

Parameters:

  • v (const fy_generic) – A direct generic value.

Return

true if v is a mapping.

fy_generic_is_direct_collection

bool fy_generic_is_direct_collection(const fy_generic v)

Test whether a direct generic is a sequence or mapping.

Parameters:

  • v (const fy_generic) – A direct generic value.

Description

Both sequences and mappings have the low 3 bits of the type tag equal to zero.

Return

true if v is either a sequence or a mapping.

fy_generic_collectionp_get_items

const fy_generic *fy_generic_collectionp_get_items(const enum fy_generic_type type, const fy_generic_collection *colp, size_t *countp)

Get the items array from a collection pointer.

Parameters:

Description

Returns the flat item array of a sequence or mapping storage block. For mappings the returned array interleaves keys and values, so countp receives colp->count * 2.

Return

Pointer to the first item, or NULL if colp is NULL or the collection is empty.

fy_generic_get_direct_collection

const fy_generic_collection *fy_generic_get_direct_collection(fy_generic v, enum fy_generic_type *typep)

Resolve a direct collection generic to its storage.

Parameters:

  • v (fy_generic) – A direct generic value.

  • typep (enum fy_generic_type*) – Receives FYGT_SEQUENCE, FYGT_MAPPING, or FYGT_INVALID if not a collection.

Description

Checks that v is a direct sequence or mapping, identifies its type, and returns a pointer to its struct fy_generic_collection storage.

Return

Pointer to the collection storage, or NULL if v is not a direct collection.

fy_generic_is_direct_alias

bool fy_generic_is_direct_alias(const fy_generic v)

Test whether a direct generic is an alias.

Parameters:

  • v (const fy_generic) – A direct generic value.

Return

true if v has type FYGT_ALIAS.

fy_generic_get_null_type_no_check

void *fy_generic_get_null_type_no_check(fy_generic v)

Decode a null generic (always returns NULL).

Parameters:

  • v (fy_generic) – A generic value known to be null.

Return

Always NULL.

fy_generic_in_place_null_type

fy_generic_value fy_generic_in_place_null_type(void *p)

Encode a null pointer as an inplace null generic.

Parameters:

  • p (void*) – Must be NULL; any non-NULL pointer yields fy_invalid_value.

Return

fy_null_value if p is NULL, fy_invalid_value otherwise.

fy_generic_out_of_place_size_null_type

size_t fy_generic_out_of_place_size_null_type(void *v)

Out-of-place allocation size for null (always 0).

Parameters:

  • v (void*) – Ignored.

Return

0 — nulls are always stored inplace.

fy_generic_out_of_place_put_null_type

fy_generic_value fy_generic_out_of_place_put_null_type(void *buf, void *v)

Encode null into an out-of-place buffer.

Parameters:

  • buf (void*) – Ignored (null has no out-of-place representation).

  • v (void*) – Ignored.

Return

fy_null_value.

fy_generic_get_bool_type_no_check

bool fy_generic_get_bool_type_no_check(fy_generic v)

Decode a boolean generic.

Parameters:

  • v (fy_generic) – A generic value known to be a boolean.

Return

true if v equals fy_true_value; false for fy_false_value.

fy_generic_in_place_bool_type

fy_generic_value fy_generic_in_place_bool_type(_Bool v)

Encode a boolean as an inplace generic.

Parameters:

  • v (_Bool) – The boolean value to encode.

Return

fy_true_value or fy_false_value.

fy_generic_out_of_place_size_bool_type

size_t fy_generic_out_of_place_size_bool_type(bool v)

Out-of-place allocation size for a boolean (0).

Parameters:

  • v (bool) – Ignored.

Return

0 — booleans are always stored inplace.

fy_generic_out_of_place_put_bool_type

fy_generic_value fy_generic_out_of_place_put_bool_type(void *buf, bool v)

Encode a boolean into an out-of-place buffer.

Parameters:

  • buf (void*) – Ignored.

  • v (bool) – The boolean value.

Return

fy_true_value or fy_false_value.

fy_generic_in_place_int_type

fy_generic_value fy_generic_in_place_int_type(const long long v)

Try to encode a signed integer inplace.

Parameters:

  • v (const long long) – The signed 64-bit integer to encode.

Description

Stores the value in the upper bits of the word if it fits within the inplace range [%FYGT_INT_INPLACE_MIN, FYGT_INT_INPLACE_MAX].

Return

The encoded struct fy_generic_value, or fy_invalid_value if v is out of range.

fy_generic_out_of_place_put_int_type

fy_generic_value fy_generic_out_of_place_put_int_type(void *buf, const long long v)

Encode a signed integer into an out-of-place buffer.

Parameters:

  • buf (void*) – Caller-allocated, suitably aligned buffer of at least sizeof(fy_generic_decorated_int).

  • v (const long long) – The signed 64-bit integer value.

Description

Writes the value into a struct fy_generic_decorated_int at buf (which must be aligned to FY_INPLACE_TYPE_MASK + 1 bytes) and returns a tagged pointer.

Return

A struct fy_generic_value with FY_INT_OUTPLACE_V tag and buf as the pointer.

fy_generic_in_place_uint_type

fy_generic_value fy_generic_in_place_uint_type(const unsigned long long v)

Try to encode an unsigned integer inplace.

Parameters:

  • v (const unsigned long long) – The unsigned 64-bit integer to encode.

Description

Stores the value inplace if it fits within FYGT_INT_INPLACE_MAX (unsigned values sharing the inplace range with signed integers).

Return

The encoded struct fy_generic_value, or fy_invalid_value if v exceeds the range.

fy_generic_out_of_place_put_uint_type

fy_generic_value fy_generic_out_of_place_put_uint_type(void *buf, const unsigned long long v)

Encode an unsigned integer into an out-of-place buffer.

Parameters:

  • buf (void*) – Caller-allocated, suitably aligned buffer.

  • v (const unsigned long long) – The unsigned 64-bit integer value.

Description

Writes the value into a struct fy_generic_decorated_int and sets FYGDIF_UNSIGNED_RANGE_EXTEND if the value exceeds LLONG_MAX.

Return

A struct fy_generic_value with FY_INT_OUTPLACE_V tag and buf as the pointer.

fy_generic_in_place_float_type

fy_generic_value fy_generic_in_place_float_type(const double v)

Try to encode a double as an inplace float (64-bit).

Parameters:

  • v (const double) – The double value to encode.

Description

On 64-bit platforms, stores the value as a 32-bit float in the upper half of the word if the value is representable without precision loss (denormals, infinities, NaN, and exact float32 values qualify). On 32-bit platforms always returns fy_invalid_value (no inplace floats).

Return

The inplace-encoded struct fy_generic_value, or fy_invalid_value if v cannot be stored inplace.

fy_generic_out_of_place_put_float_type

fy_generic_value fy_generic_out_of_place_put_float_type(void *buf, const double v)

Encode a double into an out-of-place buffer.

Parameters:

  • buf (void*) – Caller-allocated, suitably aligned buffer of at least sizeof(double).

  • v (const double) – The double value to store.

Description

Writes the double at buf (which must be suitably aligned) and returns a tagged pointer with FY_FLOAT_OUTPLACE_V.

Return

A struct fy_generic_value with FY_FLOAT_OUTPLACE_V tag and buf as the pointer.

fy_generic_get_int_type_no_check

long long fy_generic_get_int_type_no_check(fy_generic v)

Decode a signed integer generic.

Parameters:

  • v (fy_generic) – A generic value known to be an integer.

Description

Handles both inplace (sign-extends the packed value) and out-of-place (dereferences the pointer) representations.

Return

The decoded signed 64-bit integer, or 0 if the pointer resolves to NULL.

fy_generic_out_of_place_size_int_type

size_t fy_generic_out_of_place_size_int_type(const long long v)

Out-of-place allocation size for a signed integer.

Parameters:

  • v (const long long) – The integer value to be encoded.

Return

0 if v fits inplace, sizeof(fy_generic_decorated_int) otherwise.

fy_generic_get_uint_type_no_check

unsigned long long fy_generic_get_uint_type_no_check(fy_generic v)

Decode an unsigned integer generic.

Parameters:

  • v (fy_generic) – A generic value known to be an integer.

Description

Handles both inplace (zero-extends the packed value) and out-of-place representations.

Return

The decoded unsigned 64-bit integer, or 0 if the pointer resolves to NULL.

fy_generic_out_of_place_size_uint_type

size_t fy_generic_out_of_place_size_uint_type(const unsigned long long v)

Out-of-place allocation size for an unsigned integer.

Parameters:

  • v (const unsigned long long) – The unsigned integer value to be encoded.

Return

0 if v fits inplace, sizeof(fy_generic_decorated_int) otherwise.

fy_generic_get_float_type_no_check

double fy_generic_get_float_type_no_check(fy_generic v)

Decode a float generic (64-bit).

Parameters:

  • v (fy_generic) – A generic value known to be a float.

Description

Handles inplace 32-bit floats (widened to double) and out-of-place doubles.

Return

The decoded double value, or 0.0 if the out-of-place pointer is NULL.

fy_generic_out_of_place_size_float_type

size_t fy_generic_out_of_place_size_float_type(const double v)

Out-of-place allocation size for a float (64-bit).

Parameters:

  • v (const double) – The double value to be encoded.

Return

0 if v can be stored inplace (as float32 without loss), sizeof(double) otherwise.

fy_generic_out_of_place_size_double

size_t fy_generic_out_of_place_size_double(const double v)

Out-of-place allocation size for a double (32-bit).

Parameters:

  • v (const double) – Ignored.

Description

On 32-bit platforms all floats are stored out-of-place as doubles.

Return

sizeof(double).

fy_generic_sequence_resolve_outofplace

const fy_generic_sequence *fy_generic_sequence_resolve_outofplace(fy_generic seq)

Resolve a non-direct sequence to its storage.

Parameters:

Description

Called when the sequence is indirect (wrapped) or otherwise not directly addressable. Do not call directly; use fy_generic_sequence_resolve() instead.

Return

Pointer to the struct fy_generic_sequence storage, or NULL on error.

fy_generic_sequence_resolve

const fy_generic_sequence *fy_generic_sequence_resolve(const fy_generic seq)

Resolve any sequence generic to its storage pointer.

Parameters:

  • seq (const fy_generic) – A sequence generic value.

Description

Handles both direct (pointer embedded in the word) and indirect sequences.

Return

Pointer to the struct fy_generic_sequence storage, or NULL for an empty/invalid sequence.

fy_generic_sequence_to_handle

fy_generic_sequence_handle fy_generic_sequence_to_handle(const fy_generic seq)

Convert a sequence generic to an opaque handle.

Parameters:

  • seq (const fy_generic) – A sequence generic value.

Return

A struct fy_generic_sequence_handle pointing to the sequence storage.

fy_generic_sequencep_items

const fy_generic *fy_generic_sequencep_items(const fy_generic_sequence *seqp)

Get the items array from a sequence pointer.

Parameters:

Return

Pointer to the first item, or NULL if seqp is NULL.

fy_generic_sequencep_get_item_count

size_t fy_generic_sequencep_get_item_count(const fy_generic_sequence *seqp)

Get the item count from a sequence pointer.

Parameters:

Return

The number of items, or 0 if seqp is NULL.

fy_generic_sequence_get_item_count

size_t fy_generic_sequence_get_item_count(fy_generic seq)

Get the number of items in a sequence.

Parameters:

Return

The number of items in the sequence, or 0 if empty or invalid.

fy_generic_sequence_get_items

const fy_generic *fy_generic_sequence_get_items(fy_generic seq, size_t *countp)

Get the items array and count from a sequence.

Parameters:

  • seq (fy_generic) – A sequence generic value.

  • countp (size_t*) – Receives the number of items.

Return

Pointer to the first item, or NULL if the sequence is empty or invalid.

fy_generic_sequencep_get_itemp

const fy_generic *fy_generic_sequencep_get_itemp(const fy_generic_sequence *seqp, const size_t idx)

Get a pointer to a specific item in a sequence pointer.

Parameters:

Return

Pointer to the item at idx, or NULL if out of range or seqp is NULL.

fy_generic_sequence_get_itemp

const fy_generic *fy_generic_sequence_get_itemp(fy_generic seq, const size_t idx)

Get a pointer to a specific item in a sequence.

Parameters:

  • seq (fy_generic) – A sequence generic value.

  • idx (const size_t) – Zero-based item index.

Return

Pointer to the item at idx, or NULL if out of range or the sequence is invalid.

fy_generic_sequence_get_item_generic

fy_generic fy_generic_sequence_get_item_generic(fy_generic seq, const size_t idx)

Get a specific item from a sequence as a value.

Parameters:

  • seq (fy_generic) – A sequence generic value.

  • idx (const size_t) – Zero-based item index.

Return

The item at idx, or fy_invalid if out of range or the sequence is invalid.

fy_generic_mapping_resolve_outofplace

const fy_generic_mapping *fy_generic_mapping_resolve_outofplace(fy_generic map)

Resolve a non-direct mapping to its storage.

Parameters:

Description

Called when the mapping is indirect (wrapped) or otherwise not directly addressable. Do not call directly; use fy_generic_mapping_resolve() instead.

Return

Pointer to the struct fy_generic_mapping storage, or NULL on error.

fy_generic_mapping_resolve

const fy_generic_mapping *fy_generic_mapping_resolve(const fy_generic map)

Resolve any mapping generic to its storage pointer.

Parameters:

  • map (const fy_generic) – A mapping generic value.

Description

Handles both direct (pointer embedded in the word) and indirect mappings.

Return

Pointer to the struct fy_generic_mapping storage, or NULL for an empty/invalid mapping.

fy_generic_mapping_to_handle

fy_generic_mapping_handle fy_generic_mapping_to_handle(const fy_generic map)

Convert a mapping generic to an opaque handle.

Parameters:

  • map (const fy_generic) – A mapping generic value.

Return

A struct fy_generic_mapping_handle pointing to the mapping storage.

fy_generic_mappingp_items

const fy_generic *fy_generic_mappingp_items(const fy_generic_mapping *mapp)

Get the flat interleaved items array from a mapping pointer.

Parameters:

Description

Returns the pairs storage as a flat array of struct fy_generic values where even indices are keys and odd indices are values.

Return

Pointer to the first key, or NULL if mapp is NULL.

fy_generic_mappingp_get_pair_count

size_t fy_generic_mappingp_get_pair_count(const fy_generic_mapping *mapp)

Get the number of key/value pairs from a mapping pointer.

Parameters:

Return

The number of pairs, or 0 if mapp is NULL.

fy_generic_mapping_get_pairs

const fy_generic_map_pair *fy_generic_mapping_get_pairs(fy_generic map, size_t *countp)

Get the pairs array and pair count from a mapping.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • countp (size_t*) – Receives the number of key/value pairs.

Return

Pointer to the first struct fy_generic_map_pair, or NULL if the mapping is empty or invalid.

fy_generic_mapping_get_items

const fy_generic *fy_generic_mapping_get_items(fy_generic map, size_t *item_countp)

Get the flat interleaved items array and count from a mapping.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • item_countp (size_t*) – Receives the total number of items (2 x pair count).

Description

Returns the entire pair storage as a flat array of struct fy_generic values (even = keys, odd = values). item_countp receives 2 * pair_count.

Return

Pointer to the first item, or NULL if the mapping is empty or invalid.

fy_generic_compare_out_of_place

int fy_generic_compare_out_of_place(fy_generic a, fy_generic b)

Compare two generics that are not word-equal.

Parameters:

Description

Handles out-of-place values (e.g. large integers, strings, collections) that require dereferencing to compare. Not intended for direct use; call fy_generic_compare() instead.

Return

0 if equal, negative if a < b, positive if a > b, -2 if either is invalid.

fy_generic_compare

int fy_generic_compare(fy_generic a, fy_generic b)

Compare two generic values for equality and ordering.

Parameters:

Description

Fast path: if the raw words are equal the values are equal (covers inplace scalars and identical pointers). Falls back to fy_generic_compare_out_of_place() for out-of-place or complex values.

Return

0 if a == b, negative if a < b, positive if a > b, -2 if either operand is fy_invalid.

fy_generic_mappingp_get_at_keyp

const fy_generic *fy_generic_mappingp_get_at_keyp(const fy_generic_mapping *mapp, const size_t idx)

Get a pointer to a key at a given index (mapping pointer).

Parameters:

Return

Pointer to the key at idx, or NULL if out of range or mapp is NULL.

fy_generic_mapping_get_at_keyp

const fy_generic *fy_generic_mapping_get_at_keyp(fy_generic map, const size_t idx)

Get a pointer to a key at a given index.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • idx (const size_t) – Zero-based pair index.

Return

Pointer to the key at idx, or NULL if out of range or the mapping is invalid.

fy_generic_mappingp_get_at_key

fy_generic fy_generic_mappingp_get_at_key(const fy_generic_mapping *mapp, const size_t idx)

Get a key at a given index as a value (mapping pointer).

Parameters:

Return

The key at idx, or fy_invalid if out of range or mapp is NULL.

fy_generic_mapping_get_at_key

fy_generic fy_generic_mapping_get_at_key(fy_generic map, const size_t idx)

Get a key at a given index as a value.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • idx (const size_t) – Zero-based pair index.

Return

The key at idx, or fy_invalid if out of range or the mapping is invalid.

fy_generic_mappingp_valuep_index

const fy_generic *fy_generic_mappingp_valuep_index(const fy_generic_mapping *mapp, fy_generic key, size_t *idxp)

Look up a value by key in a mapping pointer.

Parameters:

Description

Linear search by key equality. If found, sets *@idxp to the pair index.

Return

Pointer to the value, or NULL if the key was not found or mapp is NULL.

fy_generic_mappingp_get_valuep

const fy_generic *fy_generic_mappingp_get_valuep(const fy_generic_mapping *mapp, fy_generic key)

Look up a value by key in a mapping pointer.

Parameters:

Return

Pointer to the value, or NULL if the key was not found.

fy_generic_mappingp_get_at_valuep

const fy_generic *fy_generic_mappingp_get_at_valuep(const fy_generic_mapping *mapp, const size_t idx)

Get a pointer to a value at a given index (mapping pointer).

Parameters:

Return

Pointer to the value at idx, or NULL if out of range or mapp is NULL.

fy_generic_mapping_get_valuep_index

const fy_generic *fy_generic_mapping_get_valuep_index(fy_generic map, fy_generic key, size_t *idxp)

Look up a value by key, returning its index.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • key (fy_generic) – The key to search for.

  • idxp (size_t*) – Receives the found pair index, or (size_t)-1 if not found (may be NULL).

Return

Pointer to the value, or NULL if not found.

fy_generic_mapping_get_valuep

const fy_generic *fy_generic_mapping_get_valuep(fy_generic map, fy_generic key)

Look up a value by key in a mapping.

Parameters:

Return

Pointer to the value, or NULL if the key was not found.

fy_generic_mapping_get_at_valuep

const fy_generic *fy_generic_mapping_get_at_valuep(fy_generic map, const size_t idx)

Get a pointer to a value at a given index.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • idx (const size_t) – Zero-based pair index.

Return

Pointer to the value at idx, or NULL if out of range or the mapping is invalid.

fy_generic_mapping_get_value_index

fy_generic fy_generic_mapping_get_value_index(fy_generic map, fy_generic key, size_t *idxp)

Look up a value by key, returning it and its index.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • key (fy_generic) – The key to search for.

  • idxp (size_t*) – Receives the found pair index, or (size_t)-1 if not found (may be NULL).

Return

The value, or fy_invalid if not found.

fy_generic_mapping_get_value

fy_generic fy_generic_mapping_get_value(fy_generic map, fy_generic key)

Look up a value by key in a mapping.

Parameters:

Return

The value, or fy_invalid if not found.

fy_generic_mappingp_get_at_value

fy_generic fy_generic_mappingp_get_at_value(const fy_generic_mapping *mapp, const size_t idx)

Get a value at a given index as a value (mapping pointer).

Parameters:

Return

The value at idx, or fy_invalid if out of range or mapp is NULL.

fy_generic_mapping_get_at_value

fy_generic fy_generic_mapping_get_at_value(fy_generic map, const size_t idx)

Get a value at a given index as a value.

Parameters:

  • map (fy_generic) – A mapping generic value.

  • idx (const size_t) – Zero-based pair index.

Return

The value at idx, or fy_invalid if out of range or the mapping is invalid.

fy_generic_mapping_get_pair_count

size_t fy_generic_mapping_get_pair_count(fy_generic map)

Get the number of key/value pairs in a mapping.

Parameters:

Return

The number of pairs, or 0 if the mapping is empty or invalid.

fy_generic_collection_get_items

const fy_generic *fy_generic_collection_get_items(fy_generic v, size_t *countp)

Get the raw item array of a sequence or mapping.

Parameters:

  • v (fy_generic) – A sequence or mapping generic value.

  • countp (size_t*) – Receives the number of items (elements for sequences, 2 x pair-count for mappings).

Description

Returns a pointer to the contiguous array of generic items stored in the collection. For a sequence this is the element array; for a mapping it is the interleaved key/value array (pairs x 2 items). Indirect wrappers are transparently resolved.

Return

Pointer to the first item, or NULL if v is not a collection or is invalid.

macro FY_GENERIC_LVAL_TEMPLATE

FY_GENERIC_LVAL_TEMPLATE(_ctype, _gtype, _gttype, _xctype, _xgtype, _xminv, _xmaxv, _default_v)

Generate typed accessor/cast functions for a C scalar type.

Parameters:

  • _ctype – The C type (e.g. int, unsigned long).

  • _gtype – The token name used in generated identifiers (e.g. int, unsigned_long).

  • _gttype – The generic type tag category (INT, UINT, FLOAT, BOOL, NULL).

  • _xctype – The underlying storage C type (long long, unsigned long long, double, etc.).

  • _xgtype – The underlying storage type name (int_type, uint_type, float_type, etc.).

  • _xminv – Minimum representable value for range-checking.

  • _xmaxv – Maximum representable value for range-checking.

  • _default_v – Default value returned when conversion fails.

Description

Generates a family of inline functions for a specific C type that map it onto the underlying integer, unsigned-integer, or floating-point storage class:

  • fy_generic_get_<gtype>_no_check() - extract value, no type check

  • fy_generic_<gtype>_is_in_range_no_check() - range check without type check

  • fy_generic_<gtype>_is_in_range() - full range check

  • fy_generic_is_direct_<gtype>() - direct type predicate

  • fy_generic_is_<gtype>() - type predicate (resolves indirect)

  • fy_generic_in_place_<gtype>() - encode as inplace value

  • fy_generic_out_of_place_size_<gtype>() - out-of-place storage size

  • fy_generic_out_of_place_put_<gtype>() - write out-of-place representation

  • fy_generic_cast_<gtype>_default() - cast generic to C type with default

  • fy_generic_cast_<gtype>() - cast generic to C type

  • fy_genericp_cast_<gtype>_default() - pointer variant with default

  • fy_genericp_cast_<gtype>() - pointer variant

  • fy_generic_sequencep_get_<gtype>_itemp() - typed sequence item pointer

  • fy_generic_sequence_get_<gtype>_itemp() - typed sequence item pointer (handle)

  • fy_generic_sequencep_get_<gtype>_default() - typed sequence item with default

  • fy_generic_sequence_get_<gtype>_default() - typed sequence item (handle)

  • fy_generic_mappingp_get_<gtype>_valuep() - typed mapping value pointer

  • fy_generic_mapping_get_<gtype>_valuep() - typed mapping value pointer (handle)

  • fy_generic_mappingp_get_<gtype>_default() - typed mapping value with default

  • fy_generic_mapping_get_<gtype>_default() - typed mapping value (handle)

  • (and similar _at_ variants for positional access)

macro FY_GENERIC_INT_LVAL_TEMPLATE

FY_GENERIC_INT_LVAL_TEMPLATE(_ctype, _gtype, _xminv, _xmaxv, _defaultv)

Specialise FY_GENERIC_LVAL_TEMPLATE for signed integer types.

Parameters:

  • _ctype – The C type (e.g. int, short).

  • _gtype – Token name (e.g. int, short).

  • _xminv – Minimum value (e.g. INT_MIN).

  • _xmaxv – Maximum value (e.g. INT_MAX).

  • _defaultv – Default value on conversion failure.

Description

Defines fy_<gtype>_is_in_range() as a [_xminv, _xmaxv] check on a long long value and then expands FY_GENERIC_LVAL_TEMPLATE using the int_type storage class.

macro FY_GENERIC_UINT_LVAL_TEMPLATE

FY_GENERIC_UINT_LVAL_TEMPLATE(_ctype, _gtype, _xminv, _xmaxv, _defaultv)

Specialise FY_GENERIC_LVAL_TEMPLATE for unsigned integer types.

Parameters:

  • _ctype – The C type (e.g. unsigned int, unsigned long).

  • _gtype – Token name (e.g. unsigned_int, unsigned_long).

  • _xminv – Minimum value (always 0 for unsigned types).

  • _xmaxv – Maximum value (e.g. UINT_MAX).

  • _defaultv – Default value on conversion failure.

Description

Defines fy_<gtype>_is_in_range() as a [0, _xmaxv] check on an unsigned long long value and then expands FY_GENERIC_LVAL_TEMPLATE using the uint_type storage class.

macro FY_GENERIC_FLOAT_LVAL_TEMPLATE

FY_GENERIC_FLOAT_LVAL_TEMPLATE(_ctype, _gtype, _xminv, _xmaxv, _defaultv)

Specialise FY_GENERIC_LVAL_TEMPLATE for floating-point types.

Parameters:

  • _ctype – The C type (float or double).

  • _gtype – Token name (float or double).

  • _xminv – Minimum normal value (e.g. -FLT_MAX).

  • _xmaxv – Maximum normal value (e.g. FLT_MAX).

  • _defaultv – Default value on conversion failure.

Description

Defines fy_<gtype>_is_in_range() accepting any non-normal value (NaN, inf, subnormal) and normal values within [_xminv, _xmaxv], then expands FY_GENERIC_LVAL_TEMPLATE using the float_type storage class.

fy_generic_get_string_inplace_size

size_t fy_generic_get_string_inplace_size(const fy_generic v)

Extract the length of an inplace string.

Parameters:

  • v (const fy_generic) – A generic value with tag FY_STRING_INPLACE_V. Behaviour is undefined otherwise.

Return

Length of the inplace string in bytes (0–7 on 64-bit, 0–3 on 32-bit).

fy_genericp_get_string_inplace

const char *fy_genericp_get_string_inplace(const fy_generic *vp)

Return a pointer to the inplace string bytes.

Parameters:

  • vp (const fy_generic*) – Pointer to a generic with tag FY_STRING_INPLACE_V.

Description

The returned pointer is into the storage of vp itself. The caller must ensure vp lives at least as long as the returned pointer is used.

Return

Pointer to the first character of the inplace string (not NUL-terminated).

fy_genericp_get_string_size_no_check

const char *fy_genericp_get_string_size_no_check(const fy_generic *vp, size_t *lenp)

Get string pointer and length without type check.

Parameters:

  • vp (const fy_generic*) – Pointer to a generic known to hold a string (inplace or outplace).

  • lenp (size_t*) – Receives the length of the string in bytes.

Description

Returns the string data and length for both inplace and out-of-place strings, without verifying that vp actually holds a string.

Return

Pointer to the NUL-terminated string data.

fy_genericp_get_string_no_check

const char *fy_genericp_get_string_no_check(const fy_generic *vp)

Get string pointer without type check or length.

Parameters:

  • vp (const fy_generic*) – Pointer to a generic known to hold a string (inplace or outplace).

Return

Pointer to the NUL-terminated string data.

macro fy_genericp_get_string_size

fy_genericp_get_string_size(_vp, _lenp)

Get string pointer and length from a generic pointer.

Parameters:

  • _vp – Pointer to a generic value (may be indirect). May be NULL.

  • _lenp – Receives the string length. Set to 0 on failure.

Description

Handles all string variants (inplace, outplace, indirect). When the underlying value is an inplace string a temporary aligned copy is alloca’d so that a stable pointer can be returned.

Return

Pointer to the NUL-terminated string, or NULL on error / non-string.

macro fy_genericp_get_string_default

fy_genericp_get_string_default(_vp, _default_v)

Get string pointer from a generic pointer, with a default.

Parameters:

  • _vp – Pointer to a generic value. May be NULL.

  • _default_v – Returned when _vp is NULL or not a string.

Return

The string pointer, or _default_v on failure.

macro fy_generic_get_string_size_alloca

fy_generic_get_string_size_alloca(_v, _lenp)

Get string pointer and length from a generic value.

Parameters:

  • _v – A generic value (may be indirect).

  • _lenp – Receives the string length. Set to 0 on failure.

Description

Like fy_genericp_get_string_size() but takes a value directly. For inplace strings an aligned alloca copy is made so the returned pointer remains valid for the calling stack frame.

Return

Pointer to the NUL-terminated string, or NULL on error / non-string.

macro fy_generic_get_string_default_alloca

fy_generic_get_string_default_alloca(_v, _default_v)

Get string from a generic value with a default.

Parameters:

  • _v – A generic value.

  • _default_v – Returned when _v is not a string.

Return

The string pointer, or _default_v on failure.

fy_genericp_get_const_char_ptr_default

const char *fy_genericp_get_const_char_ptr_default(const fy_generic *vp, const char *default_value)

Get a const char pointer from a generic pointer.

Parameters:

  • vp (const fy_generic*) – Pointer to a generic value (indirect is resolved). May be NULL.

  • default_value (const char*) – Returned when vp is NULL or not an out-of-place string.

Description

Only works for out-of-place strings (heap-allocated). Inplace strings cannot be returned as a stable pointer; use fy_genericp_get_string_size() for those.

Return

Pointer to the NUL-terminated string, or default_value on failure.

fy_genericp_get_const_char_ptr

const char *fy_genericp_get_const_char_ptr(const fy_generic *vp)

Get a const char pointer from a generic pointer.

Parameters:

  • vp (const fy_generic*) – Pointer to a generic value.

Description

Returns “” when vp is NULL or not an out-of-place string.

Return

Pointer to the string, or “” on failure.

fy_genericp_get_char_ptr_default

char *fy_genericp_get_char_ptr_default(fy_generic *vp, const char *default_value)

Get a mutable char pointer from a generic pointer.

Parameters:

  • vp (fy_generic*) – Pointer to a generic value.

  • default_value (const char*) – Returned on failure.

Description

Same as fy_genericp_get_const_char_ptr_default() but returns a non-const pointer.

Return

Mutable pointer to the string, or default_value on failure.

fy_genericp_get_char_ptr

char *fy_genericp_get_char_ptr(fy_generic *vp)

Get a mutable char pointer from a generic pointer.

Parameters:

  • vp (fy_generic*) – Pointer to a generic value.

Description

Returns “” when vp is NULL or not an out-of-place string.

Return

Mutable pointer to the string, or “” on failure.

macro fy_generic_get_alias_alloca

fy_generic_get_alias_alloca(_v)

Get the anchor name string from an alias generic.

Parameters:

  • _v – An alias generic value.

Description

Extracts the anchor (string) from an alias value using alloca for inplace storage.

Return

Pointer to the NUL-terminated anchor name, or “” if _v is not an alias.

macro fy_bool

fy_bool(_v)

Create a bool generic from a C boolean expression.

Parameters:

  • _v – Boolean expression.

Return

fy_true if _v is non-zero, fy_false otherwise.

macro fy_int_is_unsigned

fy_int_is_unsigned(_v)

Detect whether an integer constant exceeds LLONG_MAX.

Parameters:

  • _v – An integer expression.

Description

Uses _Generic to check at compile time whether an unsigned long long value is above LLONG_MAX, which indicates it requires unsigned representation.

Return

true if _v is an unsigned long long greater than LLONG_MAX, false otherwise.

macro fy_int_alloca

fy_int_alloca(_v)

Create an integer generic using alloca for out-of-place values.

Parameters:

  • _v – Any integer expression.

Description

Encodes _v inplace when it fits in FYGT_INT_INPLACE_BITS; otherwise allocates a fy_generic_decorated_int on the stack. The result is valid only for the duration of the current stack frame.

Return

A fy_generic_value encoding _v.

macro fy_int

fy_int(_v)

Create an integer generic from any integer expression.

Parameters:

  • _v – An integer expression of any width.

Description

Selects the most efficient encoding at compile time: inplace for small constants, static storage for large constants, or alloca for runtime values.

Return

A fy_generic holding _v.

fy_generic_in_place_char_ptr_len

fy_generic_value fy_generic_in_place_char_ptr_len(const char *p, const size_t len)

Attempt to encode a string inplace.

Parameters:

  • p (const char*) – String data (need not be NUL-terminated).

  • len (const size_t) – Length of p in bytes.

Description

Packs up to 7 bytes (64-bit) or 3 bytes (32-bit) of p directly into the generic word. Returns fy_invalid_value when the string is too long for inplace storage.

Return

Encoded fy_generic_value on success, fy_invalid_value when len is too large.

fy_generic_in_place_char_ptr

fy_generic_value fy_generic_in_place_char_ptr(const char *p)

Attempt to encode a NUL-terminated string inplace.

Parameters:

  • p (const char*) – NUL-terminated string. May be NULL (returns fy_invalid_value).

Return

Encoded fy_generic_value on success, fy_invalid_value when the string is too long.

fy_generic_in_place_const_szstrp

fy_generic_value fy_generic_in_place_const_szstrp(const fy_generic_sized_string *szstrp)

Attempt to encode a sized string inplace.

Parameters:

Return

Encoded fy_generic_value on success, fy_invalid_value when the string is too long.

fy_generic_in_place_szstr

fy_generic_value fy_generic_in_place_szstr(const fy_generic_sized_string szstr)

Attempt to encode a sized string value inplace.

Parameters:

Return

Encoded fy_generic_value, or fy_invalid_value when too long.

fy_generic_in_place_const_dintp

fy_generic_value fy_generic_in_place_const_dintp(const fy_generic_decorated_int *dintp)

Attempt to encode a decorated int inplace.

Parameters:

Description

Delegates to fy_generic_in_place_int_type() or fy_generic_in_place_uint_type() depending on the FYGDIF_UNSIGNED_RANGE_EXTEND flag.

Return

Encoded fy_generic_value, or fy_invalid_value when too large for inplace.

fy_generic_in_place_dint

fy_generic_value fy_generic_in_place_dint(const fy_generic_decorated_int dint)

Attempt to encode a decorated int by value inplace.

Parameters:

Return

Encoded fy_generic_value, or fy_invalid_value when too large for inplace.

fy_generic_in_place_sequence_handle

fy_generic_value fy_generic_in_place_sequence_handle(fy_generic_sequence_handle seqh)

Encode a sequence handle as a generic value.

Parameters:

  • seqh (fy_generic_sequence_handle) – A sequence handle.

Description

A NULL handle encodes as fy_seq_empty. The handle pointer must be aligned to FY_GENERIC_CONTAINER_ALIGN; misaligned pointers return fy_invalid_value.

Return

Encoded fy_generic_value, fy_seq_empty_value for NULL, or fy_invalid_value on misalignment.

fy_generic_in_place_mapping_handle

fy_generic_value fy_generic_in_place_mapping_handle(fy_generic_mapping_handle maph)

Encode a mapping handle as a generic value.

Parameters:

  • maph (fy_generic_mapping_handle) – A mapping handle.

Description

A NULL handle encodes as fy_map_empty. The handle pointer must be aligned to FY_GENERIC_CONTAINER_ALIGN; misaligned pointers return fy_invalid_value.

Return

Encoded fy_generic_value, fy_map_empty_value for NULL, or fy_invalid_value on misalignment.

macro fy_to_generic_inplace

fy_to_generic_inplace(_v)

Encode a value as an inplace generic using _Generic dispatch.

Parameters:

  • _v – Value of any supported C type.

Description

Attempts inplace encoding (no allocation) for all supported types. Returns fy_invalid_value when the value does not fit inplace (e.g. strings longer than 7 bytes on 64-bit) and out-of-place encoding must be used instead.

Return

Encoded fy_generic_value, or fy_invalid_value if out-of-place is required.

fy_generic_out_of_place_size_char_ptr

size_t fy_generic_out_of_place_size_char_ptr(const char *p)

Byte count needed for out-of-place storage of a C string.

Parameters:

  • p (const char*) – Null-terminated C string, or NULL.

Description

Returns the number of bytes required to store the length prefix and the null-terminated string data in an out-of-place buffer. Returns 0 for NULL.

Return

Storage size in bytes, or 0 for NULL.

fy_generic_out_of_place_size_const_szstrp

size_t fy_generic_out_of_place_size_const_szstrp(const fy_generic_sized_string *szstrp)

Byte count for out-of-place storage of a sized string pointer.

Parameters:

Return

Storage size in bytes (length prefix + string bytes + NUL), or 0 for NULL.

fy_generic_out_of_place_size_const_dintp

size_t fy_generic_out_of_place_size_const_dintp(const fy_generic_decorated_int *dintp)

Byte count for out-of-place storage of a decorated int pointer.

Parameters:

Description

Dispatches to the signed or unsigned variant depending on FYGDIF_UNSIGNED_RANGE_EXTEND.

Return

Storage size in bytes, or 0 for NULL.

macro fy_to_generic_outofplace_size

fy_to_generic_outofplace_size(_v)

Compute buffer size needed for out-of-place encoding of a value.

Parameters:

  • _v – Value of any supported C type.

Return

Number of bytes required, or 0 if the value can be encoded inplace or is unsupported.

fy_generic_out_of_place_put_char_ptr

fy_generic_value fy_generic_out_of_place_put_char_ptr(void *buf, const char *p)

Write a C string into an out-of-place buffer.

Parameters:

Description

Encodes the length prefix followed by the string bytes and a NUL terminator into buf, which must be aligned to FY_GENERIC_CONTAINER_ALIGN.

Return

Encoded FY_STRING_OUTPLACE_V generic value pointing into buf, or fy_invalid_value for NULL p.

fy_generic_out_of_place_put_const_szstrp

fy_generic_value fy_generic_out_of_place_put_const_szstrp(void *buf, const fy_generic_sized_string *szstrp)

Write a sized string into an out-of-place buffer.

Parameters:

  • buf (void*) – Pre-allocated aligned buffer.

  • szstrp (const fy_generic_sized_string*) – Sized string descriptor (must not be NULL).

Return

Encoded FY_STRING_OUTPLACE_V generic value, or fy_invalid_value for NULL.

fy_generic_out_of_place_put_const_dintp

fy_generic_value fy_generic_out_of_place_put_const_dintp(void *buf, const fy_generic_decorated_int *dintp)

Write a decorated int into an out-of-place buffer.

Parameters:

  • buf (void*) – Pre-allocated aligned buffer.

  • dintp (const fy_generic_decorated_int*) – Decorated int descriptor (must not be NULL).

Description

Dispatches to the signed or unsigned out-of-place encoder based on FYGDIF_UNSIGNED_RANGE_EXTEND.

Return

Encoded generic value, or fy_invalid_value for NULL.

macro fy_to_generic_outofplace_put

fy_to_generic_outofplace_put(_vp, _v)

Write a value into a pre-allocated out-of-place buffer.

Parameters:

  • _vp – Destination buffer pointer.

  • _v – Value to encode.

Description

Uses _Generic dispatch to select the correct encoder for _v. _vp must point to a buffer of at least fy_to_generic_outofplace_size(@_v) bytes, aligned to FY_GENERIC_CONTAINER_ALIGN.

Return

Encoded out-of-place generic value.

macro fy_local_to_generic_value

fy_local_to_generic_value(_v)

Encode any value as a fy_generic_value using alloca for out-of-place storage.

Parameters:

  • _v – Value of any supported C type.

Description

Tries inplace encoding first. If that returns fy_invalid_value and the type requires out-of-place storage, allocates a stack buffer and writes the value there. The resulting value is only valid for the lifetime of the enclosing function (because of alloca).

Return

fy_generic_value suitable for wrapping in a fy_generic struct.

macro fy_local_to_generic

fy_local_to_generic(_v)

Encode any value as a fy_generic using alloca for out-of-place storage.

Parameters:

  • _v – Value of any supported C type.

Description

Wrapper around fy_local_to_generic_value() that returns a full fy_generic struct. The result is only valid within the enclosing function’s scope.

Return

fy_generic value (stack lifetime for out-of-place types).

macro fy_float_alloca

fy_float_alloca(_v)

Encode a double as a generic float value using alloca for out-of-place storage.

Parameters:

  • _v – A double value.

Description

On 64-bit targets, a double that is representable as a 32-bit float is stored inplace in the generic word. Otherwise a stack-allocated double buffer is used.

Return

fy_generic_value encoding _v (stack lifetime for out-of-place case).

macro fy_local_float

fy_local_float(_v)

Construct a fy_generic float value, choosing alloca or static storage.

Parameters:

  • _v – A double (constant or runtime).

Description

Uses fy_float_const() when _v is a compile-time constant; otherwise falls back to fy_float_alloca().

Return

fy_generic wrapping the encoded float.

macro fy_float

fy_float(_v)

High-level float generic constructor.

Parameters:

  • _v – A double value.

Description

Convenience wrapper around fy_local_float().

Return

fy_generic wrapping the encoded float.

macro FY_CONST_P_INIT

FY_CONST_P_INIT(_v)

Detect a C string literal and return its value, or “” for non-literal char*.

Parameters:

  • _v – A C expression (typically a string literal or char* variable).

Description

C string literals decay to char *, but &”literal” has type char (*)[N], not char **. This macro exploits that to distinguish literals from variables: literals are returned as-is; non-literal char* expressions yield “”.

Used internally by fy_string_size_const() to initialize static string buffers.

Return

_v itself for string literals; “” for other char* values; “” for all other types.

macro fy_string_size_alloca

fy_string_size_alloca(_v, _len)

Encode a string with explicit length using alloca for out-of-place storage.

Parameters:

  • _v – Pointer to the string data (need not be NUL-terminated).

  • _len – Length in bytes.

Description

Attempts inplace encoding first (strings <=7 bytes on 64-bit). Longer strings are stored in a stack-allocated buffer prefixed with the encoded length.

Return

fy_generic_value (stack lifetime for out-of-place case).

macro fy_string_size_const

fy_string_size_const(_v, _len)

Encode a compile-time constant string with explicit length using static storage.

Parameters:

  • _v – Pointer to the string data (must be a string literal for static init).

  • _len – Byte length of the string (excluding any NUL terminator).

Description

Attempts inplace encoding first. For longer strings, stores the data in a static constant struct whose first bytes hold the variable-length encoded length and whose flexible array member holds the string bytes. The struct is aligned so its address can be stored as an out-of-place generic pointer.

Must only be called when both _v and _len are compile-time constants (guarded by __builtin_constant_p in fy_string() / fy_local_string()).

Return

fy_generic_value with static storage lifetime.

macro fy_string_alloca

fy_string_alloca(_v)

Encode a NUL-terminated string using alloca for out-of-place storage.

Parameters:

  • _v – Null-terminated C string.

Description

Computes the length with strlen() then delegates to fy_string_size_alloca().

Return

fy_generic_value (stack lifetime for out-of-place case).

macro fy_local_string_size

fy_local_string_size(_v, _len)

Construct a fy_generic string with explicit length, choosing static or alloca storage.

Parameters:

  • _v – String pointer (literal for static path, any pointer for alloca path).

  • _len – Byte length.

Return

fy_generic wrapping the encoded string.

macro fy_local_string

fy_local_string(_v)

Construct a fy_generic string, choosing static or alloca storage.

Parameters:

  • _v – String pointer (literal uses static storage; variable pointer uses alloca).

Return

fy_generic wrapping the encoded string.

macro fy_string_size

fy_string_size(_v, _len)

High-level string generic constructor with explicit byte length.

Parameters:

  • _v – String data pointer.

  • _len – Byte length.

Return

fy_generic wrapping the encoded string.

macro fy_string

fy_string(_v)

High-level string generic constructor from a NUL-terminated C string.

Parameters:

  • _v – Null-terminated C string.

Return

fy_generic wrapping the encoded string.

macro fy_stringf_value

fy_stringf_value(_fmt, ...)

Format a string using fy_sprintfa() and encode it as a fy_generic_value.

Parameters:

  • _fmt – printf-compatible format string.

  • ellipsis (ellipsis) – Format arguments.

Return

fy_generic_value encoding the formatted string (stack lifetime).

macro fy_stringf

fy_stringf(_fmt, ...)

Format a string and return it as a fy_generic.

Parameters:

  • _fmt – printf-compatible format string.

  • ellipsis (ellipsis) – Format arguments.

Return

fy_generic wrapping the formatted string.

macro fy_sequence_alloca

fy_sequence_alloca(_count, _items)

Allocate a sequence on the stack and copy items into it.

Parameters:

  • _count – Number of elements.

  • _items – Pointer to an array of _count fy_generic values to copy.

Return

fy_generic_value encoding the stack-allocated sequence (stack lifetime).

macro fy_local_sequence_create_value

fy_local_sequence_create_value(_count, _items)

Create a fy_generic_value for a sequence, handling the empty case.

Parameters:

  • _count – Number of elements.

  • _items – Array of elements to copy.

Description

Returns fy_seq_empty_value when _count is 0.

Return

fy_generic_value for the sequence.

macro fy_local_sequence_create

fy_local_sequence_create(_count, _items)

Create a fy_generic sequence from a count and item array.

Parameters:

  • _count – Number of elements.

  • _items – Array of fy_generic values to copy.

Return

fy_generic sequence value.

macro FY_CPP_VA_GITEMS

FY_CPP_VA_GITEMS(_count, ...)

Build a compound-literal fy_generic array from variadic arguments.

Parameters:

  • _count – Number of elements (must equal the number of variadic arguments).

  • ellipsis (ellipsis) – Values to convert.

Description

Each argument is passed through fy_to_generic() for automatic type conversion.

Return

A (fy_generic [_count]){…} compound literal.

macro FY_CPP_VA_GBITEMS

FY_CPP_VA_GBITEMS(_count, _gb, ...)

Build a compound-literal fy_generic array from variadic arguments via a builder.

Parameters:

  • _count – Number of elements.

  • _gb – Builder to internalize values into.

  • ellipsis (ellipsis) – Values to convert.

Description

Like FY_CPP_VA_GITEMS() but each item is internalized into _gb via fy_gb_to_generic(), ensuring persistent heap storage.

Return

A (fy_generic [_count]){…} compound literal.

macro fy_local_sequence_value

fy_local_sequence_value(...)

Build a sequence fy_generic_value from variadic arguments.

Parameters:

  • ellipsis (ellipsis) – Values to include in the sequence.

Description

Each argument is converted via fy_to_generic(); the resulting items are stored in a stack-allocated fy_generic_sequence.

Return

fy_generic_value encoding the sequence (stack lifetime).

macro fy_local_sequence

fy_local_sequence(...)

Build a fy_generic sequence from variadic arguments.

Parameters:

  • ellipsis (ellipsis) – Values to include in the sequence.

Return

fy_generic sequence value (stack lifetime).

macro fy_mapping_alloca

fy_mapping_alloca(_count, _pairs)

Allocate a mapping on the stack and copy key-value pairs into it.

Parameters:

  • _count – Number of key-value pairs.

  • _pairs – Pointer to an array of 2 x _count fy_generic values (interleaved key, value).

Return

fy_generic_value encoding the stack-allocated mapping (stack lifetime).

macro fy_local_mapping_create_value

fy_local_mapping_create_value(_count, _pairs)

Create a fy_generic_value for a mapping, handling the empty case.

Parameters:

  • _count – Number of key-value pairs.

  • _pairs – Array of interleaved key/value pairs.

Return

fy_generic_value for the mapping.

macro fy_local_mapping_create

fy_local_mapping_create(_count, _items)

Create a fy_generic mapping from a count and pairs array.

Parameters:

  • _count – Number of key-value pairs.

  • _items – Array of interleaved fy_generic key/value pairs.

Return

fy_generic mapping value.

macro fy_local_mapping_value

fy_local_mapping_value(...)

Build a mapping fy_generic_value from variadic key-value arguments.

Parameters:

  • ellipsis (ellipsis) – Alternating key/value arguments (even count required).

Description

Arguments must be alternating key, value pairs. Each is converted via fy_to_generic().

Return

fy_generic_value encoding the mapping (stack lifetime).

macro fy_local_mapping

fy_local_mapping(...)

Build a fy_generic mapping from variadic key-value arguments.

Parameters:

  • ellipsis (ellipsis) – Alternating key/value arguments.

Return

fy_generic mapping value (stack lifetime).

macro fy_indirect_alloca

fy_indirect_alloca(_v, _anchor, _tag)

Build an indirect wrapper value on the stack.

Parameters:

  • _v – Wrapped value (fy_generic_value), or fy_invalid_value to omit.

  • _anchor – Anchor string generic value (fy_string), or fy_invalid_value to omit.

  • _tag – Tag string generic value (fy_string), or fy_invalid_value to omit.

Description

Allocates a compact array on the stack that holds a flags word followed by whichever of value, anchor, and tag are not fy_invalid_value.

Return

fy_generic_value encoding the indirect wrapper (stack lifetime).

macro fy_indirect

fy_indirect(_v, _anchor, _tag)

Build an indirect-wrapper fy_generic from fy_generic arguments.

Parameters:

  • _v – The wrapped value as fy_generic, or fy_invalid for none.

  • _anchor – Anchor string as fy_generic, or fy_invalid for none.

  • _tag – Tag string as fy_generic, or fy_invalid for none.

Return

fy_generic indirect wrapper (stack lifetime).

fy_generic_cast_generic_default

fy_generic fy_generic_cast_generic_default(fy_generic v, fy_generic default_value)

Return v if it is valid, otherwise return default_value.

Parameters:

Return

v when valid, otherwise default_value.

fy_genericp_cast_generic_default

fy_generic fy_genericp_cast_generic_default(const fy_generic *vp, fy_generic default_value)

Dereference a generic pointer and return its value, or a default.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (fy_generic) – Fallback when vp is NULL or the value is invalid.

Return

*@vp when valid, otherwise default_value.

fy_generic_cast_sequence_handle_default

fy_generic_sequence_handle fy_generic_cast_sequence_handle_default(fy_generic v, fy_generic_sequence_handle default_value)

Extract a sequence handle from a generic, or return a default.

Parameters:

  • v (fy_generic) – Generic value.

  • default_value (fy_generic_sequence_handle) – Fallback handle when v does not hold a sequence.

Return

Sequence handle on success, or default_value.

fy_genericp_cast_sequence_handle_default

fy_generic_sequence_handle fy_genericp_cast_sequence_handle_default(const fy_generic *vp, fy_generic_sequence_handle default_value)

Extract a sequence handle via a pointer, or return a default.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (fy_generic_sequence_handle) – Fallback when vp is NULL or not a sequence.

Return

Sequence handle, or default_value.

fy_generic_cast_mapping_handle_default

fy_generic_mapping_handle fy_generic_cast_mapping_handle_default(fy_generic v, fy_generic_mapping_handle default_value)

Extract a mapping handle from a generic, or return a default.

Parameters:

  • v (fy_generic) – Generic value.

  • default_value (fy_generic_mapping_handle) – Fallback when v does not hold a mapping.

Return

Mapping handle, or default_value.

fy_genericp_cast_mapping_handle_default

fy_generic_mapping_handle fy_genericp_cast_mapping_handle_default(const fy_generic *vp, fy_generic_mapping_handle default_value)

Extract a mapping handle via a pointer, or return a default.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (fy_generic_mapping_handle) – Fallback when vp is NULL or not a mapping.

Return

Mapping handle, or default_value.

fy_generic_cast_const_char_ptr_default

const char *fy_generic_cast_const_char_ptr_default(fy_generic v, const char *default_value)

Extract a const char* pointer from a string generic.

Parameters:

  • v (fy_generic) – Generic string value.

  • default_value (const char*) – Fallback when v is not a string.

Description

Works for out-of-place strings (returns a pointer into the stored buffer). Returns NULL for inplace strings (the caller must use the alloca path instead).

Return

const char* into the string data, NULL for inplace strings, or default_value.

fy_generic_cast_sized_string_default

fy_generic_sized_string fy_generic_cast_sized_string_default(fy_generic v, const fy_generic_sized_string default_value)

Extract a sized string from a generic string value.

Parameters:

Description

Out-of-place strings return a pointer+size directly into the stored buffer. Inplace strings return an all-zero szstr (data=NULL, size=0) to indicate the caller must use the alloca path to copy the bytes out of the generic word.

Return

fy_generic_sized_string; data may be NULL for inplace strings.

fy_genericp_cast_const_char_ptr_default

const char *fy_genericp_cast_const_char_ptr_default(const fy_generic *vp, const char *default_value)

Extract a const char* via a pointer, or return a default.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (const char*) – Fallback when vp is NULL or not a string.

Return

Pointer to string data, or default_value.

fy_genericp_cast_sized_string_default

fy_generic_sized_string fy_genericp_cast_sized_string_default(const fy_generic *vp, const fy_generic_sized_string default_value)

Extract a sized string via a pointer, or return a default.

Parameters:

Return

fy_generic_sized_string with pointer into string data.

fy_generic_cast_decorated_int_default

fy_generic_decorated_int fy_generic_cast_decorated_int_default(fy_generic v, const fy_generic_decorated_int default_value)

Extract a decorated int from a generic, or return a default.

Parameters:

Description

Handles both inplace (always signed) and out-of-place decorated int encodings. Indirect wrappers are resolved automatically.

Return

fy_generic_decorated_int on success, or default_value.

fy_generic_cast_const_char_ptr_default_alloca

size_t fy_generic_cast_const_char_ptr_default_alloca(fy_generic v)

Return alloca size needed for inplace string cast.

Parameters:

Description

Returns sizeof(fy_generic) bytes when the value is an inplace string (so the caller can copy the bytes to the stack), 0 for all other types.

Return

sizeof(fy_generic) for inplace strings, 0 otherwise.

fy_generic_cast_const_char_ptr_default_final

void fy_generic_cast_const_char_ptr_default_final(fy_generic v, void *p, size_t size, const char *default_value, const char **store_value)

Copy an inplace string to a stack buffer.

Parameters:

  • v (fy_generic) – Inplace string generic value.

  • p (void*) – Stack buffer of at least size bytes.

  • size (size_t) – Buffer size in bytes.

  • default_value (const char*) – Unused; present for _Generic dispatch uniformity.

  • store_value (const char**) – Receives a pointer to the NUL-terminated copy in p.

Description

Called after alloca when an inplace string was detected. Copies the bytes out of the generic word into p and sets *@store_value to point to p.

fy_generic_cast_sized_string_default_final

void fy_generic_cast_sized_string_default_final(fy_generic v, void *p, size_t size, fy_generic_sized_string default_value, fy_generic_sized_string *store_value)

Copy an inplace string to a stack buffer as a sized_string.

Parameters:

macro fy_generic_cast_default

fy_generic_cast_default(_v, _dv)

Cast a generic value to a C type using _Generic dispatch.

Parameters:

  • _v – Source value (any type; converted via fy_to_generic()).

  • _dv – Default value whose C type determines the target type.

Description

Converts _v to the type inferred from _dv. Handles inplace strings by allocating a stack buffer and copying the bytes there. Indirect wrappers are automatically resolved.

Return

The converted value of the same type as _dv, or _dv on failure.

macro fy_generic_get_type_default

fy_generic_get_type_default(_type)

Produce the zero/NULL default for a C type.

Parameters:

  • _type – A C type name.

Description

Uses _Generic dispatch over a local variable of _type to look up the appropriate zero value from fy_generic_get_type_default_Generic_dispatch.

Return

The default value for _type.

macro fy_generic_cast_typed

fy_generic_cast_typed(_v, _type)

Cast a generic value to a specific C type.

Parameters:

  • _v – Source value (any type).

  • _type – Target C type name.

Description

Convenience wrapper: derives the default from the type and delegates to fy_generic_cast_default().

Return

Converted value of type _type.

macro fy_genericp_cast_default

fy_genericp_cast_default(_vp, _dv)

Cast a generic pointer’s value to a C type using _Generic dispatch.

Parameters:

  • _vp – Pointer to a fy_generic, or NULL.

  • _dv – Default value whose type determines the target.

Return

Converted value, or _dv when _vp is NULL or type mismatch.

macro fy_genericp_cast_typed

fy_genericp_cast_typed(_vp, _type)

Cast a generic pointer’s value to a specific C type.

Parameters:

  • _vp – Pointer to a fy_generic, or NULL.

  • _type – Target C type name.

Return

Converted value of type _type.

fy_genericp_get_generic_sequence_handle_default

fy_generic_sequence_handle fy_genericp_get_generic_sequence_handle_default(const fy_generic *vp, fy_generic_sequence_handle default_value)

Extract a sequence handle via a pointer, or return a default.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (fy_generic_sequence_handle) – Fallback when vp is NULL or not a sequence.

Return

Sequence handle, or default_value.

fy_genericp_get_generic_mapping_handle_default

fy_generic_mapping_handle fy_genericp_get_generic_mapping_handle_default(const fy_generic *vp, fy_generic_mapping_handle default_value)

Extract a mapping handle via a pointer, or return a default.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (fy_generic_mapping_handle) – Fallback when vp is NULL or not a mapping.

Return

Mapping handle, or default_value.

fy_genericp_get_generic_default

fy_generic fy_genericp_get_generic_default(const fy_generic *vp, fy_generic default_value)

Dereference a generic pointer, returning a default for NULL.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

  • default_value (fy_generic) – Value returned when vp is NULL.

Return

*@vp when non-NULL, otherwise default_value.

fy_genericp_get_string_genericp

const fy_generic *fy_genericp_get_string_genericp(const fy_generic *vp)

Return vp itself if it points to a direct string, or NULL.

Parameters:

  • vp (const fy_generic*) – Pointer to a fy_generic, or NULL.

Return

vp when *@vp is a direct string, NULL otherwise.

fy_genericp_get_szstr_default

fy_generic_sized_string fy_genericp_get_szstr_default(const fy_generic *vp, fy_generic_sized_string default_value)

Extract a sized string via a pointer, resolving indirects.

Parameters:

Return

fy_generic_sized_string pointing into the stored data, or default_value.

macro fy_generic_cast_default_coerse

fy_generic_cast_default_coerse(_v, _dv)

Convert a value to fy_generic first, then cast with a default.

Parameters:

  • _v – Value to convert (any supported type).

  • _dv – Default value (determines output type).

Description

Like fy_generic_cast_default() but accepts any type for _v by converting it through fy_to_generic() before casting.

Return

Converted value of the type of _dv.

macro fy_generic_sequence_get_default

fy_generic_sequence_get_default(_seq, _idx, _dv)

Retrieve a typed element from a sequence by index.

Parameters:

  • _seq – fy_generic sequence value.

  • _idx – Element index.

  • _dv – Default value (type determines the output type).

Return

Element cast to the type of _dv, or _dv if out of range or type mismatch.

macro fy_generic_sequence_get_typed

fy_generic_sequence_get_typed(_seq, _idx, _type)

Retrieve a typed element from a sequence by index.

Parameters:

  • _seq – fy_generic sequence value.

  • _idx – Element index.

  • _type – C type name of the desired output type.

Description

Like fy_generic_sequence_get_default() but derives the default from _type.

Return

Element of type _type, or the zero/NULL default.

macro fy_generic_sequence_get_default_coerse

fy_generic_sequence_get_default_coerse(_seq, _idxv, _dv)

Retrieve an element from a sequence using a generic index.

Parameters:

  • _seq – Sequence.

  • _idxv – Index as any type convertible to fy_generic (e.g. an integer).

  • _dv – Default value.

Return

Element cast to the type of _dv, or _dv.

macro fy_generic_sequencep_get_default

fy_generic_sequencep_get_default(_seqp, _idx, _dv)

Retrieve a typed element from a sequence pointer by index.

Parameters:

  • _seqp – Pointer to a fy_generic_sequence.

  • _idx – Element index.

  • _dv – Default value.

Return

Element cast to the type of _dv, or _dv.

macro fy_generic_mapping_get_default

fy_generic_mapping_get_default(_map, _key, _dv)

Look up a key in a mapping and return the typed value.

Parameters:

  • _map – fy_generic mapping value.

  • _key – Key (any type; converted via fy_to_generic()).

  • _dv – Default value (its C type determines the output type).

Return

Value cast to the type of _dv, or _dv when not found.

macro fy_generic_mapping_get_typed

fy_generic_mapping_get_typed(_map, _key, _type)

Look up a key in a mapping and return the value as a specific type.

Parameters:

  • _map – fy_generic mapping value.

  • _key – Key (any type).

  • _type – C type name of the desired output.

Return

Value of type _type, or the zero/NULL default.

macro fy_generic_mappingp_get_default

fy_generic_mappingp_get_default(_mapp, _key, _dv)

Look up a key in a mapping pointer and return the typed value.

Parameters:

  • _mapp – Pointer to a fy_generic_mapping.

  • _key – Key (any type).

  • _dv – Default value.

Return

Value cast to the type of _dv, or _dv.

macro fy_generic_mapping_get_at_default

fy_generic_mapping_get_at_default(_map, _idx, _dv)

Get the value at index _idx in a mapping, typed via default.

Parameters:

  • _map – fy_generic mapping value

  • _idx – Zero-based pair index

  • _dv – Default value (type determines the return type)

Return

The value at position _idx cast to the type of _dv, or _dv if out of range.

macro fy_generic_mappingp_get_at_default

fy_generic_mappingp_get_at_default(_mapp, _idx, _dv)

Get the value at index _idx in a mapping pointer, typed via default.

Parameters:

  • _mapp – Pointer to fy_generic_mapping

  • _idx – Zero-based pair index

  • _dv – Default value (type determines the return type)

Return

The value at position _idx cast to the type of _dv, or _dv if out of range.

macro fy_generic_mapping_get_key_at_default

fy_generic_mapping_get_key_at_default(_map, _idx, _dv)

Get the key at index _idx in a mapping, typed via default.

Parameters:

  • _map – fy_generic mapping value

  • _idx – Zero-based pair index

  • _dv – Default value (type determines the return type)

Return

The key at position _idx cast to the type of _dv, or _dv if out of range.

macro fy_generic_mappingp_get_key_at_default

fy_generic_mappingp_get_key_at_default(_mapp, _idx, _dv)

Get the key at index _idx in a mapping pointer, typed via default.

Parameters:

  • _mapp – Pointer to fy_generic_mapping

  • _idx – Zero-based pair index

  • _dv – Default value (type determines the return type)

Return

The key at position _idx cast to the type of _dv, or _dv if out of range.

fy_get_generic_direct_collection_type

enum fy_generic_type fy_get_generic_direct_collection_type(fy_generic v)

Determine whether a direct generic value is a sequence or mapping.

Parameters:

  • v (fy_generic) – A direct fy_generic value (no indirection)

Return

FYGT_SEQUENCE, FYGT_MAPPING, or FYGT_INVALID if v is not a direct collection.

macro fy_generic_get_default

fy_generic_get_default(_colv, _key, _dv)

Get an element from a collection by key or index, typed via default.

Parameters:

  • _colv – Collection value (fy_generic, sequence handle, or mapping handle)

  • _key – Key for mappings, or integer index for sequences

  • _dv – Default value (type determines the return type)

Description

Works uniformly on sequences and mappings. For mappings, _key is converted to a fy_generic and used as the lookup key. For sequences, _key is coerced to a size_t index. Accepts fy_generic, fy_generic_sequence_handle, or fy_generic_mapping_handle as _colv.

Return

The element at _key cast to the type of _dv, or _dv if not found or wrong type.

macro fy_generic_get_at_default

fy_generic_get_at_default(_colv, _idx, _dv)

Get an element from a collection at a numeric index, typed via default.

Parameters:

  • _colv – Collection value (fy_generic, sequence handle, or mapping handle)

  • _idx – Zero-based integer index

  • _dv – Default value (type determines the return type)

Description

Works uniformly on sequences and mappings. For mappings, _idx selects the pair value. Accepts fy_generic, fy_generic_sequence_handle, or fy_generic_mapping_handle as _colv.

Return

The element at _idx cast to the type of _dv, or _dv if out of range.

macro fy_generic_get_key_at_default

fy_generic_get_key_at_default(_colv, _idx, _dv)

Get the KEY at a numeric index from a collection, typed via default.

Parameters:

  • _colv – Collection value (fy_generic, sequence handle, or mapping handle)

  • _idx – Zero-based integer index

  • _dv – Default value (type determines the return type)

Description

For mappings, returns the key of the pair at _idx. For sequences, returns the element at _idx (keys are the elements themselves).

Return

The key at _idx cast to the type of _dv, or _dv if out of range.

fy_get_len_genericp

size_t fy_get_len_genericp(const void *p)

Return element/character count of a fy_generic collection or string.

Parameters:

  • p (const void*) – Pointer to a fy_generic value

Description

Resolves indirect values; returns count for sequences and mappings, byte length for strings.

Return

Element count (collection) or string length in bytes; 0 for scalar types or NULL.

macro fy_generic_len

fy_generic_len(_colv)

Return the number of elements in a collection or characters in a string.

Parameters:

  • _colv – Collection or string value

Description

Accepts fy_generic, fy_generic_sequence_handle, or fy_generic_mapping_handle. For strings, returns the byte length. For scalars, returns 0.

Return

Element count, pair count, or string length; 0 for non-collection scalars.

enum fy_generic_schema

enum fy_generic_schema

YAML/JSON schema variant used during parsing and builder operations.

Definition

enum fy_generic_schema {
    FYGS_AUTO,
    FYGS_YAML1_2_FAILSAFE,
    FYGS_YAML1_2_CORE,
    FYGS_YAML1_2_JSON,
    FYGS_YAML1_1_FAILSAFE,
    FYGS_YAML1_1,
    FYGS_YAML1_1_PYYAML,
    FYGS_JSON,
    FYGS_PYTHON
};

Constants

FYGS_AUTO

Automatically select schema based on input

FYGS_YAML1_2_FAILSAFE

YAML 1.2 failsafe schema (all values are strings)

FYGS_YAML1_2_CORE

YAML 1.2 core schema

FYGS_YAML1_2_JSON

YAML 1.2 JSON schema

FYGS_YAML1_1_FAILSAFE

YAML 1.1 failsafe schema

FYGS_YAML1_1

YAML 1.1 schema

FYGS_YAML1_1_PYYAML

YAML 1.1 with PyYAML quirks

FYGS_JSON

JSON schema

FYGS_PYTHON

Python-compatible schema

fy_generic_schema_get_text

const char *fy_generic_schema_get_text(enum fy_generic_schema schema)

Return a human-readable name for schema.

Parameters:

Return

A static NUL-terminated string describing the schema, or “unknown” for invalid values.

enum fy_gb_cfg_flags

enum fy_gb_cfg_flags

Generic builder configuration flags.

Definition

enum fy_gb_cfg_flags {
    FYGBCF_SCHEMA_AUTO,
    FYGBCF_SCHEMA_YAML1_2_FAILSAFE,
    FYGBCF_SCHEMA_YAML1_2_CORE,
    FYGBCF_SCHEMA_YAML1_2_JSON,
    FYGBCF_SCHEMA_YAML1_1_FAILSAFE,
    FYGBCF_SCHEMA_YAML1_1,
    FYGBCF_SCHEMA_YAML1_1_PYYAML,
    FYGBCF_SCHEMA_JSON,
    FYGBCF_SCHEMA_PYTHON,
    FYGBCF_OWNS_ALLOCATOR,
    FYGBCF_CREATE_ALLOCATOR,
    FYGBCF_DUPLICATE_KEYS_DISABLED,
    FYGBCF_DEDUP_ENABLED,
    FYGBCF_SCOPE_LEADER,
    FYGBCF_CREATE_TAG,
    FYGBCF_TRACE
};

Constants

FYGBCF_SCHEMA_AUTO

Auto-detect schema from content

FYGBCF_SCHEMA_YAML1_2_FAILSAFE

Use YAML 1.2 failsafe schema

FYGBCF_SCHEMA_YAML1_2_CORE

Use YAML 1.2 core schema

FYGBCF_SCHEMA_YAML1_2_JSON

Use YAML 1.2 JSON schema

FYGBCF_SCHEMA_YAML1_1_FAILSAFE

Use YAML 1.1 failsafe schema

FYGBCF_SCHEMA_YAML1_1

Use YAML 1.1 schema

FYGBCF_SCHEMA_YAML1_1_PYYAML

Use YAML 1.1 with PyYAML quirks

FYGBCF_SCHEMA_JSON

Use JSON schema

FYGBCF_SCHEMA_PYTHON

Use Python-compatible schema

FYGBCF_OWNS_ALLOCATOR

Builder will destroy the allocator on cleanup

FYGBCF_CREATE_ALLOCATOR

Builder creates its own allocator

FYGBCF_DUPLICATE_KEYS_DISABLED

Reject duplicate mapping keys

FYGBCF_DEDUP_ENABLED

Enable string/value deduplication

FYGBCF_SCOPE_LEADER

Builder is the scope leader (owns the scope)

FYGBCF_CREATE_TAG

Create an allocator tag on setup

FYGBCF_TRACE

Enable diagnostic tracing

Description

Schema selection occupies bits 0-3 (FYGBCF_SCHEMA_* values); remaining bits are boolean flags. Pass to fy_generic_builder_cfg.flags or fy_generic_builder_create_in_place().

struct fy_generic_builder_cfg

struct fy_generic_builder_cfg

Configuration for creating a generic builder.

Definition

struct fy_generic_builder_cfg {
    enum fy_gb_cfg_flags flags;
    struct fy_allocator *allocator;
    struct fy_generic_builder *parent;
    size_t estimated_max_size;
    struct fy_diag *diag;
}

Members

flags

Configuration flags (see enum fy_gb_cfg_flags)

allocator

Optional pre-existing allocator to use; NULL lets the builder create one

parent

Optional parent builder for scoped (child) builders

estimated_max_size

Hint for initial allocator capacity (0 = use default)

diag

Optional diagnostics context; NULL = no diagnostics

enum fy_gb_flags

enum fy_gb_flags

Runtime state flags for a generic builder instance.

Definition

enum fy_gb_flags {
    FYGBF_NONE,
    FYGBF_SCOPE_LEADER,
    FYGBF_DEDUP_ENABLED,
    FYGBF_DEDUP_CHAIN,
    FYGBF_OWNS_ALLOCATOR,
    FYGBF_CREATED_TAG
};

Constants

FYGBF_NONE

No flags set

FYGBF_SCOPE_LEADER

Builder is the scope leader

FYGBF_DEDUP_ENABLED

Deduplication is active on this builder

FYGBF_DEDUP_CHAIN

All builders in the chain have deduplication enabled

FYGBF_OWNS_ALLOCATOR

Builder owns and will destroy the allocator

FYGBF_CREATED_TAG

Builder created a tag on the allocator

Description

These flags reflect the operating state of a builder and are not user-settable directly; they are derived from the configuration flags at creation time.

fy_generic_builder_setup

int fy_generic_builder_setup(struct fy_generic_builder *gb, const struct fy_generic_builder_cfg *cfg)

Initialize a pre-allocated generic builder structure.

Parameters:

  • gb (struct fy_generic_builder*) – Pointer to an already-allocated fy_generic_builder to initialize

  • cfg (const struct fy_generic_builder_cfg*) – Configuration; NULL uses defaults

Return

0 on success, -1 on error.

fy_generic_builder_cleanup

void fy_generic_builder_cleanup(struct fy_generic_builder *gb)

Release resources held by a builder initialized via fy_generic_builder_setup().

Parameters:

  • gb (struct fy_generic_builder*) – Builder to clean up

Description

Does NOT free gb itself (mirrors fy_generic_builder_setup()).

fy_generic_builder_create

struct fy_generic_builder *fy_generic_builder_create(const struct fy_generic_builder_cfg *cfg)

Heap-allocate and initialize a generic builder.

Parameters:

Return

Newly allocated builder, or NULL on error. Free with fy_generic_builder_destroy().

fy_generic_builder_destroy

void fy_generic_builder_destroy(struct fy_generic_builder *gb)

Destroy and free a builder created by fy_generic_builder_create().

Parameters:

  • gb (struct fy_generic_builder*) – Builder to destroy (may be NULL)

fy_generic_builder_reset

void fy_generic_builder_reset(struct fy_generic_builder *gb)

Reset a builder to its initial empty state without freeing it.

Parameters:

  • gb (struct fy_generic_builder*) – Builder to reset

Description

All previously built values become invalid after reset.

fy_gb_alloc

void *fy_gb_alloc(struct fy_generic_builder *gb, size_t size, size_t align)

Allocate raw bytes from the builder’s arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • size (size_t) – Bytes to allocate

  • align (size_t) – Required alignment in bytes

Return

Pointer to allocated memory, or NULL on failure.

fy_gb_free

void fy_gb_free(struct fy_generic_builder *gb, void *ptr)

Release a previously allocated block back to the builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • ptr (void*) – Pointer returned by fy_gb_alloc()

fy_gb_trim

void fy_gb_trim(struct fy_generic_builder *gb)

Trim excess reserved capacity in the builder’s allocator.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

fy_gb_store

const void *fy_gb_store(struct fy_generic_builder *gb, const void *data, size_t size, size_t align)

Copy size bytes of data into the builder’s arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • data (const void*) – Source data

  • size (size_t) – Bytes to copy

  • align (size_t) – Required alignment

Return

Pointer to the stored copy inside the arena, or NULL on failure.

fy_gb_storev

const void *fy_gb_storev(struct fy_generic_builder *gb, const struct iovec *iov, unsigned int iovcnt, size_t align)

Scatter-gather store: copy multiple iovec buffers into the arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • iov (const struct iovec*) – Array of iovec descriptors

  • iovcnt (unsigned int) – Number of iovec entries

  • align (size_t) – Required alignment

Return

Pointer to the contiguous stored copy, or NULL on failure.

fy_gb_lookupv

const void *fy_gb_lookupv(struct fy_generic_builder *gb, const struct iovec *iov, unsigned int iovcnt, size_t align)

Look up existing data in the builder’s arena by scatter-gather comparison.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • iov (const struct iovec*) – Array of iovec descriptors describing the data to find

  • iovcnt (unsigned int) – Number of iovec entries

  • align (size_t) – Required alignment

Description

If deduplication is enabled, returns a pointer to an existing equal block. Otherwise returns NULL

Return

Pointer to existing copy, or NULL on failure.

fy_gb_lookup

const void *fy_gb_lookup(struct fy_generic_builder *gb, const void *data, size_t size, size_t align)

Look up existing data in the builder’s arena (single buffer variant).

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • data (const void*) – Data to find or store

  • size (size_t) – Byte size of data

  • align (size_t) – Required alignment

Description

If deduplication is enabled, returns a pointer to an existing equal block. Otherwise returns NULL

Return

Pointer to existing copy, or NULL on failure.

fy_gb_get_allocator_info

struct fy_allocator_info *fy_gb_get_allocator_info(struct fy_generic_builder *gb)

Retrieve statistics about the builder’s allocator.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

Pointer to allocator info (valid until the next allocation), or NULL.

fy_gb_release

void fy_gb_release(struct fy_generic_builder *gb, const void *ptr, size_t size)

Release a reference to an arena allocation.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • ptr (const void*) – Pointer previously returned by a store/alloc call

  • size (size_t) – Size that was allocated

fy_gb_allocation_failures

uint64_t fy_gb_allocation_failures(struct fy_generic_builder *gb)

Return number of allocation failures since last reset.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Description

Non-zero indicates that at least one operation ran out of arena space. This is used by FY_LOCAL_OP to decide whether to retry with a larger buffer.

Return

Count of allocation failures.

fy_generic_builder_set_userdata

void *fy_generic_builder_set_userdata(struct fy_generic_builder *gb, void *userdata)

Attach arbitrary user data to a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • userdata (void*) – Pointer to user-supplied data

Return

The previous userdata pointer.

fy_generic_builder_get_userdata

void *fy_generic_builder_get_userdata(struct fy_generic_builder *gb)

Retrieve user data previously attached to a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

The userdata pointer, or NULL if not set.

fy_generic_builder_create_in_place

struct fy_generic_builder *fy_generic_builder_create_in_place(enum fy_gb_cfg_flags flags, struct fy_generic_builder *parent, void *buffer, size_t size)

Create a builder using a caller-supplied stack/static buffer.

Parameters:

  • flags (enum fy_gb_cfg_flags) – Configuration flags (see enum fy_gb_cfg_flags)

  • parent (struct fy_generic_builder*) – Optional parent builder; NULL for standalone

  • buffer (void*) – Caller-supplied backing buffer (typically alloca’d or stack-allocated)

  • size (size_t) – Size of buffer in bytes; must be >= FY_GENERIC_BUILDER_LINEAR_IN_PLACE_MIN_SIZE

Description

The builder uses buffer as its backing store; no heap allocation is required. The resulting builder does NOT need to be destroyed (no fy_generic_builder_destroy() call). If the buffer runs out, operations fail with allocation errors.

Return

Pointer to the builder (embedded in buffer), or NULL on error.

fy_generic_builder_get_allocator

struct fy_allocator *fy_generic_builder_get_allocator(struct fy_generic_builder *gb)

Return the allocator used by a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

Pointer to the underlying fy_allocator, or NULL.

fy_generic_builder_get_cfg

const struct fy_generic_builder_cfg *fy_generic_builder_get_cfg(struct fy_generic_builder *gb)

Return the configuration used to create a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

Pointer to the fy_generic_builder_cfg, or NULL for in-place builders.

fy_generic_builder_get_flags

enum fy_gb_flags fy_generic_builder_get_flags(struct fy_generic_builder *gb)

Return the runtime flags of a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

The current fy_gb_flags bitmask.

fy_generic_builder_get_free

size_t fy_generic_builder_get_free(struct fy_generic_builder *gb)

Return available free bytes in the builder’s current arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

Bytes available before the next arena extension or failure.

fy_generic_builder_contains_out_of_place

bool fy_generic_builder_contains_out_of_place(struct fy_generic_builder *gb, fy_generic v)

Check whether an out-of-place generic lives in this builder’s arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • v (fy_generic) – Out-of-place generic value

Return

true if the pointer inside v points into gb‘s arena.

fy_generic_builder_contains

bool fy_generic_builder_contains(struct fy_generic_builder *gb, fy_generic v)

Check whether a generic value is owned by this builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder (may be NULL)

  • v (fy_generic) – Value to test

Description

Inplace values are always considered owned; invalid values are never owned.

Return

true if v is inplace or its pointer lives in gb‘s arena.

fy_generic_builder_get_scope_leader

struct fy_generic_builder *fy_generic_builder_get_scope_leader(struct fy_generic_builder *gb)

Walk the builder chain to find the scope-leader builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Return

The scope-leader builder in the chain, or NULL.

fy_generic_builder_get_export_builder

struct fy_generic_builder *fy_generic_builder_get_export_builder(struct fy_generic_builder *gb)

Return the builder to which values should be exported.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

Description

The export builder is the scope-leader’s parent (or the scope-leader itself if at the root).

Return

The export builder, or NULL.

fy_generic_builder_export

fy_generic fy_generic_builder_export(struct fy_generic_builder *gb, fy_generic v)

Copy a value into the export builder’s arena if necessary.

Parameters:

  • gb (struct fy_generic_builder*) – Builder (the source scope)

  • v (fy_generic) – Value to export

Description

Ensures that v is owned by the export builder so it survives beyond the scope of the current (child) builder.

Return

The exported value (possibly a copy), or fy_invalid on error.

fy_gb_string_size_create_out_of_place

fy_generic fy_gb_string_size_create_out_of_place(struct fy_generic_builder *gb, const char *str, size_t len)

Intern a string of length len in the builder’s arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • str (const char*) – String data (need not be NUL-terminated)

  • len (size_t) – String length in bytes

Return

Out-of-place fy_generic string, or fy_invalid on allocation failure.

fy_gb_string_create_out_of_place

fy_generic fy_gb_string_create_out_of_place(struct fy_generic_builder *gb, const char *str)

Intern a NUL-terminated string in the builder’s arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • str (const char*) – NUL-terminated string

Return

Out-of-place fy_generic string, or fy_invalid on allocation failure.

fy_gb_szstr_create_out_of_place

fy_generic fy_gb_szstr_create_out_of_place(struct fy_generic_builder *gb, const fy_generic_sized_string szstr)

Intern a sized string in the builder’s arena.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • szstr (const fy_generic_sized_string) – Sized string (length + pointer)

Return

Out-of-place fy_generic string, or fy_invalid on allocation failure.

fy_gb_string_size_create

fy_generic fy_gb_string_size_create(struct fy_generic_builder *gb, const char *str, size_t len)

Create a string generic, choosing inplace encoding if possible.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • str (const char*) – String data

  • len (size_t) – Length in bytes

Description

Strings up to 7 bytes (64-bit) or 3 bytes (32-bit) are encoded inplace with no allocation. Longer strings are stored in the builder’s arena.

Return

fy_generic string value, or fy_invalid on allocation failure.

macro FY_GENERIC_GB_LVAL_TEMPLATE

FY_GENERIC_GB_LVAL_TEMPLATE(_ctype, _gtype, _gttype, _xctype, _xgtype, _xminv, _xmaxv, _default_v)

Generate fy_gb_<T>_create_out_of_place() and fy_gb_<T>_create() for C type _ctype.

Parameters:

  • _ctype – C type (e.g. int, double)

  • _gtype – Name token used in the generated function names (e.g. int, double)

  • _gttype – Generic type tag (e.g. INT, FLOAT) — unused in generated code

  • _xctype – Cast destination type for the underlying primitive creator

  • _xgtype – Base type creator (int_type, uint_type, float_type, etc.)

  • _xminv – Minimum value (unused at runtime; kept for documentation)

  • _xmaxv – Maximum value (unused at runtime)

  • _default_v – Default value (unused at runtime)

macro fy_gb_to_generic_outofplace_put

fy_gb_to_generic_outofplace_put(_gb, _v)

Encode _v as an out-of-place generic using the builder.

Parameters:

  • _gb – Builder

  • _v – Value of any supported C type

Description

Uses _Generic to select the appropriate fy_gb_<T>_create_out_of_place() function.

Return

Out-of-place fy_generic, or fy_invalid on allocation failure.

macro fy_gb_to_generic_value

fy_gb_to_generic_value(_gb, _v)

Encode _v as a fy_generic_value using the builder for out-of-place storage.

Parameters:

  • _gb – Builder

  • _v – Value to encode

Description

Tries inplace encoding first; falls back to the builder arena.

Return

fy_generic_value suitable for wrapping in a fy_generic struct.

macro fy_gb_to_generic

fy_gb_to_generic(_gb, _v)

Encode _v as a fy_generic using the builder for out-of-place storage.

Parameters:

  • _gb – Builder

  • _v – Value to encode

Return

fy_generic value backed by the builder’s arena (or inplace for small values).

macro fy_to_generic_value

fy_to_generic_value(_maybe_gb, ...)

Encode a value using a builder (if provided) or alloca (for inplace / short-lived).

Parameters:

  • _maybe_gb – Either a fy_generic_builder* or any other C value

  • ellipsis (ellipsis) – variable arguments

Description

If _maybe_gb is a fy_generic_builder*, delegates to fy_gb_to_generic_value(). Otherwise treats _maybe_gb as the value itself and uses fy_local_to_generic_value().

Return

fy_generic_value for the encoded result.

fy_gb_string_vcreate

fy_generic fy_gb_string_vcreate(struct fy_generic_builder *gb, const char *fmt, va_list ap)

Create a string generic from a printf-style format string and va_list.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • fmt (const char*) – printf-compatible format string

  • ap (va_list) – Variadic argument list

Return

fy_generic string, or fy_invalid on error.

fy_gb_string_createf

fy_generic fy_gb_string_createf(struct fy_generic_builder *gb, const char *fmt, ...)

Create a string generic from a printf-style format string.

Parameters:

  • gb (struct fy_generic_builder*) – Builder

  • fmt (const char*) – printf-compatible format string

  • ellipsis (ellipsis) – Format arguments

Return

fy_generic string, or fy_invalid on error.

enum fy_gb_op

enum fy_gb_op

Operation code for generic builder operations.

Definition

enum fy_gb_op {
    FYGBOP_CREATE_INV,
    FYGBOP_CREATE_NULL,
    FYGBOP_CREATE_BOOL,
    FYGBOP_CREATE_INT,
    FYGBOP_CREATE_FLT,
    FYGBOP_CREATE_STR,
    FYGBOP_CREATE_SEQ,
    FYGBOP_CREATE_MAP,
    FYGBOP_INSERT,
    FYGBOP_REPLACE,
    FYGBOP_APPEND,
    FYGBOP_ASSOC,
    FYGBOP_DISASSOC,
    FYGBOP_KEYS,
    FYGBOP_VALUES,
    FYGBOP_ITEMS,
    FYGBOP_CONTAINS,
    FYGBOP_CONCAT,
    FYGBOP_REVERSE,
    FYGBOP_MERGE,
    FYGBOP_UNIQUE,
    FYGBOP_SORT,
    FYGBOP_FILTER,
    FYGBOP_MAP,
    FYGBOP_REDUCE,
    FYGBOP_SLICE,
    FYGBOP_SLICE_PY,
    FYGBOP_TAKE,
    FYGBOP_DROP,
    FYGBOP_FIRST,
    FYGBOP_LAST,
    FYGBOP_REST,
    FYGBOP_GET,
    FYGBOP_GET_AT,
    FYGBOP_GET_AT_PATH,
    FYGBOP_SET,
    FYGBOP_SET_AT,
    FYGBOP_SET_AT_PATH,
    FYGBOP_PARSE,
    FYGBOP_EMIT,
    FYGBOP_CONVERT
};

Constants

FYGBOP_CREATE_INV

Create an invalid (sentinel) generic

FYGBOP_CREATE_NULL

Create a null generic

FYGBOP_CREATE_BOOL

Create a boolean generic from scalar args

FYGBOP_CREATE_INT

Create an integer generic from scalar args

FYGBOP_CREATE_FLT

Create a floating-point generic from scalar args

FYGBOP_CREATE_STR

Create a string generic from scalar args

FYGBOP_CREATE_SEQ

Create a sequence from an item array

FYGBOP_CREATE_MAP

Create a mapping from a key/value pair array

FYGBOP_INSERT

Insert elements into a sequence at a given index

FYGBOP_REPLACE

Replace elements in a sequence at a given index

FYGBOP_APPEND

Append elements to the end of a sequence or mapping

FYGBOP_ASSOC

Associate key/value pairs into a mapping

FYGBOP_DISASSOC

Remove key/value pairs from a mapping

FYGBOP_KEYS

Extract all keys of a mapping as a sequence

FYGBOP_VALUES

Extract all values of a mapping as a sequence

FYGBOP_ITEMS

Extract all key+value pairs of a mapping as a sequence

FYGBOP_CONTAINS

Test whether a collection contains given elements

FYGBOP_CONCAT

Concatenate two or more sequences or mappings

FYGBOP_REVERSE

Reverse the order of a sequence

FYGBOP_MERGE

Deep-merge two mappings

FYGBOP_UNIQUE

Remove duplicate elements from a sequence

FYGBOP_SORT

Sort a sequence using a comparator

FYGBOP_FILTER

Keep elements satisfying a predicate

FYGBOP_MAP

Transform each element via a function

FYGBOP_REDUCE

Fold a sequence into an accumulator via a function

FYGBOP_SLICE

Extract a subrange [start, end) by unsigned indices

FYGBOP_SLICE_PY

Extract a subrange using Python-style signed indices

FYGBOP_TAKE

Take the first N elements of a sequence

FYGBOP_DROP

Drop the first N elements of a sequence

FYGBOP_FIRST

Return the first element of a sequence

FYGBOP_LAST

Return the last element of a sequence

FYGBOP_REST

Return all but the first element of a sequence

FYGBOP_GET

Look up a value in a collection by key

FYGBOP_GET_AT

Look up a value by numeric index

FYGBOP_GET_AT_PATH

Traverse a nested path of keys/indices

FYGBOP_SET

Set (update) a key in a mapping

FYGBOP_SET_AT

Set a value at a numeric index in a sequence

FYGBOP_SET_AT_PATH

Set a value at a nested path (creating nodes as needed)

FYGBOP_PARSE

Parse YAML/JSON text into a generic value

FYGBOP_EMIT

Emit a generic value as YAML/JSON text

FYGBOP_CONVERT

Convert a generic value to a different type

Description

Selects which collection or scalar operation fy_generic_op() / fy_generic_op_args() should perform. Encoded in the low 8 bits of fy_gb_op_flags via FYGBOPF_OP().

typedef fy_generic_filter_pred_fn

bool fy_generic_filter_pred_fn(struct fy_generic_builder *gb, fy_generic v)

Predicate function for filter operations.

Parameters:

  • gb (struct fy_generic_builder*) – The active generic builder (or NULL for stack-based operations)

  • v (fy_generic) – The element being tested

Return

true to keep the element, false to discard it.

typedef fy_generic_map_xform_fn

fy_generic fy_generic_map_xform_fn(struct fy_generic_builder *gb, fy_generic v)

Transform function for map operations.

Parameters:

  • gb (struct fy_generic_builder*) – The active generic builder

  • v (fy_generic) – The element to transform

Return

The transformed fy_generic value.

typedef fy_generic_reducer_fn

fy_generic fy_generic_reducer_fn(struct fy_generic_builder *gb, fy_generic acc, fy_generic v)

Reducer function for fold/reduce operations.

Parameters:

  • gb (struct fy_generic_builder*) – The active generic builder

  • acc (fy_generic) – The running accumulator value

  • v (fy_generic) – The current element

Return

The new accumulator value.

struct fy_op_common_args

struct fy_op_common_args

Arguments common to all collection operations.

Definition

struct fy_op_common_args {
    size_t count;
    const fy_generic *items;
    struct fy_thread_pool *tp;
}

Members

count

Number of elements in items (x2 for mapping pair arrays)

items

Pointer to the element (or key/value pair) array

tp

Optional thread pool for parallel operations (NULL = single-threaded)

Description

Embedded as the first member in every fy_op_*_args struct so that fy_generic_op_args() can read the item array uniformly regardless of which opcode is used.

Used by FYGBOP_CREATE_SEQ, FYGBOP_CREATE_MAP, FYGBOP_APPEND, FYGBOP_ASSOC, FYGBOP_DISASSOC, FYGBOP_CONTAINS, FYGBOP_CONCAT, FYGBOP_REVERSE, FYGBOP_MERGE, FYGBOP_UNIQUE, and FYGBOP_SET.

struct fy_op_create_scalar_args

struct fy_op_create_scalar_args

Arguments for scalar creation operations.

Definition

struct fy_op_create_scalar_args {
    struct fy_op_common_args common;
    union {
        bool bval;
        double fval;
        fy_generic_decorated_int ival;
        fy_generic_sized_string sval;
    } ;
}

Members

common

Embedded common args (count/items unused for scalars)

{unnamed_union}

anonymous

bval

Boolean value (FYGBOP_CREATE_BOOL)

fval

Double value (FYGBOP_CREATE_FLT)

ival

Decorated integer value (FYGBOP_CREATE_INT)

sval

Sized string value (FYGBOP_CREATE_STR)

Description

Used by FYGBOP_CREATE_BOOL, FYGBOP_CREATE_INT, FYGBOP_CREATE_FLT, and FYGBOP_CREATE_STR.

struct fy_op_sort_args

struct fy_op_sort_args

Arguments for FYGBOP_SORT.

Definition

struct fy_op_sort_args {
    struct fy_op_common_args common;
    int (*cmp_fn)(fy_generic a, fy_generic b);
}

Members

common

Embedded common args

cmp_fn

Comparator returning negative/zero/positive; NULL uses default ordering

struct fy_op_insert_replace_get_set_at_args

struct fy_op_insert_replace_get_set_at_args

Arguments for index-based operations.

Definition

struct fy_op_insert_replace_get_set_at_args {
    struct fy_op_common_args common;
    size_t idx;
}

Members

common

Embedded common args (items to insert/replace; unused for GET_AT)

idx

Zero-based target index

Description

Used by FYGBOP_INSERT, FYGBOP_REPLACE, FYGBOP_GET_AT, and FYGBOP_SET_AT.

struct fy_op_keys_values_items_args

struct fy_op_keys_values_items_args

Arguments for key/value extraction operations.

Definition

struct fy_op_keys_values_items_args {
    struct fy_op_common_args common;
}

Members

common

Embedded common args

Description

Used by FYGBOP_KEYS, FYGBOP_VALUES, and FYGBOP_ITEMS. No extra fields beyond the common args are needed.

struct fy_op_filter_args

struct fy_op_filter_args

Arguments for FYGBOP_FILTER.

Definition

struct fy_op_filter_args {
    struct fy_op_common_args common;
    union {
        fy_generic_filter_pred_fn fn;
#if defined(__BLOCKS__)
        fy_generic_filter_pred_block blk;
#endif
    } ;
}

Members

common

Embedded common args

{unnamed_union}

anonymous

fn

Filter predicate function pointer

blk

Filter predicate block (Clang __BLOCKS__ only)

struct fy_op_map_args

struct fy_op_map_args

Arguments for FYGBOP_MAP.

Definition

struct fy_op_map_args {
    struct fy_op_common_args common;
    union {
        fy_generic_map_xform_fn fn;
#if defined(__BLOCKS__)
        fy_generic_map_xform_block blk;
#endif
    } ;
}

Members

common

Embedded common args

{unnamed_union}

anonymous

fn

Transform function pointer

blk

Transform block (Clang __BLOCKS__ only)

struct fy_op_reduce_args

struct fy_op_reduce_args

Arguments for FYGBOP_REDUCE.

Definition

struct fy_op_reduce_args {
    struct fy_op_common_args common;
    union {
        fy_generic_reducer_fn fn;
#if defined(__BLOCKS__)
        fy_generic_reducer_block blk;
#endif
    } ;
    fy_generic acc;
}

Members

common

Embedded common args

{unnamed_union}

anonymous

fn

Reducer function pointer

blk

Reducer block (Clang __BLOCKS__ only)

acc

Initial accumulator value

struct fy_op_filter_map_reduce_common

struct fy_op_filter_map_reduce_common

Type-erased common layout for filter/map/reduce.

Definition

struct fy_op_filter_map_reduce_common {
    struct fy_op_common_args common;
    union {
        void (*fn)(void);
    } ;
}

Members

common

Embedded common args

{unnamed_union}

anonymous

fn

Type-erased function pointer

Description

Used internally so that the dispatcher can access the function pointer uniformly before casting it to the appropriate typed function/block.

enum fy_op_parse_flags

enum fy_op_parse_flags

Flags for FYGBOP_PARSE operations.

Definition

enum fy_op_parse_flags {
    FYOPPF_DISABLE_DIRECTORY,
    FYOPPF_MULTI_DOCUMENT,
    FYOPPF_TRACE,
    FYOPPF_DONT_RESOLVE,
    FYOPPF_INPUT_TYPE_STRING,
    FYOPPF_INPUT_TYPE_FILENAME,
    FYOPPF_INPUT_TYPE_INT_FD,
    FYOPPF_INPUT_TYPE_STDIN,
    FYOPPF_MODE_AUTO,
    FYOPPF_MODE_YAML_1_1,
    FYOPPF_MODE_YAML_1_2,
    FYOPPF_MODE_YAML_1_3,
    FYOPPF_MODE_JSON,
    FYOPPF_MODE_YAML_1_1_PYYAML,
    FYOPPF_COLLECT_DIAG,
    FYOPPF_KEEP_COMMENTS,
    FYOPPF_CREATE_MARKERS,
    FYOPPF_KEEP_STYLE,
    FYOPPF_KEEP_FAILSAFE_STR
};

Constants

FYOPPF_DISABLE_DIRECTORY

Do not include a document-state directory in the result

FYOPPF_MULTI_DOCUMENT

Allow multiple YAML documents in the input

FYOPPF_TRACE

Enable parser trace output for debugging

FYOPPF_DONT_RESOLVE

Skip tag/anchor resolution (used by the YAML test-suite)

FYOPPF_INPUT_TYPE_STRING

Input data is a NUL-terminated or sized string

FYOPPF_INPUT_TYPE_FILENAME

Input data is a filename (const char *)

FYOPPF_INPUT_TYPE_INT_FD

Input data is a file descriptor (int cast to void *)

FYOPPF_INPUT_TYPE_STDIN

Read input from stdin (input_data ignored)

FYOPPF_MODE_AUTO

Auto-detect YAML version / JSON from content

FYOPPF_MODE_YAML_1_1

Force YAML 1.1 parsing rules

FYOPPF_MODE_YAML_1_2

Force YAML 1.2 parsing rules

FYOPPF_MODE_YAML_1_3

Force YAML 1.3 parsing rules

FYOPPF_MODE_JSON

Force JSON parsing rules

FYOPPF_MODE_YAML_1_1_PYYAML

Force YAML 1.1 PyYAML-compatible parsing rules

FYOPPF_COLLECT_DIAG

Collect diagnostic messages into the result

FYOPPF_KEEP_COMMENTS

Preserve comments in the parsed representation

FYOPPF_CREATE_MARKERS

Attach position markers to parsed nodes

FYOPPF_KEEP_STYLE

Preserve original scalar/collection style information

FYOPPF_KEEP_FAILSAFE_STR

Keep failsafe-schema plain string tags

Description

Control how input is located and how the YAML parser behaves during a fy_parse() / fy_local_parse() / fy_gb_parse() call.

struct fy_op_parse_args

struct fy_op_parse_args

Arguments for FYGBOP_PARSE.

Definition

struct fy_op_parse_args {
    struct fy_op_common_args common;
    enum fy_op_parse_flags flags;
    void *input_data;
}

Members

common

Embedded common args (items may hold a schema override sequence)

flags

Parse configuration flags (input type, mode, options)

input_data

Input source; interpretation depends on FYOPPF_INPUT_TYPE_*: STRING: const char *, FILENAME: const char *, INT_FD: (void *)(uintptr_t)fd, STDIN: ignored

enum fy_op_emit_flags

enum fy_op_emit_flags

Flags for FYGBOP_EMIT operations.

Definition

enum fy_op_emit_flags {
    FYOPEF_DISABLE_DIRECTORY,
    FYOPEF_MULTI_DOCUMENT,
    FYOPEF_TRACE,
    FYOPEF_NO_ENDING_NEWLINE,
    FYOPEF_WIDTH_ADAPT_TO_TERMINAL,
    FYOPEF_OUTPUT_COMMENTS,
    FYOPEF_OUTPUT_TYPE_STRING,
    FYOPEF_OUTPUT_TYPE_FILENAME,
    FYOPEF_OUTPUT_TYPE_INT_FD,
    FYOPEF_OUTPUT_TYPE_STDOUT,
    FYOPEF_OUTPUT_TYPE_STDERR,
    FYOPEF_MODE_AUTO,
    FYOPEF_MODE_YAML_1_1,
    FYOPEF_MODE_YAML_1_2,
    FYOPEF_MODE_YAML_1_3,
    FYOPEF_MODE_JSON,
    FYOPEF_MODE_YAML_1_1_PYYAML,
    FYOPEF_COLOR_AUTO,
    FYOPEF_COLOR_NONE,
    FYOPEF_COLOR_FORCE,
    FYOPEF_INDENT_DEFAULT,
    FYOPEF_INDENT_1,
    FYOPEF_INDENT_2,
    FYOPEF_INDENT_3,
    FYOPEF_INDENT_4,
    FYOPEF_INDENT_6,
    FYOPEF_INDENT_8,
    FYOPEF_WIDTH_DEFAULT,
    FYOPEF_WIDTH_80,
    FYOPEF_WIDTH_132,
    FYOPEF_WIDTH_INF,
    FYOPEF_STYLE_DEFAULT,
    FYOPEF_STYLE_BLOCK,
    FYOPEF_STYLE_FLOW,
    FYOPEF_STYLE_PRETTY,
    FYOPEF_STYLE_COMPACT,
    FYOPEF_STYLE_ONELINE
};

Constants

FYOPEF_DISABLE_DIRECTORY

Do not include a document-state directory in the output

FYOPEF_MULTI_DOCUMENT

Emit multiple YAML documents (stream)

FYOPEF_TRACE

Enable emitter trace output for debugging

FYOPEF_NO_ENDING_NEWLINE

Do not append a trailing newline

FYOPEF_WIDTH_ADAPT_TO_TERMINAL

Adapt line width to the current terminal width

FYOPEF_OUTPUT_COMMENTS

Include inline comments in the output

FYOPEF_OUTPUT_TYPE_STRING

Emit to a NUL-terminated string (output_data = char **)

FYOPEF_OUTPUT_TYPE_FILENAME

Emit to a file by name (output_data = const char *)

FYOPEF_OUTPUT_TYPE_INT_FD

Emit to a file descriptor (output_data = (void *)fd)

FYOPEF_OUTPUT_TYPE_STDOUT

Emit to stdout

FYOPEF_OUTPUT_TYPE_STDERR

Emit to stderr

FYOPEF_MODE_AUTO

Auto-select output format from schema

FYOPEF_MODE_YAML_1_1

Emit YAML 1.1

FYOPEF_MODE_YAML_1_2

Emit YAML 1.2

FYOPEF_MODE_YAML_1_3

Emit YAML 1.3

FYOPEF_MODE_JSON

Emit JSON

FYOPEF_MODE_YAML_1_1_PYYAML

Emit YAML 1.1 PyYAML-compatible

FYOPEF_COLOR_AUTO

Auto-detect terminal color support

FYOPEF_COLOR_NONE

Disable color output

FYOPEF_COLOR_FORCE

Force color output

FYOPEF_INDENT_DEFAULT

Use the library default indent (usually 2)

FYOPEF_INDENT_1

1-space indent

FYOPEF_INDENT_2

2-space indent

FYOPEF_INDENT_3

3-space indent

FYOPEF_INDENT_4

4-space indent

FYOPEF_INDENT_6

6-space indent

FYOPEF_INDENT_8

8-space indent (maximum)

FYOPEF_WIDTH_DEFAULT

Use default line width (typically infinite)

FYOPEF_WIDTH_80

Wrap at 80 columns

FYOPEF_WIDTH_132

Wrap at 132 columns

FYOPEF_WIDTH_INF

Infinite line width (no wrapping)

FYOPEF_STYLE_DEFAULT

Use the library default style

FYOPEF_STYLE_BLOCK

Block style

FYOPEF_STYLE_FLOW

Flow style

FYOPEF_STYLE_PRETTY

Pretty-printed style

FYOPEF_STYLE_COMPACT

Compact (minimal whitespace) style

FYOPEF_STYLE_ONELINE

Single-line style

Description

Control output destination, YAML/JSON version, indentation, line width, and formatting style for fy_emit() / fy_local_emit() / fy_gb_emit() calls.

struct fy_op_emit_args

struct fy_op_emit_args

Arguments for FYGBOP_EMIT.

Definition

struct fy_op_emit_args {
    struct fy_op_common_args common;
    enum fy_op_emit_flags flags;
    void *output_data;
}

Members

common

Embedded common args (items may hold schema override sequences)

flags

Emit configuration flags (output type, mode, style, etc.)

output_data

Output destination; interpretation depends on FYOPEF_OUTPUT_TYPE_*: STRING: char **, FILENAME: const char *, INT_FD: (void *)(uintptr_t)fd, STDOUT/STDERR: ignored

struct fy_op_slice_args

struct fy_op_slice_args

Arguments for FYGBOP_SLICE.

Definition

struct fy_op_slice_args {
    struct fy_op_common_args common;
    size_t start;
    size_t end;
}

Members

common

Embedded common args

start

Starting index (inclusive, zero-based)

end

Ending index (exclusive); use SIZE_MAX for “to the end”

struct fy_op_slice_py_args

struct fy_op_slice_py_args

Arguments for FYGBOP_SLICE_PY.

Definition

struct fy_op_slice_py_args {
    struct fy_op_common_args common;
    ssize_t start;
    ssize_t end;
}

Members

common

Embedded common args

start

Starting index (inclusive; negative counts from end)

end

Ending index (exclusive; negative counts from end)

Description

Like fy_op_slice_args but uses Python-style signed indices where negative values count backwards from the end of the sequence.

struct fy_op_take_args

struct fy_op_take_args

Arguments for FYGBOP_TAKE.

Definition

struct fy_op_take_args {
    struct fy_op_common_args common;
    size_t n;
}

Members

common

Embedded common args

n

Number of elements to take from the start of the sequence

struct fy_op_drop_args

struct fy_op_drop_args

Arguments for FYGBOP_DROP.

Definition

struct fy_op_drop_args {
    struct fy_op_common_args common;
    size_t n;
}

Members

common

Embedded common args

n

Number of elements to drop from the start of the sequence

struct fy_op_convert_args

struct fy_op_convert_args

Arguments for FYGBOP_CONVERT.

Definition

struct fy_op_convert_args {
    struct fy_op_common_args common;
    enum fy_generic_type type;
}

Members

common

Embedded common args

type

Target generic type to convert the input value to

enum fy_gb_op_flags

enum fy_gb_op_flags

Combined opcode + modifier flags for fy_generic_op().

Definition

enum fy_gb_op_flags {
    FYGBOPF_CREATE_SEQ,
    FYGBOPF_CREATE_MAP,
    FYGBOPF_INSERT,
    FYGBOPF_REPLACE,
    FYGBOPF_APPEND,
    FYGBOPF_ASSOC,
    FYGBOPF_DISASSOC,
    FYGBOPF_KEYS,
    FYGBOPF_VALUES,
    FYGBOPF_ITEMS,
    FYGBOPF_CONTAINS,
    FYGBOPF_CONCAT,
    FYGBOPF_REVERSE,
    FYGBOPF_MERGE,
    FYGBOPF_UNIQUE,
    FYGBOPF_SORT,
    FYGBOPF_FILTER,
    FYGBOPF_MAP,
    FYGBOPF_REDUCE,
    FYGBOPF_SLICE,
    FYGBOPF_SLICE_PY,
    FYGBOPF_TAKE,
    FYGBOPF_DROP,
    FYGBOPF_FIRST,
    FYGBOPF_LAST,
    FYGBOPF_REST,
    FYGBOPF_GET,
    FYGBOPF_GET_AT,
    FYGBOPF_GET_AT_PATH,
    FYGBOPF_SET,
    FYGBOPF_SET_AT,
    FYGBOPF_SET_AT_PATH,
    FYGBOPF_PARSE,
    FYGBOPF_EMIT,
    FYGBOPF_CONVERT,
    FYGBOPF_DONT_INTERNALIZE,
    FYGBOPF_DEEP_VALIDATE,
    FYGBOPF_NO_CHECKS,
    FYGBOPF_PARALLEL,
    FYGBOPF_MAP_ITEM_COUNT,
    FYGBOPF_BLOCK_FN,
    FYGBOPF_CREATE_PATH,
    FYGBOPF_UNSIGNED
};

Constants

FYGBOPF_CREATE_SEQ

Create a sequence

FYGBOPF_CREATE_MAP

Create a mapping

FYGBOPF_INSERT

Insert into a sequence at an index

FYGBOPF_REPLACE

Replace elements at an index

FYGBOPF_APPEND

Append to a collection

FYGBOPF_ASSOC

Associate key/value pairs into a mapping

FYGBOPF_DISASSOC

Remove keys from a mapping

FYGBOPF_KEYS

Extract mapping keys as a sequence

FYGBOPF_VALUES

Extract mapping values as a sequence

FYGBOPF_ITEMS

Extract mapping pairs as a sequence

FYGBOPF_CONTAINS

Test for element membership

FYGBOPF_CONCAT

Concatenate collections

FYGBOPF_REVERSE

Reverse a sequence

FYGBOPF_MERGE

Deep-merge mappings

FYGBOPF_UNIQUE

Remove duplicates from a sequence

FYGBOPF_SORT

Sort a sequence

FYGBOPF_FILTER

Filter elements by predicate

FYGBOPF_MAP

Transform each element

FYGBOPF_REDUCE

Fold a sequence into an accumulator

FYGBOPF_SLICE

Unsigned index slice

FYGBOPF_SLICE_PY

Python-style signed slice

FYGBOPF_TAKE

Take first N elements

FYGBOPF_DROP

Drop first N elements

FYGBOPF_FIRST

Return first element

FYGBOPF_LAST

Return last element

FYGBOPF_REST

Return all but first element

FYGBOPF_GET

Lookup by key

FYGBOPF_GET_AT

Lookup by index

FYGBOPF_GET_AT_PATH

Traverse nested path of keys/indices

FYGBOPF_SET

Set a key in a mapping

FYGBOPF_SET_AT

Set element at an index

FYGBOPF_SET_AT_PATH

Set value at nested path (creating intermediate nodes)

FYGBOPF_PARSE

Parse YAML/JSON input

FYGBOPF_EMIT

Emit generic value as YAML/JSON

FYGBOPF_CONVERT

Convert to a different type

FYGBOPF_DONT_INTERNALIZE

Skip copying items into the builder arena

FYGBOPF_DEEP_VALIDATE

Recursively validate all elements

FYGBOPF_NO_CHECKS

Skip all input validity checks

FYGBOPF_PARALLEL

Execute in parallel using a thread pool

FYGBOPF_MAP_ITEM_COUNT

Interpret count as number of items, not pairs

FYGBOPF_BLOCK_FN

The function/callback is a Clang block (^)

FYGBOPF_CREATE_PATH

Create intermediate path nodes (like mkdir -p)

FYGBOPF_UNSIGNED

Integer scalar is unsigned (shares bit 23 with CREATE_PATH)

Description

The low 8 bits select the operation (use FYGBOPF_OP() / FYGBOPF_* opcode constants). The upper bits are modifier flags that refine behaviour.

Opcode values (low 8 bits via FYGBOPF_OP()):

fy_generic_op_args

fy_generic fy_generic_op_args(struct fy_generic_builder *gb, enum fy_gb_op_flags flags, fy_generic in, const struct fy_generic_op_args *args)

Execute a generic operation using a pre-filled args struct.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result (may be NULL for local/alloca operations)

  • flags (enum fy_gb_op_flags) – Opcode (low 8 bits) plus modifier flags

  • in (fy_generic) – Primary input collection or scalar; use fy_invalid / fy_seq_empty as appropriate

  • args (const struct fy_generic_op_args*) – Pointer to the filled fy_generic_op_args union

Description

Lower-level variant of fy_generic_op() for callers that prefer to fill a fy_generic_op_args union explicitly rather than using the variadic interface.

Return

The operation result, or fy_invalid on error or allocation failure.

fy_generic_op

fy_generic fy_generic_op(struct fy_generic_builder *gb, enum fy_gb_op_flags flags, ...)

Execute a generic operation using variadic arguments.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result

  • flags (enum fy_gb_op_flags) – Opcode (low 8 bits) plus modifier flags

  • ellipsis (ellipsis) – Operation-specific arguments (count, items, index, function, etc.)

Description

Dispatches to the appropriate collection or scalar operation selected by flags. The remaining variadic arguments are interpreted according to the opcode; see each FYGBOPF_* constant for the expected argument list.

Return

The operation result, or fy_invalid on error or allocation failure.

fy_gb_sequence_create

fy_generic fy_gb_sequence_create(struct fy_generic_builder *gb, size_t count, const fy_generic *items)

Create a sequence generic from an item array.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result

  • count (size_t) – Number of elements in items

  • items (const fy_generic*) – Array of fy_generic elements to include in the sequence

Return

A sequence fy_generic backed by the builder arena, or fy_invalid on error.

fy_gb_mapping_create

fy_generic fy_gb_mapping_create(struct fy_generic_builder *gb, size_t count, const fy_generic *pairs)

Create a mapping generic from a key/value pair array.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result

  • count (size_t) – Number of key/value PAIRS in pairs (i.e. half the array length)

  • pairs (const fy_generic*) – Interleaved key/value fy_generic array

Return

A mapping fy_generic backed by the builder arena, or fy_invalid on error.

fy_gb_indirect_create

fy_generic fy_gb_indirect_create(struct fy_generic_builder *gb, const fy_generic_indirect *gi)

Create an indirect generic wrapping metadata.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result

  • gi (const fy_generic_indirect*) – Pointer to the indirect descriptor to copy into the builder arena

Description

An indirect value carries an anchor, tag, style, or comment alongside the actual value without changing its logical type.

Return

An FYGT_INDIRECT fy_generic, or fy_invalid on error.

fy_gb_alias_create

fy_generic fy_gb_alias_create(struct fy_generic_builder *gb, fy_generic anchor)

Create an alias generic referencing an anchor value.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result

  • anchor (fy_generic) – The fy_generic value that serves as the anchor target

Return

An FYGT_ALIAS fy_generic, or fy_invalid on error.

macro fy_gb_sequence_value

fy_gb_sequence_value(_gb, ...)

Build a sequence fy_generic_value from variadic elements using a builder.

Parameters:

  • _gb – Builder

  • ellipsis (ellipsis) – Zero or more values of any supported C type

Description

Encodes each variadic argument via fy_gb_to_generic() (using _gb for out-of-place storage), then creates a sequence. With no arguments, returns fy_seq_empty_value.

Return

fy_generic_value of a sequence, or fy_seq_empty_value if no arguments.

macro fy_gb_sequence

fy_gb_sequence(_gb, ...)

Build a sequence fy_generic from variadic elements using a builder.

Parameters:

  • _gb – Builder

  • ellipsis (ellipsis) – Zero or more values of any supported C type

Description

Like fy_gb_sequence_value() but wraps the result in a fy_generic struct.

Return

A sequence fy_generic, or fy_seq_empty if no arguments.

macro fy_gb_mapping_value

fy_gb_mapping_value(_gb, ...)

Build a mapping fy_generic_value from variadic key/value pairs using a builder.

Parameters:

  • _gb – Builder

  • ellipsis (ellipsis) – Zero or more key/value pairs of any supported C type

Description

Arguments must be interleaved key/value pairs. With no arguments, returns fy_map_empty_value.

Return

fy_generic_value of a mapping, or fy_map_empty_value if no arguments.

macro fy_gb_mapping

fy_gb_mapping(_gb, ...)

Build a mapping fy_generic from variadic key/value pairs using a builder.

Parameters:

  • _gb – Builder

  • ellipsis (ellipsis) – Zero or more key/value pairs of any supported C type

Description

Like fy_gb_mapping_value() but wraps the result in a fy_generic struct.

Return

A mapping fy_generic, or fy_map_empty if no arguments.

fy_gb_create_scalar_from_text

fy_generic fy_gb_create_scalar_from_text(struct fy_generic_builder *gb, const char *text, size_t len, enum fy_generic_type force_type)

Parse a text scalar and create a typed generic.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that owns the result

  • text (const char*) – Pointer to the scalar text (not necessarily NUL-terminated)

  • len (size_t) – Length of text in bytes

  • force_type (enum fy_generic_type) – If != FYGT_INVALID, force this type instead of auto-detecting

Description

Interprets text as a YAML scalar value, optionally forcing a specific type. Useful for converting stringified values (e.g. from a config file) into the appropriate fy_generic representation.

Return

A fy_generic of the detected (or forced) type, or fy_invalid on error.

fy_gb_copy_out_of_place

fy_generic fy_gb_copy_out_of_place(struct fy_generic_builder *gb, fy_generic v)

Deep-copy an out-of-place generic into a builder arena.

Parameters:

  • gb (struct fy_generic_builder*) – Destination builder

  • v (fy_generic) – Out-of-place source value (must not be inplace or invalid)

Description

Recursively copies the value and all referenced data into gb‘s arena. This is the slow path; prefer fy_gb_copy() which skips the copy for inplace values.

Return

A new fy_generic backed by gb, or fy_invalid on allocation failure.

fy_gb_copy

fy_generic fy_gb_copy(struct fy_generic_builder *gb, fy_generic v)

Copy a generic into a builder arena, skipping inplace values.

Parameters:

  • gb (struct fy_generic_builder*) – Destination builder

  • v (fy_generic) – Source value

Description

If v is already stored inplace (no heap pointer), returns it unchanged. Otherwise delegates to fy_gb_copy_out_of_place().

Return

v unchanged if inplace, or a deep copy backed by gb on success, or fy_invalid on error.

fy_gb_internalize_out_of_place

fy_generic fy_gb_internalize_out_of_place(struct fy_generic_builder *gb, fy_generic v)

Intern an out-of-place generic if it lives outside the builder.

Parameters:

  • gb (struct fy_generic_builder*) – Target builder

  • v (fy_generic) – Out-of-place generic to potentially intern

Description

Copies v into gb‘s arena only if its pointer does not already fall within the builder’s allocated regions. If the value is already owned by gb, returns it unchanged.

Return

v (unchanged if already internal) or a copy in gb, or fy_invalid on error.

fy_gb_internalize

fy_generic fy_gb_internalize(struct fy_generic_builder *gb, fy_generic v)

Intern a generic into a builder, skipping inplace and invalid values.

Parameters:

  • gb (struct fy_generic_builder*) – Target builder

  • v (fy_generic) – Value to intern

Description

Fast path: returns v immediately if it is invalid or inplace. Otherwise delegates to fy_gb_internalize_out_of_place().

Return

v unchanged, or an interned copy in gb, or fy_invalid on error.

fy_validate_out_of_place

fy_generic fy_validate_out_of_place(fy_generic v)

Validate an out-of-place generic (no builder).

Parameters:

  • v (fy_generic) – Out-of-place generic to validate

Description

Checks structural and type consistency of v without a builder context. This is the slow path; prefer fy_validate() which skips validation for inplace and invalid values.

Return

v if valid, or fy_invalid if structural errors are found.

fy_validate

fy_generic fy_validate(fy_generic v)

Validate a generic, skipping inplace and invalid values.

Parameters:

Return

v unchanged if already invalid or inplace; otherwise the result of fy_validate_out_of_place().

fy_gb_validate_out_of_place

fy_generic fy_gb_validate_out_of_place(struct fy_generic_builder *gb, fy_generic v)

Validate an out-of-place generic using a builder context.

Parameters:

  • gb (struct fy_generic_builder*) – Builder providing schema context

  • v (fy_generic) – Out-of-place generic to validate

Description

Like fy_validate_out_of_place() but can use gb for schema information during validation.

Return

v if valid, or fy_invalid if errors are found.

fy_gb_validate

fy_generic fy_gb_validate(struct fy_generic_builder *gb, fy_generic v)

Validate a generic using a builder, skipping trivial cases.

Parameters:

  • gb (struct fy_generic_builder*) – Builder providing schema context

  • v (fy_generic) – Generic to validate

Return

v if already invalid or inplace; otherwise the result of fy_gb_validate_out_of_place().

fy_generic_relocate

fy_generic fy_generic_relocate(void *start, void *end, fy_generic v, ptrdiff_t d)

Adjust all pointers in a generic after a buffer realloc.

Parameters:

  • start (void*) – Old buffer start

  • end (void*) – Old buffer end (exclusive)

  • v (fy_generic) – Generic value to patch

  • d (ptrdiff_t) – Delta to add to pointers (new_base - old_base)

Description

When a backing buffer is reallocated (e.g. by mremap), all embedded pointers shift by d bytes. This function patches every pointer in v that falls within [@start, end) by adding d.

Return

The relocated fy_generic with updated pointers.

fy_gb_get_schema

enum fy_generic_schema fy_gb_get_schema(struct fy_generic_builder *gb)

Return the schema currently active in a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder to query

Return

The enum fy_generic_schema value configured for gb.

fy_gb_set_schema

void fy_gb_set_schema(struct fy_generic_builder *gb, enum fy_generic_schema schema)

Set the schema for a builder.

Parameters:

  • gb (struct fy_generic_builder*) – Builder to update

  • schema (enum fy_generic_schema) – New schema to use for subsequent operations

fy_gb_set_schema_from_parser_mode

int fy_gb_set_schema_from_parser_mode(struct fy_generic_builder *gb, enum fy_parser_mode parser_mode)

Derive and set the builder schema from a parser mode.

Parameters:

  • gb (struct fy_generic_builder*) – Builder to update

  • parser_mode (enum fy_parser_mode) – Parser mode whose schema to adopt

Description

Converts a fy_parser_mode value to the closest fy_generic_schema and calls fy_gb_set_schema().

Return

0 on success, -1 if parser_mode has no corresponding schema.

fy_generic_dump_primitive

void fy_generic_dump_primitive(FILE *fp, int level, fy_generic vv)

Dump a fy_generic value to a FILE stream for debugging.

Parameters:

  • fp (FILE*) – Destination FILE stream (e.g. stderr)

  • level (int) – Current indentation level (pass 0 for the top-level call)

  • vv (fy_generic) – Generic value to dump

Description

Recursively prints vv with indentation level to fp. Intended for development and debugging; output format is not stable.

macro fy_sequence_value

fy_sequence_value(...)

Build a sequence fy_generic_value from variadic elements.

Parameters:

  • ellipsis (ellipsis) – Optional builder followed by zero or more element values

Description

The first argument may optionally be a fy_generic_builder* (selects builder path) or a plain value (selects local/alloca path). With no arguments, returns fy_seq_empty_value.

Return

fy_generic_value of a sequence, or fy_seq_empty_value if empty.

macro fy_sequence

fy_sequence(...)

Build a sequence fy_generic from variadic elements.

Parameters:

  • ellipsis (ellipsis) – Optional builder followed by zero or more element values

Description

Wraps fy_sequence_value() in a fy_generic struct.

Return

A sequence fy_generic, or fy_seq_empty if empty.

macro fy_mapping_value

fy_mapping_value(...)

Build a mapping fy_generic_value from variadic key/value pairs.

Parameters:

  • ellipsis (ellipsis) – Optional builder followed by zero or more key/value pairs

Description

The first argument may optionally be a fy_generic_builder*. Arguments must be interleaved key/value pairs. With no arguments, returns fy_map_empty_value.

Return

fy_generic_value of a mapping, or fy_map_empty_value if empty.

macro fy_mapping

fy_mapping(...)

Build a mapping fy_generic from variadic key/value pairs.

Parameters:

  • ellipsis (ellipsis) – Optional builder followed by zero or more key/value pairs

Description

Wraps fy_mapping_value() in a fy_generic struct.

Return

A mapping fy_generic, or fy_map_empty if empty.

macro fy_value

fy_value(_maybe_gb, ...)

Encode a value as a fy_generic using a builder or alloca.

Parameters:

  • _maybe_gb – Either a fy_generic_builder* or a C value to encode

  • ellipsis (ellipsis) – Additional value args when _maybe_gb is a builder

Description

If _maybe_gb is a fy_generic_builder*, uses fy_gb_to_generic_value(). Otherwise treats _maybe_gb as the value itself.

Return

A fy_generic wrapping the encoded value.

macro fy_foreach

fy_foreach(_v, _col)

Iterate over every element (or key) of a collection.

Parameters:

  • _v – Loop variable (lvalue) that receives each element/key

  • _col – Collection to iterate (fy_generic sequence or mapping)

Description

For sequences: _v receives each element in order. For mappings: _v receives each key in order.

The type of _v determines how the element is cast via fy_get_key_at_typed().

macro FY_LOCAL_OP

FY_LOCAL_OP(...)

Execute a generic operation using a stack-allocated (alloca) builder.

Parameters:

  • ellipsis (ellipsis) – Same arguments as fy_generic_op() (flags, input, count, items, …)

Description

Creates a temporary fy_generic_builder backed by an alloca’d buffer and forwards the remaining arguments to fy_generic_op(). On allocation failure the buffer is doubled and the operation is retried until it either succeeds or the buffer would exceed FY_GENERIC_BUILDER_IN_PLACE_MAX_SIZE.

The stack frame is saved/restored around each retry so that failed attempts do not waste stack space. This is safe because all generic values are immutable and operations have no observable side-effects on failure.

Return

The operation result, or fy_invalid on error.

macro FY_GB_OR_LOCAL_OP

FY_GB_OR_LOCAL_OP(_gb_or_NULL, _flags, ...)

Dispatch to fy_generic_op or FY_LOCAL_OP based on _gb_or_NULL.

Parameters:

  • _gb_or_NULL – Builder pointer, or NULL to use FY_LOCAL_OP

  • _flags – Opcode + modifiers

  • ellipsis (ellipsis) – Remaining arguments forwarded unchanged

macro FY_GB_OR_LOCAL_COL

FY_GB_OR_LOCAL_COL(_flags, _gb_or_first, ...)

Dispatch a single-collection operation (no items array).

Parameters:

  • _flags – Opcode + modifiers

  • _gb_or_first – Optional builder or first collection arg

  • ellipsis (ellipsis) – Remaining args (usually the collection when _gb_or_first is a builder)

Description

The first non-builder argument is treated as the input collection.

macro FY_GB_OR_LOCAL_COL_COUNT_ITEMS

FY_GB_OR_LOCAL_COL_COUNT_ITEMS(_flags, _gb_or_first, ...)

Dispatch a collection+items operation.

Parameters:

  • _flags – Opcode + modifiers

  • _gb_or_first – Optional builder or first collection arg

  • ellipsis (ellipsis) – Collection (if builder given) + item arguments

Description

The first non-builder argument is the collection; remaining arguments are encoded as the items array.

macro FY_GB_OR_LOCAL_COL_IDX_COUNT_ITEMS

FY_GB_OR_LOCAL_COL_IDX_COUNT_ITEMS(_flags, _gb_or_first, ...)

Dispatch a collection+index+items operation.

Parameters:

  • _flags – Opcode + modifiers

  • _gb_or_first – Optional builder or first collection arg

  • ellipsis (ellipsis) – Collection, index, and item arguments

Description

The first non-builder argument is the collection, the second is the index, and remaining arguments are the items.

macro FY_GB_OR_LOCAL_SLICE

FY_GB_OR_LOCAL_SLICE(_flags, _gb_or_first, ...)

Dispatch a half-open slice [start, end) operation.

Parameters:

  • _flags – Opcode + modifier flags (e.g. FYGBOPF_SLICE).

  • _gb_or_first – Optional builder or first sequence argument.

  • ellipsis (ellipsis) – Sequence, start index (size_t), end index (size_t).

Description

Dispatches to a builder-backed or stack-local slice depending on whether a leading fy_generic_builder pointer is provided.

macro FY_GB_OR_LOCAL_SLICE_PY

FY_GB_OR_LOCAL_SLICE_PY(_flags, _gb_or_first, ...)

Dispatch a Python-style slice operation with signed indices.

Parameters:

  • _flags – Opcode + modifier flags (e.g. FYGBOPF_SLICE_PY).

  • _gb_or_first – Optional builder or first sequence argument.

  • ellipsis (ellipsis) – Sequence, start (ssize_t), end (ssize_t).

Description

Like FY_GB_OR_LOCAL_SLICE() but accepts signed (ssize_t) indices so that negative values count from the end of the sequence, matching Python slice semantics.

macro FY_GB_OR_LOCAL_SLICE_N

FY_GB_OR_LOCAL_SLICE_N(_flags, _gb_or_first, ...)

Dispatch a take-N or drop-N slice operation.

Parameters:

  • _flags – Opcode + modifier flags (e.g. FYGBOPF_TAKE or FYGBOPF_DROP).

  • _gb_or_first – Optional builder or first sequence argument.

  • ellipsis (ellipsis) – Sequence, count N (size_t).

Description

Dispatches to a builder-backed or stack-local take/drop depending on whether a leading fy_generic_builder pointer is provided.

fy_generic_emit_compact

int fy_generic_emit_compact(fy_generic v)

Emit a generic value to stdout in compact (flow-style) format.

Parameters:

Description

Formats v using flow style (all on one line) and writes the result to stdout. Intended primarily for quick debugging and interactive inspection.

Return

0 on success, -1 on error.

fy_generic_emit_default

int fy_generic_emit_default(fy_generic v)

Emit a generic value to stdout in default (block-style) format.

Parameters:

Description

Formats v using block style (multi-line indented) and writes the result to stdout. Intended primarily for quick debugging and interactive inspection.

Return

0 on success, -1 on error.

fy_generic_dir_get_document_count

int fy_generic_dir_get_document_count(fy_generic vdir)

Get the number of documents in a directory generic.

Parameters:

Description

A directory generic is a sequence produced by parsing with directory mode enabled. Each element is a vds (value-with-document-state) generic.

Return

The number of documents, or -1 on error.

fy_generic_dir_get_document_vds

fy_generic fy_generic_dir_get_document_vds(fy_generic vdir, size_t idx)

Get the vds generic for a document at a given index.

Parameters:

  • vdir (fy_generic) – The directory generic.

  • idx (size_t) – Zero-based document index.

Description

Returns the combined (root, document-state) generic for the document at position idx within the directory vdir.

Return

The vds fy_generic for the requested document, or fy_invalid on error.

fy_generic_vds_get_root

fy_generic fy_generic_vds_get_root(fy_generic vds)

Extract the root value from a document-with-state generic.

Parameters:

  • vds (fy_generic) – The document-with-state generic.

Description

A vds generic bundles the document root together with its YAML document state. This function returns only the root value portion.

Return

The root fy_generic, or fy_invalid on error.

fy_generic_vds_get_document_state

struct fy_document_state *fy_generic_vds_get_document_state(fy_generic vds)

Extract the YAML document state from a vds generic.

Parameters:

  • vds (fy_generic) – The document-with-state generic.

Description

A vds generic bundles the document root together with its YAML document state. This function returns the associated fy_document_state pointer (version, tags, schema, etc.).

Return

Pointer to the fy_document_state, or NULL on error.

fy_generic_vds_create_from_document_state

fy_generic fy_generic_vds_create_from_document_state(struct fy_generic_builder *gb, fy_generic vroot, struct fy_document_state *fyds)

Bundle a root value and document state into a vds generic.

Parameters:

  • gb (struct fy_generic_builder*) – Builder that will own the resulting vds generic.

  • vroot (fy_generic) – The document root generic.

  • fyds (struct fy_document_state*) – The YAML document state (version, tags, schema information).

Description

Creates a document-with-state (vds) generic by combining vroot with fyds into a mapping generic backed by the builder gb.

Return

The vds fy_generic, or fy_invalid on error.

enum fy_generic_iterator_cfg_flags

enum fy_generic_iterator_cfg_flags

Document iterator configuration flags

Definition

enum fy_generic_iterator_cfg_flags {
    FYGICF_WANT_BODY_EVENTS,
    FYGICF_WANT_DOCUMENT_BODY_EVENTS,
    FYGICF_WANT_STREAM_DOCUMENT_BODY_EVENTS,
    FYGICF_HAS_FULL_DIRECTORY,
    FYGICF_STRIP_LABELS,
    FYGICF_STRIP_TAGS,
    FYGICF_STRIP_COMMENTS,
    FYGICF_STRIP_STYLE,
    FYGICF_STRIP_FAILSAFE_STR
};

Constants

FYGICF_WANT_BODY_EVENTS

Generate body events

FYGICF_WANT_DOCUMENT_BODY_EVENTS

Generate document and body events

FYGICF_WANT_STREAM_DOCUMENT_BODY_EVENTS

Generate stream, document and body events

FYGICF_HAS_FULL_DIRECTORY

Full directory contents of vdir

FYGICF_STRIP_LABELS

Strip the labels (anchors)

FYGICF_STRIP_TAGS

Strip the tags

FYGICF_STRIP_COMMENTS

Strip comments from the output

FYGICF_STRIP_STYLE

Strip style information from the output

FYGICF_STRIP_FAILSAFE_STR

Strip failsafe schema plain string tags

Description

These flags control the operation of the document iterator

struct fy_generic_iterator_cfg

struct fy_generic_iterator_cfg

document iterator configuration structure.

Definition

struct fy_generic_iterator_cfg {
    enum fy_generic_iterator_cfg_flags flags;
    fy_generic vdir;
}

Members

flags

The document iterator flags

vdir

The directory of the parsed input

Description

Argument to the fy_generic_iterator_create_cfg() method.

fy_generic_iterator_create

struct fy_generic_iterator *fy_generic_iterator_create(void)

Create a document iterator

Parameters:

  • void – no arguments

Description

Creates a document iterator, that can trawl through a document without using recursion.

Return

The newly created document iterator or NULL on error

fy_generic_iterator_create_cfg

struct fy_generic_iterator *fy_generic_iterator_create_cfg(const struct fy_generic_iterator_cfg *cfg)

Create a document iterator using config

Parameters:

Description

Creates a document iterator, that can trawl through a document without using recursion. The iterator will generate all the events that created the given document starting at iterator root.

Return

The newly created document iterator or NULL on error

fy_generic_iterator_destroy

void fy_generic_iterator_destroy(struct fy_generic_iterator *fygi)

Destroy the given document iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to destroy

Description

Destroy a document iterator created earlier via fy_generic_iterator_create().

fy_generic_iterator_event_free

void fy_generic_iterator_event_free(struct fy_generic_iterator *fygi, struct fy_event *fye)

Free an event that was created by a document iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator that created the event

  • fye (struct fy_event*) – The event

Description

Free (possibly recycling) an event that was created by a document iterator.

fy_generic_iterator_stream_start

struct fy_event *fy_generic_iterator_stream_start(struct fy_generic_iterator *fygi)

Create a stream start event using the iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to create the event

Description

Creates a stream start event on the document iterator and advances the internal state of it accordingly.

Return

The newly created stream start event, or NULL on error.

fy_generic_iterator_stream_end

struct fy_event *fy_generic_iterator_stream_end(struct fy_generic_iterator *fygi)

Create a stream end event using the iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to create the event

Description

Creates a stream end event on the document iterator and advances the internal state of it accordingly.

Return

The newly created stream end event, or NULL on error.

fy_generic_iterator_document_start

struct fy_event *fy_generic_iterator_document_start(struct fy_generic_iterator *fygi, fy_generic vds)

Create a document start event using the iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to create the event

  • vds (fy_generic) – The generic directory (or fy_null for none)

Description

Creates a document start event on the document iterator and advances the internal state of it accordingly. The document must not be released until an error, cleanup or a call to fy_generic_iterator_document_end().

Return

The newly created document start event, or NULL on error.

fy_generic_iterator_document_end

struct fy_event *fy_generic_iterator_document_end(struct fy_generic_iterator *fygi)

Create a document end event using the iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to create the event

Description

Creates a document end event on the document iterator and advances the internal state of it accordingly. The document that was used earlier in the call of fy_generic_iterator_document_start() can now be released.

Return

The newly created document end event, or NULL on error.

fy_generic_iterator_body_next

struct fy_event *fy_generic_iterator_body_next(struct fy_generic_iterator *fygi)

Create document body events until the end

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to create the event

Description

Creates the next document body, depth first until the end of the document. The events are created depth first and are in same exact sequence that the original events that created the document.

That means that the finite event stream that generated the document is losslesly preserved in such a way that the document tree representation is functionally equivalent.

Repeated calls to this function will generate a stream of SCALAR, ALIAS, SEQUENCE START, SEQUENCE END, MAPPING START and MAPPING END events, returning NULL at the end of the body event stream.

Return

The newly created document body event or NULL at an error, or an end of the event stream. Use fy_generic_iterator_get_error() to check if an error occured.

fy_generic_iterator_generic_start

void fy_generic_iterator_generic_start(struct fy_generic_iterator *fygi, fy_generic v)

Start a document node iteration run using a starting point

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to run with

  • v (fy_generic) – The generic to start on

Description

Starts an iteration run starting at the given node.

fy_generic_iterator_generic_next

fy_generic fy_generic_iterator_generic_next(struct fy_generic_iterator *fygi)

Return the next node in the iteration sequence

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to use for the iteration

Description

Returns a pointer to the next node iterating using as a start the node given at fy_generic_iterator_node_start(). The first node returned will be that, followed by all the remaing nodes in the subtree.

Return

The next node in the iteration sequence or NULL at the end, or if an error occured.

fy_generic_iterator_generate_next

struct fy_event *fy_generic_iterator_generate_next(struct fy_generic_iterator *fygi)

Create events from document iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to create the event

Description

This is a method that will handle the complex state of generating stream, document and body events on the given iterator.

When generation is complete a NULL event will be generated.

Return

The newly created event or NULL at an error, or an end of the event stream. Use fy_generic_iterator_get_error() to check if an error occured.

fy_generic_iterator_get_error

bool fy_generic_iterator_get_error(struct fy_generic_iterator *fygi)

Get the error state of the document iterator

Parameters:

  • fygi (struct fy_generic_iterator*) – The document iterator to use for checking it’s error state.

Description

Returns the error state of the iterator. If it’s in error state, return true and reset the iterator to the state just after creation.

Return

true if it was in an error state, false otherwise.

fy_parser_set_generic_iterator

int fy_parser_set_generic_iterator(struct fy_parser *fyp, enum fy_parser_event_generator_flags flags, struct fy_generic_iterator *fygi)

Associate a parser with a document iterator

Parameters:

  • fyp (struct fy_parser*) – The parser

  • flags (enum fy_parser_event_generator_flags) – The event generation flags

  • fygi (struct fy_generic_iterator*) – The document iterator to associate

Description

Associate a parser with a generic iterator, that is instead of parsing the events will be generated by the generic iterator.

Return

0 on success, -1 on error