.\" Man page generated from reStructuredText .\" by the Docutils 0.22.4 manpage writer. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "LIBFYAML-GENERICS" "3" "Mar 18, 2026" "1.0.0" "libfyaml" .SH NAME libfyaml-generics \- libfyaml generic API .SH INTRODUCTION .sp For an overview of the generic runtime, read Generics Guide \%<> first. It uses \fBfy_generic\fP as the starting point, then covers the runtime type model, schema choices, and lifetime rules assumed by the API reference below. .SH GENERIC STORAGE TYPES .INDENT 0.0 .TP .B type fy_generic_indirect Wrapper attaching YAML metadata to a generic value. .sp An indirect is allocated out\-of\-place and pointed to by a tagged \fBfy_generic\fP word with type tag \fBFY_INDIRECT_V\fP\&. It stores the actual value plus optional metadata controlled by the \fBFYGIF_*\fP flag bits. An alias is encoded as an indirect with \fBvalue\fP set to \fBfy_invalid\fP and \fBanchor\fP holding the alias target name. .UNINDENT .INDENT 0.0 .TP .B type fy_generic_sequence Out\-of\-place storage for a generic sequence. .sp A contiguous block of \fBcount\fP \fBfy_generic\fP items follows the header. The allocation must remain 16\-byte aligned; the layout is shared with \fBfy_generic_collection\fP and is relied on by low\-level generic helpers. .UNINDENT .INDENT 0.0 .TP .B type fy_generic_mapping Out\-of\-place storage for a generic mapping. .sp Stores \fBcount\fP key/value pairs as a contiguous flexible array of \fBfy_generic_map_pair\fP elements. The allocation must remain 16\-byte aligned. .UNINDENT .INDENT 0.0 .TP .B type fy_generic_collection Generic view over a sequence or mapping buffer. .sp Shares the same memory layout as \fBfy_generic_sequence\fP; for mappings, \fBcount\fP is the number of pairs and \fBitems\fP contains \fB2 * count\fP interleaved key/value generics. .UNINDENT .SH GENERIC TYPE SYSTEM .sp 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. .sp The core type is \fBfy_generic\fP, a single machine word (64 or 32 bit) that encodes one of nine value types via pointer tagging: .INDENT 0.0 .IP \(bu 2 \fBnull\fP, \fBbool\fP, \fBint\fP, \fBfloat\fP, \fBstring\fP — scalar types .IP \(bu 2 \fBsequence\fP, \fBmapping\fP — ordered arrays and key/value collections .IP \(bu 2 \fBindirect\fP, \fBalias\fP — YAML\-specific wrappers (anchor, tag, style, …) .UNINDENT .sp 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. .sp \fBThree API tiers for different storage lifetimes\fP: .sp \fIStack\-based\fP (\fBfy_sequence(…)\fP, \fBfy_mapping(…)\fP, \fBfy_to_generic(x)\fP): values live for the duration of the enclosing function. C11 \fB_Generic\fP dispatch automatically selects the right conversion from native C types. Zero heap allocation for scalars and small composite values: .INDENT 0.0 .INDENT 3.5 .sp .EX fy_generic config = fy_mapping( \(dqhost\(dq, \(dqlocalhost\(dq, \(dqport\(dq, 8080, \(dqtls\(dq, true); .EE .UNINDENT .UNINDENT .sp \fILow\-level\fP (\fBfy_sequence_alloca()\fP, \fBfy_mapping_alloca()\fP): build from pre\-constructed \fBfy_generic\fP arrays; the caller controls all allocation. .sp \fIBuilder\fP (\fBfy_gb_sequence()\fP, \fBfy_gb_mapping()\fP): fy allocator created values that survive beyond the current function. Automatically internalises any stack\-based sub\-values passed to it. .sp \fBImmutability and thread safety\fP: 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. .sp \fBConversion\fP: \fBfy_document_to_generic()\fP and \fBfy_generic_to_document()\fP 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. .SS enum fy_generic_type .INDENT 0.0 .TP .B enum fy_generic_type Type discriminator for fy_generic values. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_generic_type { FYGT_INVALID, FYGT_NULL, FYGT_BOOL, FYGT_INT, FYGT_FLOAT, FYGT_STRING, FYGT_SEQUENCE, FYGT_MAPPING, FYGT_INDIRECT, FYGT_ALIAS }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGT_INVALID Sentinel representing an invalid or unset value. .TP .B FYGT_NULL YAML/JSON null. .TP .B FYGT_BOOL Boolean (true or false). .TP .B FYGT_INT Signed or unsigned integer. .TP .B FYGT_FLOAT Floating\-point (double). .TP .B FYGT_STRING UTF\-8 string. .TP .B FYGT_SEQUENCE Ordered sequence of generic values. .TP .B FYGT_MAPPING Key/value mapping of generic values. .TP .B FYGT_INDIRECT Value wrapped with metadata (anchor, tag, style, …). .TP .B FYGT_ALIAS YAML alias (anchor reference). .UNINDENT .SS Description .sp Identifies the runtime type stored in an \fBstruct fy_generic\fP word. The ordering INT < FLOAT < STRING must be preserved; internal bithacks depend on consecutive placement. .SS fy_generic_type_is_scalar .INDENT 0.0 .TP .B bool fy_generic_type_is_scalar(const enum fy_generic_type type) Test whether a type is a scalar type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (const enum fy_generic_type) – The type to test. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBtype\fP is one of \fBFYGT_NULL\fP, \fBFYGT_BOOL\fP, \fBFYGT_INT\fP, \fBFYGT_FLOAT\fP, or \fBFYGT_STRING\fP; false otherwise. .SS fy_generic_type_is_collection .INDENT 0.0 .TP .B bool fy_generic_type_is_collection(const enum fy_generic_type type) Test whether a type is a collection type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (const enum fy_generic_type) – The type to test. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBtype\fP is \fBFYGT_SEQUENCE\fP or \fBFYGT_MAPPING\fP; false otherwise. .SS enum fy_generic_type_mask .INDENT 0.0 .TP .B enum fy_generic_type_mask Bitmask constants for sets of generic types. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGTM_INVALID Bit for \fBFYGT_INVALID\fP\&. .TP .B FYGTM_NULL Bit for \fBFYGT_NULL\fP\&. .TP .B FYGTM_BOOL Bit for \fBFYGT_BOOL\fP\&. .TP .B FYGTM_INT Bit for \fBFYGT_INT\fP\&. .TP .B FYGTM_FLOAT Bit for \fBFYGT_FLOAT\fP\&. .TP .B FYGTM_STRING Bit for \fBFYGT_STRING\fP\&. .TP .B FYGTM_SEQUENCE Bit for \fBFYGT_SEQUENCE\fP\&. .TP .B FYGTM_MAPPING Bit for \fBFYGT_MAPPING\fP\&. .TP .B FYGTM_INDIRECT Bit for \fBFYGT_INDIRECT\fP\&. .TP .B FYGTM_ALIAS Bit for \fBFYGT_ALIAS\fP\&. .TP .B FYGTM_COLLECTION Combined mask for sequences and mappings. .TP .B FYGTM_SCALAR Combined mask for all scalar types (null through string). .TP .B FYGTM_ANY Combined mask for all non\-invalid, non\-alias types. .UNINDENT .SS Description .sp Each enumerator is a single bit corresponding to the matching \fBenum fy_generic_type\fP value. Combine them with bitwise OR to test for membership in a set of types. .SS typedef fy_generic_value .INDENT 0.0 .TP .B type fy_generic_value Unsigned word used as the raw tagged\-pointer storage. .UNINDENT .SS Description .sp 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. .SS typedef fy_generic_value_signed .INDENT 0.0 .TP .B type fy_generic_value_signed Signed variant of fy_generic_value. .UNINDENT .SS Description .sp Used when arithmetic sign\-extension of the raw word is needed, e.g. when decoding inplace signed integers. .SS macro FY_STRING_SHIFT7 .INDENT 0.0 .TP .B FY_STRING_SHIFT7(_v0, _v1, _v2, _v3, _v4, _v5, _v6) Build a 7\-byte inplace string encoding word (64\-bit). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v0\fP – First character byte (or 0 for padding). .IP \(bu 2 \fB_v1\fP – Second character byte. .IP \(bu 2 \fB_v2\fP – Third character byte. .IP \(bu 2 \fB_v3\fP – Fourth character byte. .IP \(bu 2 \fB_v4\fP – Fifth character byte. .IP \(bu 2 \fB_v5\fP – Sixth character byte. .IP \(bu 2 \fB_v6\fP – Seventh character byte. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Packs up to seven character bytes into the upper 56 bits of a \fBstruct fy_generic_value\fP 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. .SS Return .sp A fy_generic_value with the seven bytes packed in, ready to be OR\-ed with the type tag and string length. .SS macro FY_STRING_SHIFT3 .INDENT 0.0 .TP .B FY_STRING_SHIFT3(_v0, _v1, _v2) Build a 3\-byte inplace string encoding word (32\-bit). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v0\fP – First character byte (or 0 for padding). .IP \(bu 2 \fB_v1\fP – Second character byte. .IP \(bu 2 \fB_v2\fP – Third character byte. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Packs up to three character bytes into the upper 24 bits of a \fBstruct fy_generic_value\fP, leaving the low 8 bits free for tag and length. Endian\-specific like \fBFY_STRING_SHIFT7()\fP\&. .SS Return .sp A fy_generic_value with the three bytes packed in. .SS macro FY_MAX_ALIGNOF .INDENT 0.0 .TP .B FY_MAX_ALIGNOF(_v, _min) Return the larger of _Alignof(@_v) and \fB_min\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Expression whose alignment is queried. .IP \(bu 2 \fB_min\fP – Minimum alignment to enforce. .UNINDENT .UNINDENT .UNINDENT .SS Note .sp evaluates \fB_v\fP twice; avoid expressions with side\-effects. .SS Return .sp The larger of _Alignof(@_v) and \fB_min\fP as a size_t. .SS typedef fy_generic .INDENT 0.0 .TP .B type fy_generic A space\-efficient tagged\-union value. .UNINDENT .SS Description .sp 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. .sp Access the raw word via .v (unsigned) or .vs (signed). Always use the provided accessor functions rather than reading the raw fields. .SS fy_generic_is_direct .INDENT 0.0 .TP .B bool fy_generic_is_direct(fy_generic v) Test whether a generic value is encoded directly. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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). .SS Return .sp true if \fBv\fP is not an indirect (no wrapping metadata); false otherwise. .SS fy_generic_is_indirect .INDENT 0.0 .TP .B bool fy_generic_is_indirect(fy_generic v) Test whether a generic value is an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp An indirect points to a \fBstruct fy_generic_indirect\fP holding the actual value plus optional metadata (anchor, tag, style, diagnostics, …). .SS Return .sp true if \fBv\fP is an indirect (%FYGT_INDIRECT); false otherwise. .SS fy_generic_is_direct_valid .INDENT 0.0 .TP .B bool fy_generic_is_direct_valid(const fy_generic v) Test whether a direct generic value is not invalid. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Only meaningful for direct (non\-indirect) values. .SS Return .sp true if \fBv\fP is not the \fBfy_invalid\fP sentinel; false if it is. .SS fy_generic_is_direct_invalid .INDENT 0.0 .TP .B bool fy_generic_is_direct_invalid(const fy_generic v) Test whether a direct generic value is invalid. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Only meaningful for direct (non\-indirect) values. .SS Return .sp true if \fBv\fP equals the \fBfy_invalid\fP sentinel; false otherwise. .SS fy_generic_resolve_ptr .INDENT 0.0 .TP .B const void *fy_generic_resolve_ptr(fy_generic ptr) Extract the raw pointer from a non\-collection generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBptr\fP (fy_generic) – An out\-of\-place non\-collection generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Strips the 3\-bit type tag from \fBptr\fP to recover the original aligned pointer for out\-of\-place scalars (int, float, string, indirect). Not valid for collection values — use \fBfy_generic_resolve_collection_ptr()\fP instead. .SS Return .sp The 8\-byte\-aligned pointer stored in \fBptr\fP\&. .SS fy_generic_resolve_collection_ptr .INDENT 0.0 .TP .B const void *fy_generic_resolve_collection_ptr(fy_generic ptr) Extract the raw pointer from a collection generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBptr\fP (fy_generic) – An out\-of\-place sequence or mapping generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Strips the 4\-bit collection mask (type tag + collection discriminator bit) from \fBptr\fP to recover the 16\-byte\-aligned pointer for sequences and mappings. .SS Return .sp The 16\-byte\-aligned pointer stored in \fBptr\fP\&. .SS fy_generic_relocate_ptr .INDENT 0.0 .TP .B fy_generic fy_generic_relocate_ptr(fy_generic v, ptrdiff_t d) Adjust an out\-of\-place scalar pointer by a byte delta. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An out\-of\-place non\-collection generic value. .IP \(bu 2 \fBd\fP (ptrdiff_t) – Byte delta to add to the embedded pointer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Adds \fBd\fP to the pointer embedded in \fBv\fP while preserving the type tag. Used when moving the backing buffer (e.g. realloc). Asserts that the resulting pointer is still correctly aligned. .SS Return .sp A new \fBstruct fy_generic\fP with the adjusted pointer and the same type tag. .SS fy_generic_relocate_collection_ptr .INDENT 0.0 .TP .B fy_generic fy_generic_relocate_collection_ptr(fy_generic v, ptrdiff_t d) Adjust a collection pointer by a byte delta. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An out\-of\-place sequence or mapping generic value. .IP \(bu 2 \fBd\fP (ptrdiff_t) – Byte delta to add to the embedded pointer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_generic_relocate_ptr()\fP but for sequence and mapping values, stripping and restoring the wider 4\-bit collection mask. .SS Return .sp A new \fBstruct fy_generic\fP with the adjusted pointer and the same collection tag. .SS fy_generic_get_direct_type_table .INDENT 0.0 .TP .B enum fy_generic_type fy_generic_get_direct_type_table(fy_generic v) Determine the type of a direct generic (table lookup). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A direct (non\-indirect) generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses a 16\-entry lookup table indexed by the low 4 bits of \fBv\fP to classify the value. Handles escape codes for null, true, and false. Prefer \fBfy_generic_get_direct_type_bithack()\fP in hot paths. .SS Return .sp The \fBenum fy_generic_type\fP of \fBv\fP, or \fBFYGT_INVALID\fP for unknown escape codes. .SS fy_generic_get_direct_type_bithack .INDENT 0.0 .TP .B enum fy_generic_type fy_generic_get_direct_type_bithack(fy_generic v) Determine the type of a direct generic (bithack). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A direct (non\-indirect) generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfy_generic_get_direct_type()\fP\&. .SS Return .sp The \fBenum fy_generic_type\fP of \fBv\fP, or \fBFYGT_INVALID\fP for unknown escape codes. .SS fy_generic_is_in_place_normal .INDENT 0.0 .TP .B bool fy_generic_is_in_place_normal(fy_generic v) Test whether a generic value is stored inplace (switch impl). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns true when the entire value fits inside the word with no external allocation. Uses a readable switch\-based approach; prefer \fBfy_generic_is_in_place_bithack()\fP in hot paths. .SS Return .sp true if \fBv\fP requires no heap/stack allocation; false otherwise. .SS fy_generic_is_in_place_bithack .INDENT 0.0 .TP .B bool fy_generic_is_in_place_bithack(fy_generic v) Test whether a generic value is stored inplace (bithack). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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). .SS Return .sp true if \fBv\fP requires no heap/stack allocation; false otherwise. .SS fy_generic_is_in_place .INDENT 0.0 .TP .B bool fy_generic_is_in_place(fy_generic v) Test whether a generic value is stored inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to test. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Preferred alias for \fBfy_generic_is_in_place_bithack()\fP\&. .SS Return .sp true if \fBv\fP requires no heap/stack allocation; false otherwise. .SS fy_generic_get_type_indirect .INDENT 0.0 .TP .B enum fy_generic_type fy_generic_get_type_indirect(fy_generic v) Get the type of an indirect generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dereferences the \fBstruct fy_generic_indirect\fP to read the type of the wrapped value. Only call this when \fBfy_generic_is_indirect()\fP returns true. .SS Return .sp The \fBenum fy_generic_type\fP of the value wrapped by the indirect. .SS fy_generic_indirect_get .INDENT 0.0 .TP .B void fy_generic_indirect_get(fy_generic v, fy_generic_indirect *gi) Populate a fy_generic_indirect from an indirect value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .IP \(bu 2 \fBgi\fP (fy_generic_indirect*) – Pointer to a caller\-allocated \fBstruct fy_generic_indirect\fP to receive the data. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Copies all fields of the \fBstruct fy_generic_indirect\fP pointed to by \fBv\fP into \fBgi\fP\&. .SS fy_genericp_indirect_get_valuep_nocheck .INDENT 0.0 .TP .B const fy_generic *fy_genericp_indirect_get_valuep_nocheck(const fy_generic *vp) Get a pointer to the value inside an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to an indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns a pointer into the \fBstruct fy_generic_indirect\fP‘s \fBvalue\fP field without validating that \fBFYGIF_VALUE\fP is set. Only use when the flag is known to be set. .SS Return .sp Pointer to the \fBvalue\fP field of the underlying \fBstruct fy_generic_indirect\fP\&. .SS fy_genericp_indirect_get_valuep .INDENT 0.0 .TP .B const fy_generic *fy_genericp_indirect_get_valuep(const fy_generic *vp) Get a pointer to the value inside an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to an indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_genericp_indirect_get_valuep_nocheck()\fP but checks that \fBvp\fP is a valid indirect and that \fBFYGIF_VALUE\fP is set; returns NULL on failure. .SS Return .sp Pointer to the \fBvalue\fP field, or NULL if \fBvp\fP is not a valid indirect with a value. .SS fy_generic_indirect_get_value_nocheck .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_value_nocheck(const fy_generic v) Get the value wrapped by an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dereferences the indirect without checking flags. Only use when \fBFYGIF_VALUE\fP is known to be set. .SS Return .sp The wrapped \fBstruct fy_generic\fP value. .SS fy_generic_indirect_get_value .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_value(const fy_generic v) Get the value wrapped by an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks that \fBv\fP is a valid indirect with \fBFYGIF_VALUE\fP set. .SS Return .sp The wrapped \fBstruct fy_generic\fP value, or \fBfy_invalid\fP if not available. .SS fy_generic_indirect_get_anchor .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_anchor(fy_generic v) Get the anchor from an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The anchor as a string \fBstruct fy_generic\fP, or \fBfy_null\fP if \fBFYGIF_ANCHOR\fP is not set. .SS fy_generic_indirect_get_tag .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_tag(fy_generic v) Get the tag from an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The tag as a string \fBstruct fy_generic\fP, or \fBfy_null\fP if \fBFYGIF_TAG\fP is not set. .SS fy_generic_indirect_get_diag .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_diag(fy_generic v) Get the diagnostics from an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The diagnostics as a \fBstruct fy_generic\fP, or \fBfy_null\fP if \fBFYGIF_DIAG\fP is not set. .SS fy_generic_indirect_get_marker .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_marker(fy_generic v) Get the source\-position marker from an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The marker as a \fBstruct fy_generic\fP, or \fBfy_null\fP if \fBFYGIF_MARKER\fP is not set. .SS fy_generic_indirect_get_style .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_style(fy_generic v) Get the source style from an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The style as a \fBstruct fy_generic\fP, or \fBfy_null\fP if \fBFYGIF_STYLE\fP is not set. .SS fy_generic_indirect_get_comment .INDENT 0.0 .TP .B fy_generic fy_generic_indirect_get_comment(fy_generic v) Get the attached comment from an indirect. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – An indirect generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The comment as a \fBstruct fy_generic\fP, or \fBfy_null\fP if \fBFYGIF_COMMENT\fP is not set. .SS fy_generic_get_anchor .INDENT 0.0 .TP .B fy_generic fy_generic_get_anchor(fy_generic v) Get the anchor from any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both direct and indirect values; for direct values there is no anchor, so \fBfy_null\fP is returned. .SS Return .sp The anchor string \fBstruct fy_generic\fP, or \fBfy_null\fP if none. .SS fy_generic_get_tag .INDENT 0.0 .TP .B fy_generic fy_generic_get_tag(fy_generic v) Get the tag from any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The tag string \fBstruct fy_generic\fP, or \fBfy_null\fP if none. .SS fy_generic_get_diag .INDENT 0.0 .TP .B fy_generic fy_generic_get_diag(fy_generic v) Get the diagnostics from any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The diagnostics \fBstruct fy_generic\fP, or \fBfy_null\fP if none. .SS fy_generic_get_marker .INDENT 0.0 .TP .B fy_generic fy_generic_get_marker(fy_generic v) Get the source\-position marker from any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The marker \fBstruct fy_generic\fP, or \fBfy_null\fP if none. .SS fy_generic_get_style .INDENT 0.0 .TP .B fy_generic fy_generic_get_style(fy_generic v) Get the source style from any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The style \fBstruct fy_generic\fP, or \fBfy_null\fP if none. .SS fy_generic_get_comment .INDENT 0.0 .TP .B fy_generic fy_generic_get_comment(fy_generic v) Get the attached comment from any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The comment \fBstruct fy_generic\fP, or \fBfy_null\fP if none. .SS fy_generic_get_type .INDENT 0.0 .TP .B enum fy_generic_type fy_generic_get_type(fy_generic v) Get the type of any generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Any generic value (direct or indirect). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to the indirect or direct type accessor as appropriate. This is the preferred single entry\-point for type queries. .SS Return .sp The \fBenum fy_generic_type\fP of \fBv\fP\&. .SS typedef fy_generic_map_pair .INDENT 0.0 .TP .B type fy_generic_map_pair A key/value pair within a generic mapping. .UNINDENT .SS Description .sp The union allows access either as named \fBkey\fP / \fBvalue\fP fields or as a two\-element \fBitems\fP array (index 0 = key, index 1 = value). Do not change the layout — code iterates mappings as flat item arrays. .SS typedef fy_generic_sized_string .INDENT 0.0 .TP .B type fy_generic_sized_string A string with an explicit byte count. .UNINDENT .SS Description .sp Used when passing strings that may contain embedded NUL bytes or when avoiding a \fBstrlen()\fP call. The \fBdata\fP pointer and \fBsize\fP byte count need not be NUL\-terminated. .SS typedef fy_generic_decorated_int .INDENT 0.0 .TP .B type fy_generic_decorated_int An integer paired with encoding flags. .UNINDENT .SS Description .sp Wraps a 64\-bit integer value with a \fBflags\fP 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 \fBsv\fP (signed) or \fBuv\fP (unsigned). The value union must be first for correct ABI — do not reorder. .SS fy_sequence_storage_size .INDENT 0.0 .TP .B size_t fy_sequence_storage_size(const size_t count) Compute bytes needed for a sequence of \fBcount\fP items. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcount\fP (const size_t) – Number of items. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Computes the total allocation size for a \fBstruct fy_generic_sequence\fP header plus \fBcount\fP \fBstruct fy_generic\fP items, checking for overflow. .SS Return .sp The required byte count, or \fBSIZE_MAX\fP on integer overflow. .SS fy_mapping_storage_size .INDENT 0.0 .TP .B size_t fy_mapping_storage_size(const size_t count) Compute bytes needed for a mapping of \fBcount\fP pairs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcount\fP (const size_t) – Number of key/value pairs. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Computes the total allocation size for a \fBstruct fy_generic_mapping\fP header plus \fBcount\fP \fBstruct fy_generic_map_pair\fP entries, checking for overflow. .SS Return .sp The required byte count, or \fBSIZE_MAX\fP on integer overflow. .SS fy_collection_storage_size .INDENT 0.0 .TP .B size_t fy_collection_storage_size(bool is_map, const size_t count) Compute bytes for a sequence or mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBis_map\fP (bool) – true for a mapping, false for a sequence. .IP \(bu 2 \fBcount\fP (const size_t) – Number of items (pairs for mappings). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to \fBfy_sequence_storage_size()\fP or \fBfy_mapping_storage_size()\fP depending on \fBis_map\fP\&. .SS Return .sp The required byte count, or \fBSIZE_MAX\fP on integer overflow. .SS macro fy_generic_typeof .INDENT 0.0 .TP .B fy_generic_typeof(_v) Yield the canonical C type for a generic\-compatible expression. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – An expression whose type is to be normalised. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses C11 _Generic to map \fB_v\fP to its canonical type: char* and const char* pass through unchanged, fy_generic_builder* passes through, and everything else yields the type of \fB_v\fP itself. Used internally to normalise argument types before encoding them as fy_generic values. .SS Return .sp An expression of the canonical type (for use with __typeof__). .SS fy_generic_is_valid .INDENT 0.0 .TP .B bool fy_generic_is_valid(const fy_generic v) Test whether any generic value is not invalid. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both direct and indirect values. For an indirect, the wrapped value is checked. .SS Return .sp true if \fBv\fP (or its wrapped value for indirects) is not \fBfy_invalid\fP\&. .SS fy_generic_is_invalid .INDENT 0.0 .TP .B bool fy_generic_is_invalid(const fy_generic v) Test whether any generic value is invalid. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – Any generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both direct and indirect values. For an indirect, the wrapped value is checked. .SS Return .sp true if \fBv\fP (or its wrapped value for indirects) equals \fBfy_invalid\fP\&. .SS macro FY_GENERIC_IS_TEMPLATE_INLINE .INDENT 0.0 .TP .B FY_GENERIC_IS_TEMPLATE_INLINE(_gtype) Generate inline type\-check functions for a generic type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gtype\fP – Type suffix (e.g. null_type, bool_type, int_type, string, sequence, …). .UNINDENT .UNINDENT .UNINDENT .SS Description .INDENT 0.0 .TP .B Instantiates three functions for the type suffix \fB_gtype\fP: .INDENT 7.0 .IP \(bu 2 fy_generic_is_indirect_##_gtype##_nocheck(): checks the type of an indirect’s wrapped value without validating that the indirect flag is set. .IP \(bu 2 fy_generic_is_indirect_##_gtype(): safe version with validation. .IP \(bu 2 fy_generic_is_##_gtype(): inline dispatcher handling both direct and indirect values. .UNINDENT .UNINDENT .SS macro FY_GENERIC_IS_TEMPLATE_NON_INLINE .INDENT 0.0 .TP .B FY_GENERIC_IS_TEMPLATE_NON_INLINE(_gtype) Generate out\-of\-line type\-check function bodies. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gtype\fP – Type suffix matching a previous \fBFY_GENERIC_IS_TEMPLATE_INLINE()\fP call. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Companion to \fBFY_GENERIC_IS_TEMPLATE_INLINE()\fP used in .c files to emit the actual function bodies for fy_generic_is_indirect_##_gtype##_nocheck() and fy_generic_is_indirect_##_gtype(). .SS fy_generic_is_direct_null_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_null_type(const fy_generic v) Test whether a direct generic is null. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP is the null escape constant. .SS fy_generic_is_direct_bool_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_bool_type(const fy_generic v) Test whether a direct generic is a boolean. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP is fy_true or fy_false. .SS fy_generic_is_direct_int_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_int_type(const fy_generic v) Test whether a direct generic is a signed integer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks for both inplace (%FY_INT_INPLACE_V) and out\-of\-place (%FY_INT_OUTPLACE_V) integer tag values using an unsigned range trick. .SS Return .sp true if \fBv\fP holds an integer (signed or unsigned). .SS fy_generic_is_direct_uint_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_uint_type(const fy_generic v) Test whether a direct generic is an unsigned integer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Signed and unsigned integers share the same tag bits; this is an alias for \fBfy_generic_is_direct_int_type()\fP\&. .SS Return .sp true if \fBv\fP holds an integer value. .SS fy_generic_is_direct_float_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_float_type(const fy_generic v) Test whether a direct generic is a float. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks for both inplace (%FY_FLOAT_INPLACE_V, 64\-bit only) and out\-of\-place (%FY_FLOAT_OUTPLACE_V) float tag values. .SS Return .sp true if \fBv\fP holds a floating\-point value. .SS fy_generic_is_direct_string .INDENT 0.0 .TP .B bool fy_generic_is_direct_string(const fy_generic v) Test whether a direct generic is a string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks for both inplace (%FY_STRING_INPLACE_V) and out\-of\-place (%FY_STRING_OUTPLACE_V) string tag values. .SS Return .sp true if \fBv\fP holds a string value. .SS fy_generic_is_direct_string_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_string_type(const fy_generic v) Alias for \fBfy_generic_is_direct_string()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP holds a string value. .SS fy_generic_is_direct_sequence .INDENT 0.0 .TP .B bool fy_generic_is_direct_sequence(const fy_generic v) Test whether a direct generic is a sequence. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp A direct sequence has the low 4 bits all zero (pointer or empty sentinel). .SS Return .sp true if \fBv\fP is a sequence (possibly empty). .SS fy_generic_is_direct_sequence_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_sequence_type(const fy_generic v) Alias for \fBfy_generic_is_direct_sequence()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP is a sequence. .SS fy_generic_is_direct_mapping .INDENT 0.0 .TP .B bool fy_generic_is_direct_mapping(const fy_generic v) Test whether a direct generic is a mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp A direct mapping has bit 3 set and the low 3 bits zero (low 4 bits == 8). .SS Return .sp true if \fBv\fP is a mapping (possibly empty). .SS fy_generic_is_direct_mapping_type .INDENT 0.0 .TP .B bool fy_generic_is_direct_mapping_type(const fy_generic v) Alias for \fBfy_generic_is_direct_mapping()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP is a mapping. .SS fy_generic_is_direct_collection .INDENT 0.0 .TP .B bool fy_generic_is_direct_collection(const fy_generic v) Test whether a direct generic is a sequence or mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Both sequences and mappings have the low 3 bits of the type tag equal to zero. .SS Return .sp true if \fBv\fP is either a sequence or a mapping. .SS fy_generic_collectionp_get_items .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBtype\fP (const enum fy_generic_type) – Either \fBFYGT_SEQUENCE\fP or \fBFYGT_MAPPING\fP\&. .IP \(bu 2 \fBcolp\fP (const fy_generic_collection*) – Pointer to the \fBstruct fy_generic_collection\fP storage block (may be NULL). .IP \(bu 2 \fBcountp\fP (size_t*) – Receives the number of \fBstruct fy_generic\fP items in the returned array. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the flat item array of a sequence or mapping storage block. For mappings the returned array interleaves keys and values, so \fBcountp\fP receives colp\->count * 2. .SS Return .sp Pointer to the first item, or NULL if \fBcolp\fP is NULL or the collection is empty. .SS fy_generic_get_direct_collection .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A direct generic value. .IP \(bu 2 \fBtypep\fP (enum fy_generic_type*) – Receives \fBFYGT_SEQUENCE\fP, \fBFYGT_MAPPING\fP, or \fBFYGT_INVALID\fP if not a collection. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks that \fBv\fP is a direct sequence or mapping, identifies its type, and returns a pointer to its \fBstruct fy_generic_collection\fP storage. .SS Return .sp Pointer to the collection storage, or NULL if \fBv\fP is not a direct collection. .SS fy_generic_is_direct_alias .INDENT 0.0 .TP .B bool fy_generic_is_direct_alias(const fy_generic v) Test whether a direct generic is an alias. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A direct generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP has type \fBFYGT_ALIAS\fP\&. .SS fy_generic_get_null_type_no_check .INDENT 0.0 .TP .B void *fy_generic_get_null_type_no_check(fy_generic v) Decode a null generic (always returns NULL). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A generic value known to be null. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Always NULL. .SS fy_generic_in_place_null_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_null_type(void *p) Encode a null pointer as an inplace null generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBp\fP (void*) – Must be NULL; any non\-NULL pointer yields \fBfy_invalid_value\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBfy_null_value\fP if \fBp\fP is NULL, \fBfy_invalid_value\fP otherwise. .SS fy_generic_out_of_place_size_null_type .INDENT 0.0 .TP .B size_t fy_generic_out_of_place_size_null_type(void *v) Out\-of\-place allocation size for null (always 0). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (void*) – Ignored. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 0 — nulls are always stored inplace. .SS fy_generic_out_of_place_put_null_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_out_of_place_put_null_type(void *buf, void *v) Encode null into an out\-of\-place buffer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Ignored (null has no out\-of\-place representation). .IP \(bu 2 \fBv\fP (void*) – Ignored. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBfy_null_value\fP\&. .SS fy_generic_get_bool_type_no_check .INDENT 0.0 .TP .B bool fy_generic_get_bool_type_no_check(fy_generic v) Decode a boolean generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A generic value known to be a boolean. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if \fBv\fP equals \fBfy_true_value\fP; false for \fBfy_false_value\fP\&. .SS fy_generic_in_place_bool_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_bool_type(_Bool v) Encode a boolean as an inplace generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (_Bool) – The boolean value to encode. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBfy_true_value\fP or \fBfy_false_value\fP\&. .SS fy_generic_out_of_place_size_bool_type .INDENT 0.0 .TP .B size_t fy_generic_out_of_place_size_bool_type(bool v) Out\-of\-place allocation size for a boolean (0). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (bool) – Ignored. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 0 — booleans are always stored inplace. .SS fy_generic_out_of_place_put_bool_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_out_of_place_put_bool_type(void *buf, bool v) Encode a boolean into an out\-of\-place buffer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Ignored. .IP \(bu 2 \fBv\fP (bool) – The boolean value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBfy_true_value\fP or \fBfy_false_value\fP\&. .SS fy_generic_in_place_int_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_int_type(const long long v) Try to encode a signed integer inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const long long) – The signed 64\-bit integer to encode. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Stores the value in the upper bits of the word if it fits within the inplace range [%FYGT_INT_INPLACE_MIN, \fBFYGT_INT_INPLACE_MAX\fP]. .SS Return .sp The encoded \fBstruct fy_generic_value\fP, or \fBfy_invalid_value\fP if \fBv\fP is out of range. .SS fy_generic_out_of_place_put_int_type .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Caller\-allocated, suitably aligned buffer of at least sizeof(fy_generic_decorated_int). .IP \(bu 2 \fBv\fP (const long long) – The signed 64\-bit integer value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Writes the value into a \fBstruct fy_generic_decorated_int\fP at \fBbuf\fP (which must be aligned to \fBFY_INPLACE_TYPE_MASK\fP + 1 bytes) and returns a tagged pointer. .SS Return .sp A \fBstruct fy_generic_value\fP with \fBFY_INT_OUTPLACE_V\fP tag and \fBbuf\fP as the pointer. .SS fy_generic_in_place_uint_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_uint_type(const unsigned long long v) Try to encode an unsigned integer inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const unsigned long long) – The unsigned 64\-bit integer to encode. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Stores the value inplace if it fits within \fBFYGT_INT_INPLACE_MAX\fP (unsigned values sharing the inplace range with signed integers). .SS Return .sp The encoded \fBstruct fy_generic_value\fP, or \fBfy_invalid_value\fP if \fBv\fP exceeds the range. .SS fy_generic_out_of_place_put_uint_type .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Caller\-allocated, suitably aligned buffer. .IP \(bu 2 \fBv\fP (const unsigned long long) – The unsigned 64\-bit integer value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Writes the value into a \fBstruct fy_generic_decorated_int\fP and sets \fBFYGDIF_UNSIGNED_RANGE_EXTEND\fP if the value exceeds LLONG_MAX. .SS Return .sp A \fBstruct fy_generic_value\fP with \fBFY_INT_OUTPLACE_V\fP tag and \fBbuf\fP as the pointer. .SS fy_generic_in_place_float_type .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_float_type(const double v) Try to encode a double as an inplace float (64\-bit). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const double) – The double value to encode. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfy_invalid_value\fP (no inplace floats). .SS Return .sp The inplace\-encoded \fBstruct fy_generic_value\fP, or \fBfy_invalid_value\fP if \fBv\fP cannot be stored inplace. .SS fy_generic_out_of_place_put_float_type .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Caller\-allocated, suitably aligned buffer of at least sizeof(double). .IP \(bu 2 \fBv\fP (const double) – The double value to store. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Writes the double at \fBbuf\fP (which must be suitably aligned) and returns a tagged pointer with \fBFY_FLOAT_OUTPLACE_V\fP\&. .SS Return .sp A \fBstruct fy_generic_value\fP with \fBFY_FLOAT_OUTPLACE_V\fP tag and \fBbuf\fP as the pointer. .SS fy_generic_get_int_type_no_check .INDENT 0.0 .TP .B long long fy_generic_get_int_type_no_check(fy_generic v) Decode a signed integer generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A generic value known to be an integer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both inplace (sign\-extends the packed value) and out\-of\-place (dereferences the pointer) representations. .SS Return .sp The decoded signed 64\-bit integer, or 0 if the pointer resolves to NULL. .SS fy_generic_out_of_place_size_int_type .INDENT 0.0 .TP .B size_t fy_generic_out_of_place_size_int_type(const long long v) Out\-of\-place allocation size for a signed integer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const long long) – The integer value to be encoded. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 0 if \fBv\fP fits inplace, sizeof(fy_generic_decorated_int) otherwise. .SS fy_generic_get_uint_type_no_check .INDENT 0.0 .TP .B unsigned long long fy_generic_get_uint_type_no_check(fy_generic v) Decode an unsigned integer generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A generic value known to be an integer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both inplace (zero\-extends the packed value) and out\-of\-place representations. .SS Return .sp The decoded unsigned 64\-bit integer, or 0 if the pointer resolves to NULL. .SS fy_generic_out_of_place_size_uint_type .INDENT 0.0 .TP .B size_t fy_generic_out_of_place_size_uint_type(const unsigned long long v) Out\-of\-place allocation size for an unsigned integer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const unsigned long long) – The unsigned integer value to be encoded. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 0 if \fBv\fP fits inplace, sizeof(fy_generic_decorated_int) otherwise. .SS fy_generic_get_float_type_no_check .INDENT 0.0 .TP .B double fy_generic_get_float_type_no_check(fy_generic v) Decode a float generic (64\-bit). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A generic value known to be a float. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles inplace 32\-bit floats (widened to double) and out\-of\-place doubles. .SS Return .sp The decoded double value, or 0.0 if the out\-of\-place pointer is NULL. .SS fy_generic_out_of_place_size_float_type .INDENT 0.0 .TP .B size_t fy_generic_out_of_place_size_float_type(const double v) Out\-of\-place allocation size for a float (64\-bit). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const double) – The double value to be encoded. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 0 if \fBv\fP can be stored inplace (as float32 without loss), sizeof(double) otherwise. .SS fy_generic_out_of_place_size_double .INDENT 0.0 .TP .B size_t fy_generic_out_of_place_size_double(const double v) Out\-of\-place allocation size for a double (32\-bit). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const double) – Ignored. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp On 32\-bit platforms all floats are stored out\-of\-place as doubles. .SS Return .sp sizeof(double). .SS fy_generic_sequence_resolve_outofplace .INDENT 0.0 .TP .B const fy_generic_sequence *fy_generic_sequence_resolve_outofplace(fy_generic seq) Resolve a non\-direct sequence to its storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (fy_generic) – A sequence generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Called when the sequence is indirect (wrapped) or otherwise not directly addressable. Do not call directly; use \fBfy_generic_sequence_resolve()\fP instead. .SS Return .sp Pointer to the \fBstruct fy_generic_sequence\fP storage, or NULL on error. .SS fy_generic_sequence_resolve .INDENT 0.0 .TP .B const fy_generic_sequence *fy_generic_sequence_resolve(const fy_generic seq) Resolve any sequence generic to its storage pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (const fy_generic) – A sequence generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both direct (pointer embedded in the word) and indirect sequences. .SS Return .sp Pointer to the \fBstruct fy_generic_sequence\fP storage, or NULL for an empty/invalid sequence. .SS fy_generic_sequence_to_handle .INDENT 0.0 .TP .B fy_generic_sequence_handle fy_generic_sequence_to_handle(const fy_generic seq) Convert a sequence generic to an opaque handle. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (const fy_generic) – A sequence generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A \fBstruct fy_generic_sequence_handle\fP pointing to the sequence storage. .SS fy_generic_sequencep_items .INDENT 0.0 .TP .B const fy_generic *fy_generic_sequencep_items(const fy_generic_sequence *seqp) Get the items array from a sequence pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseqp\fP (const fy_generic_sequence*) – Pointer to a \fBstruct fy_generic_sequence\fP (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the first item, or NULL if \fBseqp\fP is NULL. .SS fy_generic_sequencep_get_item_count .INDENT 0.0 .TP .B size_t fy_generic_sequencep_get_item_count(const fy_generic_sequence *seqp) Get the item count from a sequence pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseqp\fP (const fy_generic_sequence*) – Pointer to a \fBstruct fy_generic_sequence\fP (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The number of items, or 0 if \fBseqp\fP is NULL. .SS fy_generic_sequence_get_item_count .INDENT 0.0 .TP .B size_t fy_generic_sequence_get_item_count(fy_generic seq) Get the number of items in a sequence. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (fy_generic) – A sequence generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The number of items in the sequence, or 0 if empty or invalid. .SS fy_generic_sequence_get_items .INDENT 0.0 .TP .B const fy_generic *fy_generic_sequence_get_items(fy_generic seq, size_t *countp) Get the items array and count from a sequence. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (fy_generic) – A sequence generic value. .IP \(bu 2 \fBcountp\fP (size_t*) – Receives the number of items. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the first item, or NULL if the sequence is empty or invalid. .SS fy_generic_sequencep_get_itemp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseqp\fP (const fy_generic_sequence*) – Pointer to a \fBstruct fy_generic_sequence\fP (may be NULL). .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based item index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the item at \fBidx\fP, or NULL if out of range or \fBseqp\fP is NULL. .SS fy_generic_sequence_get_itemp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (fy_generic) – A sequence generic value. .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based item index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the item at \fBidx\fP, or NULL if out of range or the sequence is invalid. .SS fy_generic_sequence_get_item_generic .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseq\fP (fy_generic) – A sequence generic value. .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based item index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The item at \fBidx\fP, or \fBfy_invalid\fP if out of range or the sequence is invalid. .SS fy_generic_mapping_resolve_outofplace .INDENT 0.0 .TP .B const fy_generic_mapping *fy_generic_mapping_resolve_outofplace(fy_generic map) Resolve a non\-direct mapping to its storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Called when the mapping is indirect (wrapped) or otherwise not directly addressable. Do not call directly; use \fBfy_generic_mapping_resolve()\fP instead. .SS Return .sp Pointer to the \fBstruct fy_generic_mapping\fP storage, or NULL on error. .SS fy_generic_mapping_resolve .INDENT 0.0 .TP .B const fy_generic_mapping *fy_generic_mapping_resolve(const fy_generic map) Resolve any mapping generic to its storage pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (const fy_generic) – A mapping generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both direct (pointer embedded in the word) and indirect mappings. .SS Return .sp Pointer to the \fBstruct fy_generic_mapping\fP storage, or NULL for an empty/invalid mapping. .SS fy_generic_mapping_to_handle .INDENT 0.0 .TP .B fy_generic_mapping_handle fy_generic_mapping_to_handle(const fy_generic map) Convert a mapping generic to an opaque handle. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (const fy_generic) – A mapping generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A \fBstruct fy_generic_mapping_handle\fP pointing to the mapping storage. .SS fy_generic_mappingp_items .INDENT 0.0 .TP .B const fy_generic *fy_generic_mappingp_items(const fy_generic_mapping *mapp) Get the flat interleaved items array from a mapping pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the pairs storage as a flat array of \fBstruct fy_generic\fP values where even indices are keys and odd indices are values. .SS Return .sp Pointer to the first key, or NULL if \fBmapp\fP is NULL. .SS fy_generic_mappingp_get_pair_count .INDENT 0.0 .TP .B size_t fy_generic_mappingp_get_pair_count(const fy_generic_mapping *mapp) Get the number of key/value pairs from a mapping pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The number of pairs, or 0 if \fBmapp\fP is NULL. .SS fy_generic_mapping_get_pairs .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBcountp\fP (size_t*) – Receives the number of key/value pairs. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the first \fBstruct fy_generic_map_pair\fP, or NULL if the mapping is empty or invalid. .SS fy_generic_mapping_get_items .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBitem_countp\fP (size_t*) – Receives the total number of items (2 x pair count). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the entire pair storage as a flat array of \fBstruct fy_generic\fP values (even = keys, odd = values). \fBitem_countp\fP receives 2 * pair_count. .SS Return .sp Pointer to the first item, or NULL if the mapping is empty or invalid. .SS fy_generic_compare_out_of_place .INDENT 0.0 .TP .B int fy_generic_compare_out_of_place(fy_generic a, fy_generic b) Compare two generics that are not word\-equal. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBa\fP (fy_generic) – First generic value. .IP \(bu 2 \fBb\fP (fy_generic) – Second generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles out\-of\-place values (e.g. large integers, strings, collections) that require dereferencing to compare. Not intended for direct use; call \fBfy_generic_compare()\fP instead. .SS Return .sp 0 if equal, negative if \fBa\fP < \fBb\fP, positive if \fBa\fP > \fBb\fP, \-2 if either is invalid. .SS fy_generic_compare .INDENT 0.0 .TP .B int fy_generic_compare(fy_generic a, fy_generic b) Compare two generic values for equality and ordering. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBa\fP (fy_generic) – First generic value. .IP \(bu 2 \fBb\fP (fy_generic) – Second generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Fast path: if the raw words are equal the values are equal (covers inplace scalars and identical pointers). Falls back to \fBfy_generic_compare_out_of_place()\fP for out\-of\-place or complex values. .SS Return .sp 0 if \fBa\fP == \fBb\fP, negative if \fBa\fP < \fBb\fP, positive if \fBa\fP > \fBb\fP, \-2 if either operand is \fBfy_invalid\fP\&. .SS fy_generic_mappingp_get_at_keyp .INDENT 0.0 .TP .B 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). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the key at \fBidx\fP, or NULL if out of range or \fBmapp\fP is NULL. .SS fy_generic_mapping_get_at_keyp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the key at \fBidx\fP, or NULL if out of range or the mapping is invalid. .SS fy_generic_mappingp_get_at_key .INDENT 0.0 .TP .B 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). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The key at \fBidx\fP, or \fBfy_invalid\fP if out of range or \fBmapp\fP is NULL. .SS fy_generic_mapping_get_at_key .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The key at \fBidx\fP, or \fBfy_invalid\fP if out of range or the mapping is invalid. .SS fy_generic_mappingp_valuep_index .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .IP \(bu 2 \fBkey\fP (fy_generic) – The key to search for. .IP \(bu 2 \fBidxp\fP (size_t*) – Receives the found pair index, or (size_t)\-1 if not found (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Linear search by key equality. If found, sets \%<*@\:idxp> to the pair index. .SS Return .sp Pointer to the value, or NULL if the key was not found or \fBmapp\fP is NULL. .SS fy_generic_mappingp_get_valuep .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .IP \(bu 2 \fBkey\fP (fy_generic) – The key to search for. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the value, or NULL if the key was not found. .SS fy_generic_mappingp_get_at_valuep .INDENT 0.0 .TP .B 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). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the value at \fBidx\fP, or NULL if out of range or \fBmapp\fP is NULL. .SS fy_generic_mapping_get_valuep_index .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBkey\fP (fy_generic) – The key to search for. .IP \(bu 2 \fBidxp\fP (size_t*) – Receives the found pair index, or (size_t)\-1 if not found (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the value, or NULL if not found. .SS fy_generic_mapping_get_valuep .INDENT 0.0 .TP .B const fy_generic *fy_generic_mapping_get_valuep(fy_generic map, fy_generic key) Look up a value by key in a mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBkey\fP (fy_generic) – The key to search for. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the value, or NULL if the key was not found. .SS fy_generic_mapping_get_at_valuep .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the value at \fBidx\fP, or NULL if out of range or the mapping is invalid. .SS fy_generic_mapping_get_value_index .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBkey\fP (fy_generic) – The key to search for. .IP \(bu 2 \fBidxp\fP (size_t*) – Receives the found pair index, or (size_t)\-1 if not found (may be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The value, or \fBfy_invalid\fP if not found. .SS fy_generic_mapping_get_value .INDENT 0.0 .TP .B fy_generic fy_generic_mapping_get_value(fy_generic map, fy_generic key) Look up a value by key in a mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBkey\fP (fy_generic) – The key to search for. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The value, or \fBfy_invalid\fP if not found. .SS fy_generic_mappingp_get_at_value .INDENT 0.0 .TP .B 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). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmapp\fP (const fy_generic_mapping*) – Pointer to a \fBstruct fy_generic_mapping\fP (may be NULL). .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The value at \fBidx\fP, or \fBfy_invalid\fP if out of range or \fBmapp\fP is NULL. .SS fy_generic_mapping_get_at_value .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .IP \(bu 2 \fBidx\fP (const size_t) – Zero\-based pair index. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The value at \fBidx\fP, or \fBfy_invalid\fP if out of range or the mapping is invalid. .SS fy_generic_mapping_get_pair_count .INDENT 0.0 .TP .B size_t fy_generic_mapping_get_pair_count(fy_generic map) Get the number of key/value pairs in a mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmap\fP (fy_generic) – A mapping generic value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The number of pairs, or 0 if the mapping is empty or invalid. .SS fy_generic_collection_get_items .INDENT 0.0 .TP .B const fy_generic *fy_generic_collection_get_items(fy_generic v, size_t *countp) Get the raw item array of a sequence or mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A sequence or mapping generic value. .IP \(bu 2 \fBcountp\fP (size_t*) – Receives the number of items (elements for sequences, 2 x pair\-count for mappings). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Pointer to the first item, or NULL if \fBv\fP is not a collection or is invalid. .SS macro FY_GENERIC_LVAL_TEMPLATE .INDENT 0.0 .TP .B FY_GENERIC_LVAL_TEMPLATE(_ctype, _gtype, _gttype, _xctype, _xgtype, _xminv, _xmaxv, _default_v) Generate typed accessor/cast functions for a C scalar type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_ctype\fP – The C type (e.g. int, unsigned long). .IP \(bu 2 \fB_gtype\fP – The token name used in generated identifiers (e.g. int, unsigned_long). .IP \(bu 2 \fB_gttype\fP – The generic type tag category (INT, UINT, FLOAT, BOOL, NULL). .IP \(bu 2 \fB_xctype\fP – The underlying storage C type (long long, unsigned long long, double, etc.). .IP \(bu 2 \fB_xgtype\fP – The underlying storage type name (int_type, uint_type, float_type, etc.). .IP \(bu 2 \fB_xminv\fP – Minimum representable value for range\-checking. .IP \(bu 2 \fB_xmaxv\fP – Maximum representable value for range\-checking. .IP \(bu 2 \fB_default_v\fP – Default value returned when conversion fails. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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: .INDENT 0.0 .IP \(bu 2 fy_generic_get__no_check() \- extract value, no type check .IP \(bu 2 fy_generic__is_in_range_no_check() \- range check without type check .IP \(bu 2 fy_generic__is_in_range() \- full range check .IP \(bu 2 fy_generic_is_direct_() \- direct type predicate .IP \(bu 2 fy_generic_is_() \- type predicate (resolves indirect) .IP \(bu 2 fy_generic_in_place_() \- encode as inplace value .IP \(bu 2 fy_generic_out_of_place_size_() \- out\-of\-place storage size .IP \(bu 2 fy_generic_out_of_place_put_() \- write out\-of\-place representation .IP \(bu 2 fy_generic_cast__default() \- cast generic to C type with default .IP \(bu 2 fy_generic_cast_() \- cast generic to C type .IP \(bu 2 fy_genericp_cast__default() \- pointer variant with default .IP \(bu 2 fy_genericp_cast_() \- pointer variant .IP \(bu 2 fy_generic_sequencep_get__itemp() \- typed sequence item pointer .IP \(bu 2 fy_generic_sequence_get__itemp() \- typed sequence item pointer (handle) .IP \(bu 2 fy_generic_sequencep_get__default() \- typed sequence item with default .IP \(bu 2 fy_generic_sequence_get__default() \- typed sequence item (handle) .IP \(bu 2 fy_generic_mappingp_get__valuep() \- typed mapping value pointer .IP \(bu 2 fy_generic_mapping_get__valuep() \- typed mapping value pointer (handle) .IP \(bu 2 fy_generic_mappingp_get__default() \- typed mapping value with default .IP \(bu 2 fy_generic_mapping_get__default() \- typed mapping value (handle) .IP \(bu 2 (and similar _at_ variants for positional access) .UNINDENT .SS macro FY_GENERIC_INT_LVAL_TEMPLATE .INDENT 0.0 .TP .B FY_GENERIC_INT_LVAL_TEMPLATE(_ctype, _gtype, _xminv, _xmaxv, _defaultv) Specialise FY_GENERIC_LVAL_TEMPLATE for signed integer types. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_ctype\fP – The C type (e.g. int, short). .IP \(bu 2 \fB_gtype\fP – Token name (e.g. int, short). .IP \(bu 2 \fB_xminv\fP – Minimum value (e.g. INT_MIN). .IP \(bu 2 \fB_xmaxv\fP – Maximum value (e.g. INT_MAX). .IP \(bu 2 \fB_defaultv\fP – Default value on conversion failure. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Defines fy__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. .SS macro FY_GENERIC_UINT_LVAL_TEMPLATE .INDENT 0.0 .TP .B FY_GENERIC_UINT_LVAL_TEMPLATE(_ctype, _gtype, _xminv, _xmaxv, _defaultv) Specialise FY_GENERIC_LVAL_TEMPLATE for unsigned integer types. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_ctype\fP – The C type (e.g. unsigned int, unsigned long). .IP \(bu 2 \fB_gtype\fP – Token name (e.g. unsigned_int, unsigned_long). .IP \(bu 2 \fB_xminv\fP – Minimum value (always 0 for unsigned types). .IP \(bu 2 \fB_xmaxv\fP – Maximum value (e.g. UINT_MAX). .IP \(bu 2 \fB_defaultv\fP – Default value on conversion failure. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Defines fy__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. .SS macro FY_GENERIC_FLOAT_LVAL_TEMPLATE .INDENT 0.0 .TP .B FY_GENERIC_FLOAT_LVAL_TEMPLATE(_ctype, _gtype, _xminv, _xmaxv, _defaultv) Specialise FY_GENERIC_LVAL_TEMPLATE for floating\-point types. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_ctype\fP – The C type (float or double). .IP \(bu 2 \fB_gtype\fP – Token name (float or double). .IP \(bu 2 \fB_xminv\fP – Minimum normal value (e.g. \-FLT_MAX). .IP \(bu 2 \fB_xmaxv\fP – Maximum normal value (e.g. FLT_MAX). .IP \(bu 2 \fB_defaultv\fP – Default value on conversion failure. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Defines fy__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. .SS fy_generic_get_string_inplace_size .INDENT 0.0 .TP .B size_t fy_generic_get_string_inplace_size(const fy_generic v) Extract the length of an inplace string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (const fy_generic) – A generic value with tag FY_STRING_INPLACE_V. Behaviour is undefined otherwise. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Length of the inplace string in bytes (0–7 on 64\-bit, 0–3 on 32\-bit). .SS fy_genericp_get_string_inplace .INDENT 0.0 .TP .B const char *fy_genericp_get_string_inplace(const fy_generic *vp) Return a pointer to the inplace string bytes. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a generic with tag FY_STRING_INPLACE_V. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp The returned pointer is into the storage of \fBvp\fP itself. The caller must ensure \fBvp\fP lives at least as long as the returned pointer is used. .SS Return .sp Pointer to the first character of the inplace string (not NUL\-terminated). .SS fy_genericp_get_string_size_no_check .INDENT 0.0 .TP .B const char *fy_genericp_get_string_size_no_check(const fy_generic *vp, size_t *lenp) Get string pointer and length without type check. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a generic known to hold a string (inplace or outplace). .IP \(bu 2 \fBlenp\fP (size_t*) – Receives the length of the string in bytes. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the string data and length for both inplace and out\-of\-place strings, without verifying that \fBvp\fP actually holds a string. .SS Return .sp Pointer to the NUL\-terminated string data. .SS fy_genericp_get_string_no_check .INDENT 0.0 .TP .B const char *fy_genericp_get_string_no_check(const fy_generic *vp) Get string pointer without type check or length. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a generic known to hold a string (inplace or outplace). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the NUL\-terminated string data. .SS macro fy_genericp_get_string_size .INDENT 0.0 .TP .B fy_genericp_get_string_size(_vp, _lenp) Get string pointer and length from a generic pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_vp\fP – Pointer to a generic value (may be indirect). May be NULL. .IP \(bu 2 \fB_lenp\fP – Receives the string length. Set to 0 on failure. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Pointer to the NUL\-terminated string, or NULL on error / non\-string. .SS macro fy_genericp_get_string_default .INDENT 0.0 .TP .B fy_genericp_get_string_default(_vp, _default_v) Get string pointer from a generic pointer, with a default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_vp\fP – Pointer to a generic value. May be NULL. .IP \(bu 2 \fB_default_v\fP – Returned when \fB_vp\fP is NULL or not a string. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The string pointer, or \fB_default_v\fP on failure. .SS macro fy_generic_get_string_size_alloca .INDENT 0.0 .TP .B fy_generic_get_string_size_alloca(_v, _lenp) Get string pointer and length from a generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – A generic value (may be indirect). .IP \(bu 2 \fB_lenp\fP – Receives the string length. Set to 0 on failure. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_genericp_get_string_size()\fP 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. .SS Return .sp Pointer to the NUL\-terminated string, or NULL on error / non\-string. .SS macro fy_generic_get_string_default_alloca .INDENT 0.0 .TP .B fy_generic_get_string_default_alloca(_v, _default_v) Get string from a generic value with a default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – A generic value. .IP \(bu 2 \fB_default_v\fP – Returned when \fB_v\fP is not a string. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The string pointer, or \fB_default_v\fP on failure. .SS fy_genericp_get_const_char_ptr_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a generic value (indirect is resolved). May be NULL. .IP \(bu 2 \fBdefault_value\fP (const char*) – Returned when \fBvp\fP is NULL or not an out\-of\-place string. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Only works for out\-of\-place strings (heap\-allocated). Inplace strings cannot be returned as a stable pointer; use \fBfy_genericp_get_string_size()\fP for those. .SS Return .sp Pointer to the NUL\-terminated string, or \fBdefault_value\fP on failure. .SS fy_genericp_get_const_char_ptr .INDENT 0.0 .TP .B const char *fy_genericp_get_const_char_ptr(const fy_generic *vp) Get a const char pointer from a generic pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns “” when \fBvp\fP is NULL or not an out\-of\-place string. .SS Return .sp Pointer to the string, or “” on failure. .SS fy_genericp_get_char_ptr_default .INDENT 0.0 .TP .B char *fy_genericp_get_char_ptr_default(fy_generic *vp, const char *default_value) Get a mutable char pointer from a generic pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (fy_generic*) – Pointer to a generic value. .IP \(bu 2 \fBdefault_value\fP (const char*) – Returned on failure. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Same as \fBfy_genericp_get_const_char_ptr_default()\fP but returns a non\-const pointer. .SS Return .sp Mutable pointer to the string, or \fBdefault_value\fP on failure. .SS fy_genericp_get_char_ptr .INDENT 0.0 .TP .B char *fy_genericp_get_char_ptr(fy_generic *vp) Get a mutable char pointer from a generic pointer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (fy_generic*) – Pointer to a generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns “” when \fBvp\fP is NULL or not an out\-of\-place string. .SS Return .sp Mutable pointer to the string, or “” on failure. .SS macro fy_generic_get_alias_alloca .INDENT 0.0 .TP .B fy_generic_get_alias_alloca(_v) Get the anchor name string from an alias generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – An alias generic value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Extracts the anchor (string) from an alias value using alloca for inplace storage. .SS Return .sp Pointer to the NUL\-terminated anchor name, or “” if \fB_v\fP is not an alias. .SS macro fy_bool .INDENT 0.0 .TP .B fy_bool(_v) Create a bool generic from a C boolean expression. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Boolean expression. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_true if \fB_v\fP is non\-zero, fy_false otherwise. .SS macro fy_int_is_unsigned .INDENT 0.0 .TP .B fy_int_is_unsigned(_v) Detect whether an integer constant exceeds LLONG_MAX. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – An integer expression. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses _Generic to check at compile time whether an unsigned long long value is above LLONG_MAX, which indicates it requires unsigned representation. .SS Return .sp true if \fB_v\fP is an unsigned long long greater than LLONG_MAX, false otherwise. .SS macro fy_int_alloca .INDENT 0.0 .TP .B fy_int_alloca(_v) Create an integer generic using alloca for out\-of\-place values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Any integer expression. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Encodes \fB_v\fP 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. .SS Return .sp A fy_generic_value encoding \fB_v\fP\&. .SS macro fy_int .INDENT 0.0 .TP .B fy_int(_v) Create an integer generic from any integer expression. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – An integer expression of any width. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Selects the most efficient encoding at compile time: inplace for small constants, static storage for large constants, or alloca for runtime values. .SS Return .sp A fy_generic holding \fB_v\fP\&. .SS fy_generic_in_place_char_ptr_len .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_char_ptr_len(const char *p, const size_t len) Attempt to encode a string inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBp\fP (const char*) – String data (need not be NUL\-terminated). .IP \(bu 2 \fBlen\fP (const size_t) – Length of \fBp\fP in bytes. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Packs up to 7 bytes (64\-bit) or 3 bytes (32\-bit) of \fBp\fP directly into the generic word. Returns fy_invalid_value when the string is too long for inplace storage. .SS Return .sp Encoded fy_generic_value on success, fy_invalid_value when \fBlen\fP is too large. .SS fy_generic_in_place_char_ptr .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_char_ptr(const char *p) Attempt to encode a NUL\-terminated string inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBp\fP (const char*) – NUL\-terminated string. May be NULL (returns fy_invalid_value). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Encoded fy_generic_value on success, fy_invalid_value when the string is too long. .SS fy_generic_in_place_const_szstrp .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_const_szstrp(const fy_generic_sized_string *szstrp) Attempt to encode a sized string inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBszstrp\fP (const fy_generic_sized_string*) – Pointer to a sized string. May be NULL (returns fy_invalid_value). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Encoded fy_generic_value on success, fy_invalid_value when the string is too long. .SS fy_generic_in_place_szstr .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_szstr(const fy_generic_sized_string szstr) Attempt to encode a sized string value inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBszstr\fP (const fy_generic_sized_string) – A sized string by value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Encoded fy_generic_value, or fy_invalid_value when too long. .SS fy_generic_in_place_const_dintp .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_const_dintp(const fy_generic_decorated_int *dintp) Attempt to encode a decorated int inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdintp\fP (const fy_generic_decorated_int*) – Pointer to the decorated int. May be NULL (returns fy_invalid_value). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Delegates to \fBfy_generic_in_place_int_type()\fP or \fBfy_generic_in_place_uint_type()\fP depending on the FYGDIF_UNSIGNED_RANGE_EXTEND flag. .SS Return .sp Encoded fy_generic_value, or fy_invalid_value when too large for inplace. .SS fy_generic_in_place_dint .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_dint(const fy_generic_decorated_int dint) Attempt to encode a decorated int by value inplace. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdint\fP (const fy_generic_decorated_int) – A decorated int value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Encoded fy_generic_value, or fy_invalid_value when too large for inplace. .SS fy_generic_in_place_sequence_handle .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_sequence_handle(fy_generic_sequence_handle seqh) Encode a sequence handle as a generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBseqh\fP (fy_generic_sequence_handle) – A sequence handle. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Encoded fy_generic_value, fy_seq_empty_value for NULL, or fy_invalid_value on misalignment. .SS fy_generic_in_place_mapping_handle .INDENT 0.0 .TP .B fy_generic_value fy_generic_in_place_mapping_handle(fy_generic_mapping_handle maph) Encode a mapping handle as a generic value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmaph\fP (fy_generic_mapping_handle) – A mapping handle. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Encoded fy_generic_value, fy_map_empty_value for NULL, or fy_invalid_value on misalignment. .SS macro fy_to_generic_inplace .INDENT 0.0 .TP .B fy_to_generic_inplace(_v) Encode a value as an inplace generic using _Generic dispatch. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Value of any supported C type. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Encoded fy_generic_value, or fy_invalid_value if out\-of\-place is required. .SS fy_generic_out_of_place_size_char_ptr .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBp\fP (const char*) – Null\-terminated C string, or NULL. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Storage size in bytes, or 0 for NULL. .SS fy_generic_out_of_place_size_const_szstrp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBszstrp\fP (const fy_generic_sized_string*) – Pointer to a sized string descriptor, or NULL. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Storage size in bytes (length prefix + string bytes + NUL), or 0 for NULL. .SS fy_generic_out_of_place_size_const_dintp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBdintp\fP (const fy_generic_decorated_int*) – Pointer to a decorated int descriptor, or NULL. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to the signed or unsigned variant depending on FYGDIF_UNSIGNED_RANGE_EXTEND. .SS Return .sp Storage size in bytes, or 0 for NULL. .SS macro fy_to_generic_outofplace_size .INDENT 0.0 .TP .B fy_to_generic_outofplace_size(_v) Compute buffer size needed for out\-of\-place encoding of a value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Value of any supported C type. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Number of bytes required, or 0 if the value can be encoded inplace or is unsupported. .SS fy_generic_out_of_place_put_char_ptr .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Pre\-allocated buffer of at least \fBfy_generic_out_of_place_size_char_ptr()\fP bytes. .IP \(bu 2 \fBp\fP (const char*) – Null\-terminated C string (must not be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Encodes the length prefix followed by the string bytes and a NUL terminator into \fBbuf\fP, which must be aligned to FY_GENERIC_CONTAINER_ALIGN. .SS Return .sp Encoded FY_STRING_OUTPLACE_V generic value pointing into \fBbuf\fP, or fy_invalid_value for NULL \fBp\fP\&. .SS fy_generic_out_of_place_put_const_szstrp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Pre\-allocated aligned buffer. .IP \(bu 2 \fBszstrp\fP (const fy_generic_sized_string*) – Sized string descriptor (must not be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Encoded FY_STRING_OUTPLACE_V generic value, or fy_invalid_value for NULL. .SS fy_generic_out_of_place_put_const_dintp .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBbuf\fP (void*) – Pre\-allocated aligned buffer. .IP \(bu 2 \fBdintp\fP (const fy_generic_decorated_int*) – Decorated int descriptor (must not be NULL). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to the signed or unsigned out\-of\-place encoder based on FYGDIF_UNSIGNED_RANGE_EXTEND. .SS Return .sp Encoded generic value, or fy_invalid_value for NULL. .SS macro fy_to_generic_outofplace_put .INDENT 0.0 .TP .B fy_to_generic_outofplace_put(_vp, _v) Write a value into a pre\-allocated out\-of\-place buffer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_vp\fP – Destination buffer pointer. .IP \(bu 2 \fB_v\fP – Value to encode. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses _Generic dispatch to select the correct encoder for \fB_v\fP\&. \fB_vp\fP must point to a buffer of at least fy_to_generic_outofplace_size(@_v) bytes, aligned to FY_GENERIC_CONTAINER_ALIGN. .SS Return .sp Encoded out\-of\-place generic value. .SS macro fy_local_to_generic_value .INDENT 0.0 .TP .B fy_local_to_generic_value(_v) Encode any value as a fy_generic_value using alloca for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Value of any supported C type. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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). .SS Return .sp fy_generic_value suitable for wrapping in a fy_generic struct. .SS macro fy_local_to_generic .INDENT 0.0 .TP .B fy_local_to_generic(_v) Encode any value as a fy_generic using alloca for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Value of any supported C type. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Wrapper around \fBfy_local_to_generic_value()\fP that returns a full fy_generic struct. The result is only valid within the enclosing function’s scope. .SS Return .sp fy_generic value (stack lifetime for out\-of\-place types). .SS macro fy_float_alloca .INDENT 0.0 .TP .B fy_float_alloca(_v) Encode a double as a generic float value using alloca for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – A double value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp fy_generic_value encoding \fB_v\fP (stack lifetime for out\-of\-place case). .SS macro fy_local_float .INDENT 0.0 .TP .B fy_local_float(_v) Construct a fy_generic float value, choosing alloca or static storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – A double (constant or runtime). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses \fBfy_float_const()\fP when \fB_v\fP is a compile\-time constant; otherwise falls back to \fBfy_float_alloca()\fP\&. .SS Return .sp fy_generic wrapping the encoded float. .SS macro fy_float .INDENT 0.0 .TP .B fy_float(_v) High\-level float generic constructor. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – A double value. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience wrapper around \fBfy_local_float()\fP\&. .SS Return .sp fy_generic wrapping the encoded float. .SS macro FY_CONST_P_INIT .INDENT 0.0 .TP .B FY_CONST_P_INIT(_v) Detect a C string literal and return its value, or “” for non\-literal char*. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – A C expression (typically a string literal or char* variable). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp C string literals decay to \fIchar *\fP, but \fI&”literal”\fP has type \fIchar (*)[N]\fP, not \fIchar **\fP\&. This macro exploits that to distinguish literals from variables: literals are returned as\-is; non\-literal char* expressions yield “”. .sp Used internally by \fBfy_string_size_const()\fP to initialize static string buffers. .SS Return .sp \fB_v\fP itself for string literals; “” for other char* values; “” for all other types. .SS macro fy_string_size_alloca .INDENT 0.0 .TP .B fy_string_size_alloca(_v, _len) Encode a string with explicit length using alloca for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Pointer to the string data (need not be NUL\-terminated). .IP \(bu 2 \fB_len\fP – Length in bytes. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Attempts inplace encoding first (strings <=7 bytes on 64\-bit). Longer strings are stored in a stack\-allocated buffer prefixed with the encoded length. .SS Return .sp fy_generic_value (stack lifetime for out\-of\-place case). .SS macro fy_string_size_const .INDENT 0.0 .TP .B fy_string_size_const(_v, _len) Encode a compile\-time constant string with explicit length using static storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Pointer to the string data (must be a string literal for static init). .IP \(bu 2 \fB_len\fP – Byte length of the string (excluding any NUL terminator). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp Must only be called when both \fB_v\fP and \fB_len\fP are compile\-time constants (guarded by __builtin_constant_p in \fBfy_string()\fP / \fBfy_local_string()\fP). .SS Return .sp fy_generic_value with static storage lifetime. .SS macro fy_string_alloca .INDENT 0.0 .TP .B fy_string_alloca(_v) Encode a NUL\-terminated string using alloca for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Null\-terminated C string. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Computes the length with \fBstrlen()\fP then delegates to \fBfy_string_size_alloca()\fP\&. .SS Return .sp fy_generic_value (stack lifetime for out\-of\-place case). .SS macro fy_local_string_size .INDENT 0.0 .TP .B fy_local_string_size(_v, _len) Construct a fy_generic string with explicit length, choosing static or alloca storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – String pointer (literal for static path, any pointer for alloca path). .IP \(bu 2 \fB_len\fP – Byte length. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic wrapping the encoded string. .SS macro fy_local_string .INDENT 0.0 .TP .B fy_local_string(_v) Construct a fy_generic string, choosing static or alloca storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – String pointer (literal uses static storage; variable pointer uses alloca). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic wrapping the encoded string. .SS macro fy_string_size .INDENT 0.0 .TP .B fy_string_size(_v, _len) High\-level string generic constructor with explicit byte length. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – String data pointer. .IP \(bu 2 \fB_len\fP – Byte length. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic wrapping the encoded string. .SS macro fy_string .INDENT 0.0 .TP .B fy_string(_v) High\-level string generic constructor from a NUL\-terminated C string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Null\-terminated C string. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic wrapping the encoded string. .SS macro fy_stringf_value .INDENT 0.0 .TP .B fy_stringf_value(_fmt, \&...) Format a string using \fBfy_sprintfa()\fP \%<#\:c\:.fy_sprintfa> and encode it as a fy_generic_value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_fmt\fP – printf\-compatible format string. .IP \(bu 2 \fBellipsis\fP (ellipsis) – Format arguments. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic_value encoding the formatted string (stack lifetime). .SS macro fy_stringf .INDENT 0.0 .TP .B fy_stringf(_fmt, \&...) Format a string and return it as a fy_generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_fmt\fP – printf\-compatible format string. .IP \(bu 2 \fBellipsis\fP (ellipsis) – Format arguments. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic wrapping the formatted string. .SS macro fy_sequence_alloca .INDENT 0.0 .TP .B fy_sequence_alloca(_count, _items) Allocate a sequence on the stack and copy items into it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of elements. .IP \(bu 2 \fB_items\fP – Pointer to an array of \fB_count\fP fy_generic values to copy. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic_value encoding the stack\-allocated sequence (stack lifetime). .SS macro fy_local_sequence_create_value .INDENT 0.0 .TP .B fy_local_sequence_create_value(_count, _items) Create a fy_generic_value for a sequence, handling the empty case. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of elements. .IP \(bu 2 \fB_items\fP – Array of elements to copy. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns fy_seq_empty_value when \fB_count\fP is 0. .SS Return .sp fy_generic_value for the sequence. .SS macro fy_local_sequence_create .INDENT 0.0 .TP .B fy_local_sequence_create(_count, _items) Create a fy_generic sequence from a count and item array. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of elements. .IP \(bu 2 \fB_items\fP – Array of fy_generic values to copy. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic sequence value. .SS macro FY_CPP_VA_GITEMS .INDENT 0.0 .TP .B FY_CPP_VA_GITEMS(_count, \&...) Build a compound\-literal fy_generic array from variadic arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of elements (must equal the number of variadic arguments). .IP \(bu 2 \fBellipsis\fP (ellipsis) – Values to convert. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Each argument is passed through \fBfy_to_generic()\fP for automatic type conversion. .SS Return .sp A (fy_generic [_count]){…} compound literal. .SS macro FY_CPP_VA_GBITEMS .INDENT 0.0 .TP .B FY_CPP_VA_GBITEMS(_count, _gb, \&...) Build a compound\-literal fy_generic array from variadic arguments via a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of elements. .IP \(bu 2 \fB_gb\fP – Builder to internalize values into. .IP \(bu 2 \fBellipsis\fP (ellipsis) – Values to convert. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBFY_CPP_VA_GITEMS()\fP but each item is internalized into \fB_gb\fP via \fBfy_gb_to_generic()\fP, ensuring persistent heap storage. .SS Return .sp A (fy_generic [_count]){…} compound literal. .SS macro fy_local_sequence_value .INDENT 0.0 .TP .B fy_local_sequence_value(\&...) Build a sequence fy_generic_value from variadic arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Values to include in the sequence. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Each argument is converted via \fBfy_to_generic()\fP; the resulting items are stored in a stack\-allocated fy_generic_sequence. .SS Return .sp fy_generic_value encoding the sequence (stack lifetime). .SS macro fy_local_sequence .INDENT 0.0 .TP .B fy_local_sequence(\&...) Build a fy_generic sequence from variadic arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Values to include in the sequence. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic sequence value (stack lifetime). .SS macro fy_mapping_alloca .INDENT 0.0 .TP .B fy_mapping_alloca(_count, _pairs) Allocate a mapping on the stack and copy key\-value pairs into it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of key\-value pairs. .IP \(bu 2 \fB_pairs\fP – Pointer to an array of 2 x \fB_count\fP fy_generic values (interleaved key, value). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic_value encoding the stack\-allocated mapping (stack lifetime). .SS macro fy_local_mapping_create_value .INDENT 0.0 .TP .B fy_local_mapping_create_value(_count, _pairs) Create a fy_generic_value for a mapping, handling the empty case. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of key\-value pairs. .IP \(bu 2 \fB_pairs\fP – Array of interleaved key/value pairs. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic_value for the mapping. .SS macro fy_local_mapping_create .INDENT 0.0 .TP .B fy_local_mapping_create(_count, _items) Create a fy_generic mapping from a count and pairs array. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_count\fP – Number of key\-value pairs. .IP \(bu 2 \fB_items\fP – Array of interleaved fy_generic key/value pairs. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic mapping value. .SS macro fy_local_mapping_value .INDENT 0.0 .TP .B fy_local_mapping_value(\&...) Build a mapping fy_generic_value from variadic key\-value arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Alternating key/value arguments (even count required). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Arguments must be alternating key, value pairs. Each is converted via \fBfy_to_generic()\fP\&. .SS Return .sp fy_generic_value encoding the mapping (stack lifetime). .SS macro fy_local_mapping .INDENT 0.0 .TP .B fy_local_mapping(\&...) Build a fy_generic mapping from variadic key\-value arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Alternating key/value arguments. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic mapping value (stack lifetime). .SS macro fy_indirect_alloca .INDENT 0.0 .TP .B fy_indirect_alloca(_v, _anchor, _tag) Build an indirect wrapper value on the stack. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Wrapped value (fy_generic_value), or fy_invalid_value to omit. .IP \(bu 2 \fB_anchor\fP – Anchor string generic value (fy_string), or fy_invalid_value to omit. .IP \(bu 2 \fB_tag\fP – Tag string generic value (fy_string), or fy_invalid_value to omit. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp fy_generic_value encoding the indirect wrapper (stack lifetime). .SS macro fy_indirect .INDENT 0.0 .TP .B fy_indirect(_v, _anchor, _tag) Build an indirect\-wrapper fy_generic from fy_generic arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – The wrapped value as fy_generic, or fy_invalid for none. .IP \(bu 2 \fB_anchor\fP – Anchor string as fy_generic, or fy_invalid for none. .IP \(bu 2 \fB_tag\fP – Tag string as fy_generic, or fy_invalid for none. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic indirect wrapper (stack lifetime). .SS fy_generic_cast_generic_default .INDENT 0.0 .TP .B fy_generic fy_generic_cast_generic_default(fy_generic v, fy_generic default_value) Return \fBv\fP if it is valid, otherwise return \fBdefault_value\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic value to check. .IP \(bu 2 \fBdefault_value\fP (fy_generic) – Fallback fy_generic. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBv\fP when valid, otherwise \fBdefault_value\fP\&. .SS fy_genericp_cast_generic_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic) – Fallback when \fBvp\fP is NULL or the value is invalid. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \%<*@vp> when valid, otherwise \fBdefault_value\fP\&. .SS fy_generic_cast_sequence_handle_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic value. .IP \(bu 2 \fBdefault_value\fP (fy_generic_sequence_handle) – Fallback handle when \fBv\fP does not hold a sequence. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Sequence handle on success, or \fBdefault_value\fP\&. .SS fy_genericp_cast_sequence_handle_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic_sequence_handle) – Fallback when \fBvp\fP is NULL or not a sequence. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Sequence handle, or \fBdefault_value\fP\&. .SS fy_generic_cast_mapping_handle_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic value. .IP \(bu 2 \fBdefault_value\fP (fy_generic_mapping_handle) – Fallback when \fBv\fP does not hold a mapping. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Mapping handle, or \fBdefault_value\fP\&. .SS fy_genericp_cast_mapping_handle_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic_mapping_handle) – Fallback when \fBvp\fP is NULL or not a mapping. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Mapping handle, or \fBdefault_value\fP\&. .SS fy_generic_cast_const_char_ptr_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic string value. .IP \(bu 2 \fBdefault_value\fP (const char*) – Fallback when \fBv\fP is not a string. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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). .SS Return .sp const char* into the string data, NULL for inplace strings, or \fBdefault_value\fP\&. .SS fy_generic_cast_sized_string_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic string value. .IP \(bu 2 \fBdefault_value\fP (const fy_generic_sized_string) – Fallback when \fBv\fP is not a string. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp fy_generic_sized_string; data may be NULL for inplace strings. .SS fy_genericp_cast_const_char_ptr_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (const char*) – Fallback when \fBvp\fP is NULL or not a string. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to string data, or \fBdefault_value\fP\&. .SS fy_genericp_cast_sized_string_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (const fy_generic_sized_string) – Fallback when \fBvp\fP is NULL or not a string. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic_sized_string with pointer into string data. .SS fy_generic_cast_decorated_int_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic value. .IP \(bu 2 \fBdefault_value\fP (const fy_generic_decorated_int) – Fallback when \fBv\fP does not hold an integer. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Handles both inplace (always signed) and out\-of\-place decorated int encodings. Indirect wrappers are resolved automatically. .SS Return .sp fy_generic_decorated_int on success, or \fBdefault_value\fP\&. .SS fy_generic_cast_const_char_ptr_default_alloca .INDENT 0.0 .TP .B size_t fy_generic_cast_const_char_ptr_default_alloca(fy_generic v) Return alloca size needed for inplace string cast. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic value to examine. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp sizeof(fy_generic) for inplace strings, 0 otherwise. .SS fy_generic_cast_const_char_ptr_default_final .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Inplace string generic value. .IP \(bu 2 \fBp\fP (void*) – Stack buffer of at least \fBsize\fP bytes. .IP \(bu 2 \fBsize\fP (size_t) – Buffer size in bytes. .IP \(bu 2 \fBdefault_value\fP (const char*) – Unused; present for _Generic dispatch uniformity. .IP \(bu 2 \fBstore_value\fP (const char**) – Receives a pointer to the NUL\-terminated copy in \fBp\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Called after alloca when an inplace string was detected. Copies the bytes out of the generic word into \fBp\fP and sets \%<*@\:store_value> to point to \fBp\fP\&. .SS fy_generic_cast_sized_string_default_final .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Inplace string generic value. .IP \(bu 2 \fBp\fP (void*) – Stack buffer. .IP \(bu 2 \fBsize\fP (size_t) – Buffer size in bytes. .IP \(bu 2 \fBdefault_value\fP (fy_generic_sized_string) – Unused. .IP \(bu 2 \fBstore_value\fP (fy_generic_sized_string*) – Receives data/size pointing into \fBp\fP\&. .UNINDENT .UNINDENT .UNINDENT .SS macro fy_generic_cast_default .INDENT 0.0 .TP .B fy_generic_cast_default(_v, _dv) Cast a generic value to a C type using _Generic dispatch. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Source value (any type; converted via \fBfy_to_generic()\fP). .IP \(bu 2 \fB_dv\fP – Default value whose C type determines the target type. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Converts \fB_v\fP to the type inferred from \fB_dv\fP\&. Handles inplace strings by allocating a stack buffer and copying the bytes there. Indirect wrappers are automatically resolved. .SS Return .sp The converted value of the same type as \fB_dv\fP, or \fB_dv\fP on failure. .SS macro fy_generic_get_type_default .INDENT 0.0 .TP .B fy_generic_get_type_default(_type) Produce the zero/NULL default for a C type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_type\fP – A C type name. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses _Generic dispatch over a local variable of \fB_type\fP to look up the appropriate zero value from fy_generic_get_type_default_Generic_dispatch. .SS Return .sp The default value for \fB_type\fP\&. .SS macro fy_generic_cast_typed .INDENT 0.0 .TP .B fy_generic_cast_typed(_v, _type) Cast a generic value to a specific C type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Source value (any type). .IP \(bu 2 \fB_type\fP – Target C type name. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Convenience wrapper: derives the default from the type and delegates to \fBfy_generic_cast_default()\fP\&. .SS Return .sp Converted value of type \fB_type\fP\&. .SS macro fy_genericp_cast_default .INDENT 0.0 .TP .B fy_genericp_cast_default(_vp, _dv) Cast a generic pointer’s value to a C type using _Generic dispatch. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_vp\fP – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fB_dv\fP – Default value whose type determines the target. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Converted value, or \fB_dv\fP when \fB_vp\fP is NULL or type mismatch. .SS macro fy_genericp_cast_typed .INDENT 0.0 .TP .B fy_genericp_cast_typed(_vp, _type) Cast a generic pointer’s value to a specific C type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_vp\fP – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fB_type\fP – Target C type name. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Converted value of type \fB_type\fP\&. .SS fy_genericp_get_generic_sequence_handle_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic_sequence_handle) – Fallback when \fBvp\fP is NULL or not a sequence. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Sequence handle, or \fBdefault_value\fP\&. .SS fy_genericp_get_generic_mapping_handle_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic_mapping_handle) – Fallback when \fBvp\fP is NULL or not a mapping. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Mapping handle, or \fBdefault_value\fP\&. .SS fy_genericp_get_generic_default .INDENT 0.0 .TP .B fy_generic fy_genericp_get_generic_default(const fy_generic *vp, fy_generic default_value) Dereference a generic pointer, returning a default for NULL. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic) – Value returned when \fBvp\fP is NULL. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \%<*@vp> when non\-NULL, otherwise \fBdefault_value\fP\&. .SS fy_genericp_get_string_genericp .INDENT 0.0 .TP .B const fy_generic *fy_genericp_get_string_genericp(const fy_generic *vp) Return \fBvp\fP itself if it points to a direct string, or NULL. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBvp\fP when \%<*@vp> is a direct string, NULL otherwise. .SS fy_genericp_get_szstr_default .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvp\fP (const fy_generic*) – Pointer to a fy_generic, or NULL. .IP \(bu 2 \fBdefault_value\fP (fy_generic_sized_string) – Fallback when \fBvp\fP is NULL or not a string. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic_sized_string pointing into the stored data, or \fBdefault_value\fP\&. .SS macro fy_generic_cast_default_coerse .INDENT 0.0 .TP .B fy_generic_cast_default_coerse(_v, _dv) Convert a value to fy_generic first, then cast with a default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Value to convert (any supported type). .IP \(bu 2 \fB_dv\fP – Default value (determines output type). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_generic_cast_default()\fP but accepts any type for \fB_v\fP by converting it through \fBfy_to_generic()\fP before casting. .SS Return .sp Converted value of the type of \fB_dv\fP\&. .SS macro fy_generic_sequence_get_default .INDENT 0.0 .TP .B fy_generic_sequence_get_default(_seq, _idx, _dv) Retrieve a typed element from a sequence by index. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_seq\fP – fy_generic sequence value. .IP \(bu 2 \fB_idx\fP – Element index. .IP \(bu 2 \fB_dv\fP – Default value (type determines the output type). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Element cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range or type mismatch. .SS macro fy_generic_sequence_get_typed .INDENT 0.0 .TP .B fy_generic_sequence_get_typed(_seq, _idx, _type) Retrieve a typed element from a sequence by index. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_seq\fP – fy_generic sequence value. .IP \(bu 2 \fB_idx\fP – Element index. .IP \(bu 2 \fB_type\fP – C type name of the desired output type. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_generic_sequence_get_default()\fP but derives the default from \fB_type\fP\&. .SS Return .sp Element of type \fB_type\fP, or the zero/NULL default. .SS macro fy_generic_sequence_get_default_coerse .INDENT 0.0 .TP .B fy_generic_sequence_get_default_coerse(_seq, _idxv, _dv) Retrieve an element from a sequence using a generic index. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_seq\fP – Sequence. .IP \(bu 2 \fB_idxv\fP – Index as any type convertible to fy_generic (e.g. an integer). .IP \(bu 2 \fB_dv\fP – Default value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Element cast to the type of \fB_dv\fP, or \fB_dv\fP\&. .SS macro fy_generic_sequencep_get_default .INDENT 0.0 .TP .B fy_generic_sequencep_get_default(_seqp, _idx, _dv) Retrieve a typed element from a sequence pointer by index. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_seqp\fP – Pointer to a fy_generic_sequence. .IP \(bu 2 \fB_idx\fP – Element index. .IP \(bu 2 \fB_dv\fP – Default value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Element cast to the type of \fB_dv\fP, or \fB_dv\fP\&. .SS macro fy_generic_mapping_get_default .INDENT 0.0 .TP .B fy_generic_mapping_get_default(_map, _key, _dv) Look up a key in a mapping and return the typed value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_map\fP – fy_generic mapping value. .IP \(bu 2 \fB_key\fP – Key (any type; converted via \fBfy_to_generic()\fP). .IP \(bu 2 \fB_dv\fP – Default value (its C type determines the output type). .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Value cast to the type of \fB_dv\fP, or \fB_dv\fP when not found. .SS macro fy_generic_mapping_get_typed .INDENT 0.0 .TP .B fy_generic_mapping_get_typed(_map, _key, _type) Look up a key in a mapping and return the value as a specific type. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_map\fP – fy_generic mapping value. .IP \(bu 2 \fB_key\fP – Key (any type). .IP \(bu 2 \fB_type\fP – C type name of the desired output. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Value of type \fB_type\fP, or the zero/NULL default. .SS macro fy_generic_mappingp_get_default .INDENT 0.0 .TP .B fy_generic_mappingp_get_default(_mapp, _key, _dv) Look up a key in a mapping pointer and return the typed value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_mapp\fP – Pointer to a fy_generic_mapping. .IP \(bu 2 \fB_key\fP – Key (any type). .IP \(bu 2 \fB_dv\fP – Default value. .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Value cast to the type of \fB_dv\fP, or \fB_dv\fP\&. .SS macro fy_generic_mapping_get_at_default .INDENT 0.0 .TP .B fy_generic_mapping_get_at_default(_map, _idx, _dv) Get the value at index \fB_idx\fP in a mapping, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_map\fP – fy_generic mapping value .IP \(bu 2 \fB_idx\fP – Zero\-based pair index .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The value at position \fB_idx\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range. .SS macro fy_generic_mappingp_get_at_default .INDENT 0.0 .TP .B fy_generic_mappingp_get_at_default(_mapp, _idx, _dv) Get the value at index \fB_idx\fP in a mapping pointer, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_mapp\fP – Pointer to fy_generic_mapping .IP \(bu 2 \fB_idx\fP – Zero\-based pair index .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The value at position \fB_idx\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range. .SS macro fy_generic_mapping_get_key_at_default .INDENT 0.0 .TP .B fy_generic_mapping_get_key_at_default(_map, _idx, _dv) Get the key at index \fB_idx\fP in a mapping, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_map\fP – fy_generic mapping value .IP \(bu 2 \fB_idx\fP – Zero\-based pair index .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The key at position \fB_idx\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range. .SS macro fy_generic_mappingp_get_key_at_default .INDENT 0.0 .TP .B fy_generic_mappingp_get_key_at_default(_mapp, _idx, _dv) Get the key at index \fB_idx\fP in a mapping pointer, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_mapp\fP – Pointer to fy_generic_mapping .IP \(bu 2 \fB_idx\fP – Zero\-based pair index .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The key at position \fB_idx\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range. .SS fy_get_generic_direct_collection_type .INDENT 0.0 .TP .B enum fy_generic_type fy_get_generic_direct_collection_type(fy_generic v) Determine whether a direct generic value is a sequence or mapping. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – A direct fy_generic value (no indirection) .UNINDENT .UNINDENT .UNINDENT .SS Return .sp FYGT_SEQUENCE, FYGT_MAPPING, or FYGT_INVALID if \fBv\fP is not a direct collection. .SS macro fy_generic_get_default .INDENT 0.0 .TP .B fy_generic_get_default(_colv, _key, _dv) Get an element from a collection by key or index, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_colv\fP – Collection value (fy_generic, sequence handle, or mapping handle) .IP \(bu 2 \fB_key\fP – Key for mappings, or integer index for sequences .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Works uniformly on sequences and mappings. For mappings, \fB_key\fP is converted to a fy_generic and used as the lookup key. For sequences, \fB_key\fP is coerced to a size_t index. Accepts fy_generic, fy_generic_sequence_handle, or fy_generic_mapping_handle as \fB_colv\fP\&. .SS Return .sp The element at \fB_key\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if not found or wrong type. .SS macro fy_generic_get_at_default .INDENT 0.0 .TP .B fy_generic_get_at_default(_colv, _idx, _dv) Get an element from a collection at a numeric index, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_colv\fP – Collection value (fy_generic, sequence handle, or mapping handle) .IP \(bu 2 \fB_idx\fP – Zero\-based integer index .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Works uniformly on sequences and mappings. For mappings, \fB_idx\fP selects the pair value. Accepts fy_generic, fy_generic_sequence_handle, or fy_generic_mapping_handle as \fB_colv\fP\&. .SS Return .sp The element at \fB_idx\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range. .SS macro fy_generic_get_key_at_default .INDENT 0.0 .TP .B fy_generic_get_key_at_default(_colv, _idx, _dv) Get the KEY at a numeric index from a collection, typed via default. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_colv\fP – Collection value (fy_generic, sequence handle, or mapping handle) .IP \(bu 2 \fB_idx\fP – Zero\-based integer index .IP \(bu 2 \fB_dv\fP – Default value (type determines the return type) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp For mappings, returns the key of the pair at \fB_idx\fP\&. For sequences, returns the element at \fB_idx\fP (keys are the elements themselves). .SS Return .sp The key at \fB_idx\fP cast to the type of \fB_dv\fP, or \fB_dv\fP if out of range. .SS fy_get_len_genericp .INDENT 0.0 .TP .B size_t fy_get_len_genericp(const void *p) Return element/character count of a fy_generic collection or string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBp\fP (const void*) – Pointer to a fy_generic value .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Resolves indirect values; returns count for sequences and mappings, byte length for strings. .SS Return .sp Element count (collection) or string length in bytes; 0 for scalar types or NULL. .SS macro fy_generic_len .INDENT 0.0 .TP .B fy_generic_len(_colv) Return the number of elements in a collection or characters in a string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_colv\fP – Collection or string value .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Accepts fy_generic, fy_generic_sequence_handle, or fy_generic_mapping_handle. For strings, returns the byte length. For scalars, returns 0. .SS Return .sp Element count, pair count, or string length; 0 for non\-collection scalars. .SS enum fy_generic_schema .INDENT 0.0 .TP .B enum fy_generic_schema YAML/JSON schema variant used during parsing and builder operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGS_AUTO Automatically select schema based on input .TP .B FYGS_YAML1_2_FAILSAFE YAML 1.2 failsafe schema (all values are strings) .TP .B FYGS_YAML1_2_CORE YAML 1.2 core schema .TP .B FYGS_YAML1_2_JSON YAML 1.2 JSON schema .TP .B FYGS_YAML1_1_FAILSAFE YAML 1.1 failsafe schema .TP .B FYGS_YAML1_1 YAML 1.1 schema .TP .B FYGS_YAML1_1_PYYAML YAML 1.1 with PyYAML quirks .TP .B FYGS_JSON JSON schema .TP .B FYGS_PYTHON Python\-compatible schema .UNINDENT .SS fy_generic_schema_get_text .INDENT 0.0 .TP .B const char *fy_generic_schema_get_text(enum fy_generic_schema schema) Return a human\-readable name for \fBschema\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBschema\fP (enum fy_generic_schema) – A fy_generic_schema value .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A static NUL\-terminated string describing the schema, or “unknown” for invalid values. .SS enum fy_gb_cfg_flags .INDENT 0.0 .TP .B enum fy_gb_cfg_flags Generic builder configuration flags. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGBCF_SCHEMA_AUTO Auto\-detect schema from content .TP .B FYGBCF_SCHEMA_YAML1_2_FAILSAFE Use YAML 1.2 failsafe schema .TP .B FYGBCF_SCHEMA_YAML1_2_CORE Use YAML 1.2 core schema .TP .B FYGBCF_SCHEMA_YAML1_2_JSON Use YAML 1.2 JSON schema .TP .B FYGBCF_SCHEMA_YAML1_1_FAILSAFE Use YAML 1.1 failsafe schema .TP .B FYGBCF_SCHEMA_YAML1_1 Use YAML 1.1 schema .TP .B FYGBCF_SCHEMA_YAML1_1_PYYAML Use YAML 1.1 with PyYAML quirks .TP .B FYGBCF_SCHEMA_JSON Use JSON schema .TP .B FYGBCF_SCHEMA_PYTHON Use Python\-compatible schema .TP .B FYGBCF_OWNS_ALLOCATOR Builder will destroy the allocator on cleanup .TP .B FYGBCF_CREATE_ALLOCATOR Builder creates its own allocator .TP .B FYGBCF_DUPLICATE_KEYS_DISABLED Reject duplicate mapping keys .TP .B FYGBCF_DEDUP_ENABLED Enable string/value deduplication .TP .B FYGBCF_SCOPE_LEADER Builder is the scope leader (owns the scope) .TP .B FYGBCF_CREATE_TAG Create an allocator tag on setup .TP .B FYGBCF_TRACE Enable diagnostic tracing .UNINDENT .SS Description .sp Schema selection occupies bits 0\-3 (FYGBCF_SCHEMA_* values); remaining bits are boolean flags. Pass to fy_generic_builder_cfg.flags or \fBfy_generic_builder_create_in_place()\fP\&. .SS struct fy_generic_builder_cfg .INDENT 0.0 .TP .B struct fy_generic_builder_cfg Configuration for creating a generic builder. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B flags Configuration flags (see enum fy_gb_cfg_flags) .TP .B allocator Optional pre\-existing allocator to use; NULL lets the builder create one .TP .B parent Optional parent builder for scoped (child) builders .TP .B estimated_max_size Hint for initial allocator capacity (0 = use default) .TP .B diag Optional diagnostics context; NULL = no diagnostics .UNINDENT .SS enum fy_gb_flags .INDENT 0.0 .TP .B enum fy_gb_flags Runtime state flags for a generic builder instance. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX enum fy_gb_flags { FYGBF_NONE, FYGBF_SCOPE_LEADER, FYGBF_DEDUP_ENABLED, FYGBF_DEDUP_CHAIN, FYGBF_OWNS_ALLOCATOR, FYGBF_CREATED_TAG }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGBF_NONE No flags set .TP .B FYGBF_SCOPE_LEADER Builder is the scope leader .TP .B FYGBF_DEDUP_ENABLED Deduplication is active on this builder .TP .B FYGBF_DEDUP_CHAIN All builders in the chain have deduplication enabled .TP .B FYGBF_OWNS_ALLOCATOR Builder owns and will destroy the allocator .TP .B FYGBF_CREATED_TAG Builder created a tag on the allocator .UNINDENT .SS Description .sp 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. .SS fy_generic_builder_setup .INDENT 0.0 .TP .B int fy_generic_builder_setup(struct fy_generic_builder *gb, const struct fy_generic_builder_cfg *cfg) Initialize a pre\-allocated generic builder structure. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Pointer to an already\-allocated fy_generic_builder to initialize .IP \(bu 2 \fBcfg\fP (const struct fy_generic_builder_cfg*) – Configuration; NULL uses defaults .UNINDENT .UNINDENT .UNINDENT .SS Return .sp 0 on success, \-1 on error. .SS fy_generic_builder_cleanup .INDENT 0.0 .TP .B void fy_generic_builder_cleanup(struct fy_generic_builder *gb) Release resources held by a builder initialized via \fBfy_generic_builder_setup()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder to clean up .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Does NOT free \fBgb\fP itself (mirrors \fBfy_generic_builder_setup()\fP). .SS fy_generic_builder_create .INDENT 0.0 .TP .B struct fy_generic_builder *fy_generic_builder_create(const struct fy_generic_builder_cfg *cfg) Heap\-allocate and initialize a generic builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct fy_generic_builder_cfg*) – Configuration; NULL uses defaults .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Newly allocated builder, or NULL on error. Free with \fBfy_generic_builder_destroy()\fP\&. .SS fy_generic_builder_destroy .INDENT 0.0 .TP .B void fy_generic_builder_destroy(struct fy_generic_builder *gb) Destroy and free a builder created by \fBfy_generic_builder_create()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder to destroy (may be NULL) .UNINDENT .UNINDENT .UNINDENT .SS fy_generic_builder_reset .INDENT 0.0 .TP .B void fy_generic_builder_reset(struct fy_generic_builder *gb) Reset a builder to its initial empty state without freeing it. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder to reset .UNINDENT .UNINDENT .UNINDENT .SS Description .sp All previously built values become invalid after reset. .SS fy_gb_alloc .INDENT 0.0 .TP .B void *fy_gb_alloc(struct fy_generic_builder *gb, size_t size, size_t align) Allocate raw bytes from the builder’s arena. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBsize\fP (size_t) – Bytes to allocate .IP \(bu 2 \fBalign\fP (size_t) – Required alignment in bytes .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to allocated memory, or NULL on failure. .SS fy_gb_free .INDENT 0.0 .TP .B void fy_gb_free(struct fy_generic_builder *gb, void *ptr) Release a previously allocated block back to the builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBptr\fP (void*) – Pointer returned by \fBfy_gb_alloc()\fP .UNINDENT .UNINDENT .UNINDENT .SS fy_gb_trim .INDENT 0.0 .TP .B void fy_gb_trim(struct fy_generic_builder *gb) Trim excess reserved capacity in the builder’s allocator. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS fy_gb_store .INDENT 0.0 .TP .B const void *fy_gb_store(struct fy_generic_builder *gb, const void *data, size_t size, size_t align) Copy \fBsize\fP bytes of \fBdata\fP into the builder’s arena. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBdata\fP (const void*) – Source data .IP \(bu 2 \fBsize\fP (size_t) – Bytes to copy .IP \(bu 2 \fBalign\fP (size_t) – Required alignment .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the stored copy inside the arena, or NULL on failure. .SS fy_gb_storev .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBiov\fP (const struct iovec*) – Array of iovec descriptors .IP \(bu 2 \fBiovcnt\fP (unsigned int) – Number of iovec entries .IP \(bu 2 \fBalign\fP (size_t) – Required alignment .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the contiguous stored copy, or NULL on failure. .SS fy_gb_lookupv .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBiov\fP (const struct iovec*) – Array of iovec descriptors describing the data to find .IP \(bu 2 \fBiovcnt\fP (unsigned int) – Number of iovec entries .IP \(bu 2 \fBalign\fP (size_t) – Required alignment .UNINDENT .UNINDENT .UNINDENT .SS Description .sp If deduplication is enabled, returns a pointer to an existing equal block. Otherwise returns NULL .SS Return .sp Pointer to existing copy, or NULL on failure. .SS fy_gb_lookup .INDENT 0.0 .TP .B 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). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBdata\fP (const void*) – Data to find or store .IP \(bu 2 \fBsize\fP (size_t) – Byte size of \fBdata\fP .IP \(bu 2 \fBalign\fP (size_t) – Required alignment .UNINDENT .UNINDENT .UNINDENT .SS Description .sp If deduplication is enabled, returns a pointer to an existing equal block. Otherwise returns NULL .SS Return .sp Pointer to existing copy, or NULL on failure. .SS fy_gb_get_allocator_info .INDENT 0.0 .TP .B struct fy_allocator_info *fy_gb_get_allocator_info(struct fy_generic_builder *gb) Retrieve statistics about the builder’s allocator. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to allocator info (valid until the next allocation), or NULL. .SS fy_gb_release .INDENT 0.0 .TP .B void fy_gb_release(struct fy_generic_builder *gb, const void *ptr, size_t size) Release a reference to an arena allocation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBptr\fP (const void*) – Pointer previously returned by a store/alloc call .IP \(bu 2 \fBsize\fP (size_t) – Size that was allocated .UNINDENT .UNINDENT .UNINDENT .SS fy_gb_allocation_failures .INDENT 0.0 .TP .B uint64_t fy_gb_allocation_failures(struct fy_generic_builder *gb) Return number of allocation failures since last reset. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp Count of allocation failures. .SS fy_generic_builder_set_userdata .INDENT 0.0 .TP .B void *fy_generic_builder_set_userdata(struct fy_generic_builder *gb, void *userdata) Attach arbitrary user data to a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBuserdata\fP (void*) – Pointer to user\-supplied data .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The previous userdata pointer. .SS fy_generic_builder_get_userdata .INDENT 0.0 .TP .B void *fy_generic_builder_get_userdata(struct fy_generic_builder *gb) Retrieve user data previously attached to a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The userdata pointer, or NULL if not set. .SS fy_generic_builder_create_in_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBflags\fP (enum fy_gb_cfg_flags) – Configuration flags (see enum fy_gb_cfg_flags) .IP \(bu 2 \fBparent\fP (struct fy_generic_builder*) – Optional parent builder; NULL for standalone .IP \(bu 2 \fBbuffer\fP (void*) – Caller\-supplied backing buffer (typically alloca’d or stack\-allocated) .IP \(bu 2 \fBsize\fP (size_t) – Size of \fBbuffer\fP in bytes; must be >= FY_GENERIC_BUILDER_LINEAR_IN_PLACE_MIN_SIZE .UNINDENT .UNINDENT .UNINDENT .SS Description .sp The builder uses \fBbuffer\fP as its backing store; no heap allocation is required. The resulting builder does NOT need to be destroyed (no \fBfy_generic_builder_destroy()\fP call). If the buffer runs out, operations fail with allocation errors. .SS Return .sp Pointer to the builder (embedded in \fBbuffer\fP), or NULL on error. .SS fy_generic_builder_get_allocator .INDENT 0.0 .TP .B struct fy_allocator *fy_generic_builder_get_allocator(struct fy_generic_builder *gb) Return the allocator used by a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the underlying fy_allocator, or NULL. .SS fy_generic_builder_get_cfg .INDENT 0.0 .TP .B const struct fy_generic_builder_cfg *fy_generic_builder_get_cfg(struct fy_generic_builder *gb) Return the configuration used to create a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Pointer to the fy_generic_builder_cfg, or NULL for in\-place builders. .SS fy_generic_builder_get_flags .INDENT 0.0 .TP .B enum fy_gb_flags fy_generic_builder_get_flags(struct fy_generic_builder *gb) Return the runtime flags of a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The current fy_gb_flags bitmask. .SS fy_generic_builder_get_free .INDENT 0.0 .TP .B size_t fy_generic_builder_get_free(struct fy_generic_builder *gb) Return available free bytes in the builder’s current arena. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Bytes available before the next arena extension or failure. .SS fy_generic_builder_contains_out_of_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBv\fP (fy_generic) – Out\-of\-place generic value .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true if the pointer inside \fBv\fP points into \fBgb\fP‘s arena. .SS fy_generic_builder_contains .INDENT 0.0 .TP .B bool fy_generic_builder_contains(struct fy_generic_builder *gb, fy_generic v) Check whether a generic value is owned by this builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder (may be NULL) .IP \(bu 2 \fBv\fP (fy_generic) – Value to test .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Inplace values are always considered owned; invalid values are never owned. .SS Return .sp true if \fBv\fP is inplace or its pointer lives in \fBgb\fP‘s arena. .SS fy_generic_builder_get_scope_leader .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The scope\-leader builder in the chain, or NULL. .SS fy_generic_builder_get_export_builder .INDENT 0.0 .TP .B struct fy_generic_builder *fy_generic_builder_get_export_builder(struct fy_generic_builder *gb) Return the builder to which values should be exported. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp The export builder is the scope\-leader’s parent (or the scope\-leader itself if at the root). .SS Return .sp The export builder, or NULL. .SS fy_generic_builder_export .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder (the source scope) .IP \(bu 2 \fBv\fP (fy_generic) – Value to export .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Ensures that \fBv\fP is owned by the export builder so it survives beyond the scope of the current (child) builder. .SS Return .sp The exported value (possibly a copy), or fy_invalid on error. .SS fy_gb_string_size_create_out_of_place .INDENT 0.0 .TP .B 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 \fBlen\fP in the builder’s arena. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBstr\fP (const char*) – String data (need not be NUL\-terminated) .IP \(bu 2 \fBlen\fP (size_t) – String length in bytes .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Out\-of\-place fy_generic string, or fy_invalid on allocation failure. .SS fy_gb_string_create_out_of_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBstr\fP (const char*) – NUL\-terminated string .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Out\-of\-place fy_generic string, or fy_invalid on allocation failure. .SS fy_gb_szstr_create_out_of_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBszstr\fP (const fy_generic_sized_string) – Sized string (length + pointer) .UNINDENT .UNINDENT .UNINDENT .SS Return .sp Out\-of\-place fy_generic string, or fy_invalid on allocation failure. .SS fy_gb_string_size_create .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBstr\fP (const char*) – String data .IP \(bu 2 \fBlen\fP (size_t) – Length in bytes .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp fy_generic string value, or fy_invalid on allocation failure. .SS macro FY_GENERIC_GB_LVAL_TEMPLATE .INDENT 0.0 .TP .B FY_GENERIC_GB_LVAL_TEMPLATE(_ctype, _gtype, _gttype, _xctype, _xgtype, _xminv, _xmaxv, _default_v) Generate fy_gb__create_out_of_place() and fy_gb__create() for C type \fB_ctype\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_ctype\fP – C type (e.g. int, double) .IP \(bu 2 \fB_gtype\fP – Name token used in the generated function names (e.g. int, double) .IP \(bu 2 \fB_gttype\fP – Generic type tag (e.g. INT, FLOAT) — unused in generated code .IP \(bu 2 \fB_xctype\fP – Cast destination type for the underlying primitive creator .IP \(bu 2 \fB_xgtype\fP – Base type creator (int_type, uint_type, float_type, etc.) .IP \(bu 2 \fB_xminv\fP – Minimum value (unused at runtime; kept for documentation) .IP \(bu 2 \fB_xmaxv\fP – Maximum value (unused at runtime) .IP \(bu 2 \fB_default_v\fP – Default value (unused at runtime) .UNINDENT .UNINDENT .UNINDENT .SS macro fy_gb_to_generic_outofplace_put .INDENT 0.0 .TP .B fy_gb_to_generic_outofplace_put(_gb, _v) Encode \fB_v\fP as an out\-of\-place generic using the builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fB_v\fP – Value of any supported C type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Uses _Generic to select the appropriate fy_gb__create_out_of_place() function. .SS Return .sp Out\-of\-place fy_generic, or fy_invalid on allocation failure. .SS macro fy_gb_to_generic_value .INDENT 0.0 .TP .B fy_gb_to_generic_value(_gb, _v) Encode \fB_v\fP as a fy_generic_value using the builder for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fB_v\fP – Value to encode .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Tries inplace encoding first; falls back to the builder arena. .SS Return .sp fy_generic_value suitable for wrapping in a fy_generic struct. .SS macro fy_gb_to_generic .INDENT 0.0 .TP .B fy_gb_to_generic(_gb, _v) Encode \fB_v\fP as a fy_generic using the builder for out\-of\-place storage. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fB_v\fP – Value to encode .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic value backed by the builder’s arena (or inplace for small values). .SS macro fy_to_generic_value .INDENT 0.0 .TP .B fy_to_generic_value(_maybe_gb, \&...) Encode a value using a builder (if provided) or alloca (for inplace / short\-lived). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_maybe_gb\fP – Either a fy_generic_builder* or any other C value .IP \(bu 2 \fBellipsis\fP (ellipsis) – variable arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp If \fB_maybe_gb\fP is a fy_generic_builder*, delegates to \fBfy_gb_to_generic_value()\fP\&. Otherwise treats \fB_maybe_gb\fP as the value itself and uses \fBfy_local_to_generic_value()\fP\&. .SS Return .sp fy_generic_value for the encoded result. .SS fy_gb_string_vcreate .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBfmt\fP (const char*) – printf\-compatible format string .IP \(bu 2 \fBap\fP (va_list) – Variadic argument list .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic string, or fy_invalid on error. .SS fy_gb_string_createf .INDENT 0.0 .TP .B fy_generic fy_gb_string_createf(struct fy_generic_builder *gb, const char *fmt, \&...) Create a string generic from a printf\-style format string. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder .IP \(bu 2 \fBfmt\fP (const char*) – printf\-compatible format string .IP \(bu 2 \fBellipsis\fP (ellipsis) – Format arguments .UNINDENT .UNINDENT .UNINDENT .SS Return .sp fy_generic string, or fy_invalid on error. .SS enum fy_gb_op .INDENT 0.0 .TP .B enum fy_gb_op Operation code for generic builder operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGBOP_CREATE_INV Create an invalid (sentinel) generic .TP .B FYGBOP_CREATE_NULL Create a null generic .TP .B FYGBOP_CREATE_BOOL Create a boolean generic from scalar args .TP .B FYGBOP_CREATE_INT Create an integer generic from scalar args .TP .B FYGBOP_CREATE_FLT Create a floating\-point generic from scalar args .TP .B FYGBOP_CREATE_STR Create a string generic from scalar args .TP .B FYGBOP_CREATE_SEQ Create a sequence from an item array .TP .B FYGBOP_CREATE_MAP Create a mapping from a key/value pair array .TP .B FYGBOP_INSERT Insert elements into a sequence at a given index .TP .B FYGBOP_REPLACE Replace elements in a sequence at a given index .TP .B FYGBOP_APPEND Append elements to the end of a sequence or mapping .TP .B FYGBOP_ASSOC Associate key/value pairs into a mapping .TP .B FYGBOP_DISASSOC Remove key/value pairs from a mapping .TP .B FYGBOP_KEYS Extract all keys of a mapping as a sequence .TP .B FYGBOP_VALUES Extract all values of a mapping as a sequence .TP .B FYGBOP_ITEMS Extract all key+value pairs of a mapping as a sequence .TP .B FYGBOP_CONTAINS Test whether a collection contains given elements .TP .B FYGBOP_CONCAT Concatenate two or more sequences or mappings .TP .B FYGBOP_REVERSE Reverse the order of a sequence .TP .B FYGBOP_MERGE Deep\-merge two mappings .TP .B FYGBOP_UNIQUE Remove duplicate elements from a sequence .TP .B FYGBOP_SORT Sort a sequence using a comparator .TP .B FYGBOP_FILTER Keep elements satisfying a predicate .TP .B FYGBOP_MAP Transform each element via a function .TP .B FYGBOP_REDUCE Fold a sequence into an accumulator via a function .TP .B FYGBOP_SLICE Extract a subrange [start, end) by unsigned indices .TP .B FYGBOP_SLICE_PY Extract a subrange using Python\-style signed indices .TP .B FYGBOP_TAKE Take the first N elements of a sequence .TP .B FYGBOP_DROP Drop the first N elements of a sequence .TP .B FYGBOP_FIRST Return the first element of a sequence .TP .B FYGBOP_LAST Return the last element of a sequence .TP .B FYGBOP_REST Return all but the first element of a sequence .TP .B FYGBOP_GET Look up a value in a collection by key .TP .B FYGBOP_GET_AT Look up a value by numeric index .TP .B FYGBOP_GET_AT_PATH Traverse a nested path of keys/indices .TP .B FYGBOP_SET Set (update) a key in a mapping .TP .B FYGBOP_SET_AT Set a value at a numeric index in a sequence .TP .B FYGBOP_SET_AT_PATH Set a value at a nested path (creating nodes as needed) .TP .B FYGBOP_PARSE Parse YAML/JSON text into a generic value .TP .B FYGBOP_EMIT Emit a generic value as YAML/JSON text .TP .B FYGBOP_CONVERT Convert a generic value to a different type .UNINDENT .SS Description .sp Selects which collection or scalar operation \fBfy_generic_op()\fP / \fBfy_generic_op_args()\fP should perform. Encoded in the low 8 bits of fy_gb_op_flags via \fBFYGBOPF_OP()\fP\&. .SS typedef fy_generic_filter_pred_fn .INDENT 0.0 .TP .B bool fy_generic_filter_pred_fn(struct fy_generic_builder *gb, fy_generic v) Predicate function for filter operations. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – The active generic builder (or NULL for stack\-based operations) .IP \(bu 2 \fBv\fP (fy_generic) – The element being tested .UNINDENT .UNINDENT .UNINDENT .SS Return .sp true to keep the element, false to discard it. .SS typedef fy_generic_map_xform_fn .INDENT 0.0 .TP .B fy_generic fy_generic_map_xform_fn(struct fy_generic_builder *gb, fy_generic v) Transform function for map operations. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – The active generic builder .IP \(bu 2 \fBv\fP (fy_generic) – The element to transform .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The transformed fy_generic value. .SS typedef fy_generic_reducer_fn .INDENT 0.0 .TP .B fy_generic fy_generic_reducer_fn(struct fy_generic_builder *gb, fy_generic acc, fy_generic v) Reducer function for fold/reduce operations. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – The active generic builder .IP \(bu 2 \fBacc\fP (fy_generic) – The running accumulator value .IP \(bu 2 \fBv\fP (fy_generic) – The current element .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The new accumulator value. .SS struct fy_op_common_args .INDENT 0.0 .TP .B struct fy_op_common_args Arguments common to all collection operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_common_args { size_t count; const fy_generic *items; struct fy_thread_pool *tp; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B count Number of elements in \fBitems\fP (x2 for mapping pair arrays) .TP .B items Pointer to the element (or key/value pair) array .TP .B tp Optional thread pool for parallel operations (NULL = single\-threaded) .UNINDENT .SS Description .sp Embedded as the first member in every fy_op_*_args struct so that \fBfy_generic_op_args()\fP can read the item array uniformly regardless of which opcode is used. .sp 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. .SS struct fy_op_create_scalar_args .INDENT 0.0 .TP .B struct fy_op_create_scalar_args Arguments for scalar creation operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } ; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args (count/items unused for scalars) .TP .B {unnamed_union} anonymous .TP .B bval Boolean value (FYGBOP_CREATE_BOOL) .TP .B fval Double value (FYGBOP_CREATE_FLT) .TP .B ival Decorated integer value (FYGBOP_CREATE_INT) .TP .B sval Sized string value (FYGBOP_CREATE_STR) .UNINDENT .SS Description .sp Used by FYGBOP_CREATE_BOOL, FYGBOP_CREATE_INT, FYGBOP_CREATE_FLT, and FYGBOP_CREATE_STR. .SS struct fy_op_sort_args .INDENT 0.0 .TP .B struct fy_op_sort_args Arguments for FYGBOP_SORT. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_sort_args { struct fy_op_common_args common; int (*cmp_fn)(fy_generic a, fy_generic b); } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B cmp_fn Comparator returning negative/zero/positive; NULL uses default ordering .UNINDENT .SS struct fy_op_insert_replace_get_set_at_args .INDENT 0.0 .TP .B struct fy_op_insert_replace_get_set_at_args Arguments for index\-based operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_insert_replace_get_set_at_args { struct fy_op_common_args common; size_t idx; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args (items to insert/replace; unused for GET_AT) .TP .B idx Zero\-based target index .UNINDENT .SS Description .sp Used by FYGBOP_INSERT, FYGBOP_REPLACE, FYGBOP_GET_AT, and FYGBOP_SET_AT. .SS struct fy_op_keys_values_items_args .INDENT 0.0 .TP .B struct fy_op_keys_values_items_args Arguments for key/value extraction operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_keys_values_items_args { struct fy_op_common_args common; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .UNINDENT .SS Description .sp Used by FYGBOP_KEYS, FYGBOP_VALUES, and FYGBOP_ITEMS. No extra fields beyond the common args are needed. .SS struct fy_op_filter_args .INDENT 0.0 .TP .B struct fy_op_filter_args Arguments for FYGBOP_FILTER. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 } ; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B {unnamed_union} anonymous .TP .B fn Filter predicate function pointer .TP .B blk Filter predicate block (Clang __BLOCKS__ only) .UNINDENT .SS struct fy_op_map_args .INDENT 0.0 .TP .B struct fy_op_map_args Arguments for FYGBOP_MAP. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 } ; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B {unnamed_union} anonymous .TP .B fn Transform function pointer .TP .B blk Transform block (Clang __BLOCKS__ only) .UNINDENT .SS struct fy_op_reduce_args .INDENT 0.0 .TP .B struct fy_op_reduce_args Arguments for FYGBOP_REDUCE. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B {unnamed_union} anonymous .TP .B fn Reducer function pointer .TP .B blk Reducer block (Clang __BLOCKS__ only) .TP .B acc Initial accumulator value .UNINDENT .SS struct fy_op_filter_map_reduce_common .INDENT 0.0 .TP .B struct fy_op_filter_map_reduce_common Type\-erased common layout for filter/map/reduce. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_filter_map_reduce_common { struct fy_op_common_args common; union { void (*fn)(void); } ; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B {unnamed_union} anonymous .TP .B fn Type\-erased function pointer .UNINDENT .SS Description .sp Used internally so that the dispatcher can access the function pointer uniformly before casting it to the appropriate typed function/block. .SS enum fy_op_parse_flags .INDENT 0.0 .TP .B enum fy_op_parse_flags Flags for FYGBOP_PARSE operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYOPPF_DISABLE_DIRECTORY Do not include a document\-state directory in the result .TP .B FYOPPF_MULTI_DOCUMENT Allow multiple YAML documents in the input .TP .B FYOPPF_TRACE Enable parser trace output for debugging .TP .B FYOPPF_DONT_RESOLVE Skip tag/anchor resolution (used by the YAML test\-suite) .TP .B FYOPPF_INPUT_TYPE_STRING Input data is a NUL\-terminated or sized string .TP .B FYOPPF_INPUT_TYPE_FILENAME Input data is a filename (const char *) .TP .B FYOPPF_INPUT_TYPE_INT_FD Input data is a file descriptor (int cast to void *) .TP .B FYOPPF_INPUT_TYPE_STDIN Read input from stdin (input_data ignored) .TP .B FYOPPF_MODE_AUTO Auto\-detect YAML version / JSON from content .TP .B FYOPPF_MODE_YAML_1_1 Force YAML 1.1 parsing rules .TP .B FYOPPF_MODE_YAML_1_2 Force YAML 1.2 parsing rules .TP .B FYOPPF_MODE_YAML_1_3 Force YAML 1.3 parsing rules .TP .B FYOPPF_MODE_JSON Force JSON parsing rules .TP .B FYOPPF_MODE_YAML_1_1_PYYAML Force YAML 1.1 PyYAML\-compatible parsing rules .TP .B FYOPPF_COLLECT_DIAG Collect diagnostic messages into the result .TP .B FYOPPF_KEEP_COMMENTS Preserve comments in the parsed representation .TP .B FYOPPF_CREATE_MARKERS Attach position markers to parsed nodes .TP .B FYOPPF_KEEP_STYLE Preserve original scalar/collection style information .TP .B FYOPPF_KEEP_FAILSAFE_STR Keep failsafe\-schema plain string tags .UNINDENT .SS Description .sp Control how input is located and how the YAML parser behaves during a \fBfy_parse()\fP / \fBfy_local_parse()\fP / \fBfy_gb_parse()\fP call. .SS struct fy_op_parse_args .INDENT 0.0 .TP .B struct fy_op_parse_args Arguments for FYGBOP_PARSE. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_parse_args { struct fy_op_common_args common; enum fy_op_parse_flags flags; void *input_data; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args (items may hold a schema override sequence) .TP .B flags Parse configuration flags (input type, mode, options) .TP .B input_data Input source; interpretation depends on FYOPPF_INPUT_TYPE_*: STRING: const char *, FILENAME: const char *, INT_FD: (void *)(uintptr_t)fd, STDIN: ignored .UNINDENT .SS enum fy_op_emit_flags .INDENT 0.0 .TP .B enum fy_op_emit_flags Flags for FYGBOP_EMIT operations. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYOPEF_DISABLE_DIRECTORY Do not include a document\-state directory in the output .TP .B FYOPEF_MULTI_DOCUMENT Emit multiple YAML documents (stream) .TP .B FYOPEF_TRACE Enable emitter trace output for debugging .TP .B FYOPEF_NO_ENDING_NEWLINE Do not append a trailing newline .TP .B FYOPEF_WIDTH_ADAPT_TO_TERMINAL Adapt line width to the current terminal width .TP .B FYOPEF_OUTPUT_COMMENTS Include inline comments in the output .TP .B FYOPEF_OUTPUT_TYPE_STRING Emit to a NUL\-terminated string (output_data = char **) .TP .B FYOPEF_OUTPUT_TYPE_FILENAME Emit to a file by name (output_data = const char *) .TP .B FYOPEF_OUTPUT_TYPE_INT_FD Emit to a file descriptor (output_data = (void *)fd) .TP .B FYOPEF_OUTPUT_TYPE_STDOUT Emit to stdout .TP .B FYOPEF_OUTPUT_TYPE_STDERR Emit to stderr .TP .B FYOPEF_MODE_AUTO Auto\-select output format from schema .TP .B FYOPEF_MODE_YAML_1_1 Emit YAML 1.1 .TP .B FYOPEF_MODE_YAML_1_2 Emit YAML 1.2 .TP .B FYOPEF_MODE_YAML_1_3 Emit YAML 1.3 .TP .B FYOPEF_MODE_JSON Emit JSON .TP .B FYOPEF_MODE_YAML_1_1_PYYAML Emit YAML 1.1 PyYAML\-compatible .TP .B FYOPEF_COLOR_AUTO Auto\-detect terminal color support .TP .B FYOPEF_COLOR_NONE Disable color output .TP .B FYOPEF_COLOR_FORCE Force color output .TP .B FYOPEF_INDENT_DEFAULT Use the library default indent (usually 2) .TP .B FYOPEF_INDENT_1 1\-space indent .TP .B FYOPEF_INDENT_2 2\-space indent .TP .B FYOPEF_INDENT_3 3\-space indent .TP .B FYOPEF_INDENT_4 4\-space indent .TP .B FYOPEF_INDENT_6 6\-space indent .TP .B FYOPEF_INDENT_8 8\-space indent (maximum) .TP .B FYOPEF_WIDTH_DEFAULT Use default line width (typically infinite) .TP .B FYOPEF_WIDTH_80 Wrap at 80 columns .TP .B FYOPEF_WIDTH_132 Wrap at 132 columns .TP .B FYOPEF_WIDTH_INF Infinite line width (no wrapping) .TP .B FYOPEF_STYLE_DEFAULT Use the library default style .TP .B FYOPEF_STYLE_BLOCK Block style .TP .B FYOPEF_STYLE_FLOW Flow style .TP .B FYOPEF_STYLE_PRETTY Pretty\-printed style .TP .B FYOPEF_STYLE_COMPACT Compact (minimal whitespace) style .TP .B FYOPEF_STYLE_ONELINE Single\-line style .UNINDENT .SS Description .sp Control output destination, YAML/JSON version, indentation, line width, and formatting style for \fBfy_emit()\fP / \fBfy_local_emit()\fP / \fBfy_gb_emit()\fP calls. .SS struct fy_op_emit_args .INDENT 0.0 .TP .B struct fy_op_emit_args Arguments for FYGBOP_EMIT. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_emit_args { struct fy_op_common_args common; enum fy_op_emit_flags flags; void *output_data; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args (items may hold schema override sequences) .TP .B flags Emit configuration flags (output type, mode, style, etc.) .TP .B output_data Output destination; interpretation depends on FYOPEF_OUTPUT_TYPE_*: STRING: char **, FILENAME: const char *, INT_FD: (void *)(uintptr_t)fd, STDOUT/STDERR: ignored .UNINDENT .SS struct fy_op_slice_args .INDENT 0.0 .TP .B struct fy_op_slice_args Arguments for FYGBOP_SLICE. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_slice_args { struct fy_op_common_args common; size_t start; size_t end; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B start Starting index (inclusive, zero\-based) .TP .B end Ending index (exclusive); use SIZE_MAX for “to the end” .UNINDENT .SS struct fy_op_slice_py_args .INDENT 0.0 .TP .B struct fy_op_slice_py_args Arguments for FYGBOP_SLICE_PY. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_slice_py_args { struct fy_op_common_args common; ssize_t start; ssize_t end; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B start Starting index (inclusive; negative counts from end) .TP .B end Ending index (exclusive; negative counts from end) .UNINDENT .SS Description .sp Like fy_op_slice_args but uses Python\-style signed indices where negative values count backwards from the end of the sequence. .SS struct fy_op_take_args .INDENT 0.0 .TP .B struct fy_op_take_args Arguments for FYGBOP_TAKE. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_take_args { struct fy_op_common_args common; size_t n; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B n Number of elements to take from the start of the sequence .UNINDENT .SS struct fy_op_drop_args .INDENT 0.0 .TP .B struct fy_op_drop_args Arguments for FYGBOP_DROP. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_drop_args { struct fy_op_common_args common; size_t n; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B n Number of elements to drop from the start of the sequence .UNINDENT .SS struct fy_op_convert_args .INDENT 0.0 .TP .B struct fy_op_convert_args Arguments for FYGBOP_CONVERT. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_op_convert_args { struct fy_op_common_args common; enum fy_generic_type type; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B common Embedded common args .TP .B type Target generic type to convert the input value to .UNINDENT .SS enum fy_gb_op_flags .INDENT 0.0 .TP .B enum fy_gb_op_flags Combined opcode + modifier flags for \fBfy_generic_op()\fP\&. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGBOPF_CREATE_SEQ Create a sequence .TP .B FYGBOPF_CREATE_MAP Create a mapping .TP .B FYGBOPF_INSERT Insert into a sequence at an index .TP .B FYGBOPF_REPLACE Replace elements at an index .TP .B FYGBOPF_APPEND Append to a collection .TP .B FYGBOPF_ASSOC Associate key/value pairs into a mapping .TP .B FYGBOPF_DISASSOC Remove keys from a mapping .TP .B FYGBOPF_KEYS Extract mapping keys as a sequence .TP .B FYGBOPF_VALUES Extract mapping values as a sequence .TP .B FYGBOPF_ITEMS Extract mapping pairs as a sequence .TP .B FYGBOPF_CONTAINS Test for element membership .TP .B FYGBOPF_CONCAT Concatenate collections .TP .B FYGBOPF_REVERSE Reverse a sequence .TP .B FYGBOPF_MERGE Deep\-merge mappings .TP .B FYGBOPF_UNIQUE Remove duplicates from a sequence .TP .B FYGBOPF_SORT Sort a sequence .TP .B FYGBOPF_FILTER Filter elements by predicate .TP .B FYGBOPF_MAP Transform each element .TP .B FYGBOPF_REDUCE Fold a sequence into an accumulator .TP .B FYGBOPF_SLICE Unsigned index slice .TP .B FYGBOPF_SLICE_PY Python\-style signed slice .TP .B FYGBOPF_TAKE Take first N elements .TP .B FYGBOPF_DROP Drop first N elements .TP .B FYGBOPF_FIRST Return first element .TP .B FYGBOPF_LAST Return last element .TP .B FYGBOPF_REST Return all but first element .TP .B FYGBOPF_GET Lookup by key .TP .B FYGBOPF_GET_AT Lookup by index .TP .B FYGBOPF_GET_AT_PATH Traverse nested path of keys/indices .TP .B FYGBOPF_SET Set a key in a mapping .TP .B FYGBOPF_SET_AT Set element at an index .TP .B FYGBOPF_SET_AT_PATH Set value at nested path (creating intermediate nodes) .TP .B FYGBOPF_PARSE Parse YAML/JSON input .TP .B FYGBOPF_EMIT Emit generic value as YAML/JSON .TP .B FYGBOPF_CONVERT Convert to a different type .TP .B FYGBOPF_DONT_INTERNALIZE Skip copying items into the builder arena .TP .B FYGBOPF_DEEP_VALIDATE Recursively validate all elements .TP .B FYGBOPF_NO_CHECKS Skip all input validity checks .TP .B FYGBOPF_PARALLEL Execute in parallel using a thread pool .TP .B FYGBOPF_MAP_ITEM_COUNT Interpret \fBcount\fP as number of items, not pairs .TP .B FYGBOPF_BLOCK_FN The function/callback is a Clang block (^) .TP .B FYGBOPF_CREATE_PATH Create intermediate path nodes (like mkdir \-p) .TP .B FYGBOPF_UNSIGNED Integer scalar is unsigned (shares bit 23 with CREATE_PATH) .UNINDENT .SS Description .sp The low 8 bits select the operation (use \fBFYGBOPF_OP()\fP / FYGBOPF_* opcode constants). The upper bits are modifier flags that refine behaviour. .sp Opcode values (low 8 bits via \fBFYGBOPF_OP()\fP): .SS fy_generic_op_args .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result (may be NULL for local/alloca operations) .IP \(bu 2 \fBflags\fP (enum fy_gb_op_flags) – Opcode (low 8 bits) plus modifier flags .IP \(bu 2 \fBin\fP (fy_generic) – Primary input collection or scalar; use fy_invalid / fy_seq_empty as appropriate .IP \(bu 2 \fBargs\fP (const struct fy_generic_op_args*) – Pointer to the filled fy_generic_op_args union .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Lower\-level variant of \fBfy_generic_op()\fP for callers that prefer to fill a fy_generic_op_args union explicitly rather than using the variadic interface. .SS Return .sp The operation result, or fy_invalid on error or allocation failure. .SS fy_generic_op .INDENT 0.0 .TP .B fy_generic fy_generic_op(struct fy_generic_builder *gb, enum fy_gb_op_flags flags, \&...) Execute a generic operation using variadic arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result .IP \(bu 2 \fBflags\fP (enum fy_gb_op_flags) – Opcode (low 8 bits) plus modifier flags .IP \(bu 2 \fBellipsis\fP (ellipsis) – Operation\-specific arguments (count, items, index, function, etc.) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to the appropriate collection or scalar operation selected by \fBflags\fP\&. The remaining variadic arguments are interpreted according to the opcode; see each FYGBOPF_* constant for the expected argument list. .SS Return .sp The operation result, or fy_invalid on error or allocation failure. .SS fy_gb_sequence_create .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result .IP \(bu 2 \fBcount\fP (size_t) – Number of elements in \fBitems\fP .IP \(bu 2 \fBitems\fP (const fy_generic*) – Array of fy_generic elements to include in the sequence .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A sequence fy_generic backed by the builder arena, or fy_invalid on error. .SS fy_gb_mapping_create .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result .IP \(bu 2 \fBcount\fP (size_t) – Number of key/value PAIRS in \fBpairs\fP (i.e. half the array length) .IP \(bu 2 \fBpairs\fP (const fy_generic*) – Interleaved key/value fy_generic array .UNINDENT .UNINDENT .UNINDENT .SS Return .sp A mapping fy_generic backed by the builder arena, or fy_invalid on error. .SS fy_gb_indirect_create .INDENT 0.0 .TP .B fy_generic fy_gb_indirect_create(struct fy_generic_builder *gb, const fy_generic_indirect *gi) Create an indirect generic wrapping metadata. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result .IP \(bu 2 \fBgi\fP (const fy_generic_indirect*) – Pointer to the indirect descriptor to copy into the builder arena .UNINDENT .UNINDENT .UNINDENT .SS Description .sp An indirect value carries an anchor, tag, style, or comment alongside the actual value without changing its logical type. .SS Return .sp An FYGT_INDIRECT fy_generic, or fy_invalid on error. .SS fy_gb_alias_create .INDENT 0.0 .TP .B fy_generic fy_gb_alias_create(struct fy_generic_builder *gb, fy_generic anchor) Create an alias generic referencing an anchor value. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result .IP \(bu 2 \fBanchor\fP (fy_generic) – The fy_generic value that serves as the anchor target .UNINDENT .UNINDENT .UNINDENT .SS Return .sp An FYGT_ALIAS fy_generic, or fy_invalid on error. .SS macro fy_gb_sequence_value .INDENT 0.0 .TP .B fy_gb_sequence_value(_gb, \&...) Build a sequence fy_generic_value from variadic elements using a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fBellipsis\fP (ellipsis) – Zero or more values of any supported C type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Encodes each variadic argument via \fBfy_gb_to_generic()\fP (using \fB_gb\fP for out\-of\-place storage), then creates a sequence. With no arguments, returns fy_seq_empty_value. .SS Return .sp fy_generic_value of a sequence, or fy_seq_empty_value if no arguments. .SS macro fy_gb_sequence .INDENT 0.0 .TP .B fy_gb_sequence(_gb, \&...) Build a sequence fy_generic from variadic elements using a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fBellipsis\fP (ellipsis) – Zero or more values of any supported C type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_gb_sequence_value()\fP but wraps the result in a fy_generic struct. .SS Return .sp A sequence fy_generic, or fy_seq_empty if no arguments. .SS macro fy_gb_mapping_value .INDENT 0.0 .TP .B fy_gb_mapping_value(_gb, \&...) Build a mapping fy_generic_value from variadic key/value pairs using a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fBellipsis\fP (ellipsis) – Zero or more key/value pairs of any supported C type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Arguments must be interleaved key/value pairs. With no arguments, returns fy_map_empty_value. .SS Return .sp fy_generic_value of a mapping, or fy_map_empty_value if no arguments. .SS macro fy_gb_mapping .INDENT 0.0 .TP .B fy_gb_mapping(_gb, \&...) Build a mapping fy_generic from variadic key/value pairs using a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb\fP – Builder .IP \(bu 2 \fBellipsis\fP (ellipsis) – Zero or more key/value pairs of any supported C type .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_gb_mapping_value()\fP but wraps the result in a fy_generic struct. .SS Return .sp A mapping fy_generic, or fy_map_empty if no arguments. .SS fy_gb_create_scalar_from_text .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that owns the result .IP \(bu 2 \fBtext\fP (const char*) – Pointer to the scalar text (not necessarily NUL\-terminated) .IP \(bu 2 \fBlen\fP (size_t) – Length of \fBtext\fP in bytes .IP \(bu 2 \fBforce_type\fP (enum fy_generic_type) – If != FYGT_INVALID, force this type instead of auto\-detecting .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Interprets \fBtext\fP 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. .SS Return .sp A fy_generic of the detected (or forced) type, or fy_invalid on error. .SS fy_gb_copy_out_of_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Destination builder .IP \(bu 2 \fBv\fP (fy_generic) – Out\-of\-place source value (must not be inplace or invalid) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Recursively copies the value and all referenced data into \fBgb\fP‘s arena. This is the slow path; prefer \fBfy_gb_copy()\fP which skips the copy for inplace values. .SS Return .sp A new fy_generic backed by \fBgb\fP, or fy_invalid on allocation failure. .SS fy_gb_copy .INDENT 0.0 .TP .B fy_generic fy_gb_copy(struct fy_generic_builder *gb, fy_generic v) Copy a generic into a builder arena, skipping inplace values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Destination builder .IP \(bu 2 \fBv\fP (fy_generic) – Source value .UNINDENT .UNINDENT .UNINDENT .SS Description .sp If \fBv\fP is already stored inplace (no heap pointer), returns it unchanged. Otherwise delegates to \fBfy_gb_copy_out_of_place()\fP\&. .SS Return .sp \fBv\fP unchanged if inplace, or a deep copy backed by \fBgb\fP on success, or fy_invalid on error. .SS fy_gb_internalize_out_of_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Target builder .IP \(bu 2 \fBv\fP (fy_generic) – Out\-of\-place generic to potentially intern .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Copies \fBv\fP into \fBgb\fP‘s arena only if its pointer does not already fall within the builder’s allocated regions. If the value is already owned by \fBgb\fP, returns it unchanged. .SS Return .sp \fBv\fP (unchanged if already internal) or a copy in \fBgb\fP, or fy_invalid on error. .SS fy_gb_internalize .INDENT 0.0 .TP .B fy_generic fy_gb_internalize(struct fy_generic_builder *gb, fy_generic v) Intern a generic into a builder, skipping inplace and invalid values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Target builder .IP \(bu 2 \fBv\fP (fy_generic) – Value to intern .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Fast path: returns \fBv\fP immediately if it is invalid or inplace. Otherwise delegates to \fBfy_gb_internalize_out_of_place()\fP\&. .SS Return .sp \fBv\fP unchanged, or an interned copy in \fBgb\fP, or fy_invalid on error. .SS fy_validate_out_of_place .INDENT 0.0 .TP .B fy_generic fy_validate_out_of_place(fy_generic v) Validate an out\-of\-place generic (no builder). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Out\-of\-place generic to validate .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Checks structural and type consistency of \fBv\fP without a builder context. This is the slow path; prefer \fBfy_validate()\fP which skips validation for inplace and invalid values. .SS Return .sp \fBv\fP if valid, or fy_invalid if structural errors are found. .SS fy_validate .INDENT 0.0 .TP .B fy_generic fy_validate(fy_generic v) Validate a generic, skipping inplace and invalid values. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – Generic to validate .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBv\fP unchanged if already invalid or inplace; otherwise the result of \fBfy_validate_out_of_place()\fP\&. .SS fy_gb_validate_out_of_place .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder providing schema context .IP \(bu 2 \fBv\fP (fy_generic) – Out\-of\-place generic to validate .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBfy_validate_out_of_place()\fP but can use \fBgb\fP for schema information during validation. .SS Return .sp \fBv\fP if valid, or fy_invalid if errors are found. .SS fy_gb_validate .INDENT 0.0 .TP .B fy_generic fy_gb_validate(struct fy_generic_builder *gb, fy_generic v) Validate a generic using a builder, skipping trivial cases. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder providing schema context .IP \(bu 2 \fBv\fP (fy_generic) – Generic to validate .UNINDENT .UNINDENT .UNINDENT .SS Return .sp \fBv\fP if already invalid or inplace; otherwise the result of \fBfy_gb_validate_out_of_place()\fP\&. .SS fy_generic_relocate .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstart\fP (void*) – Old buffer start .IP \(bu 2 \fBend\fP (void*) – Old buffer end (exclusive) .IP \(bu 2 \fBv\fP (fy_generic) – Generic value to patch .IP \(bu 2 \fBd\fP (ptrdiff_t) – Delta to add to pointers (new_base \- old_base) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp When a backing buffer is reallocated (e.g. by mremap), all embedded pointers shift by \fBd\fP bytes. This function patches every pointer in \fBv\fP that falls within [@start, \fBend\fP) by adding \fBd\fP\&. .SS Return .sp The relocated fy_generic with updated pointers. .SS fy_gb_get_schema .INDENT 0.0 .TP .B enum fy_generic_schema fy_gb_get_schema(struct fy_generic_builder *gb) Return the schema currently active in a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder to query .UNINDENT .UNINDENT .UNINDENT .SS Return .sp The enum fy_generic_schema value configured for \fBgb\fP\&. .SS fy_gb_set_schema .INDENT 0.0 .TP .B void fy_gb_set_schema(struct fy_generic_builder *gb, enum fy_generic_schema schema) Set the schema for a builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder to update .IP \(bu 2 \fBschema\fP (enum fy_generic_schema) – New schema to use for subsequent operations .UNINDENT .UNINDENT .UNINDENT .SS fy_gb_set_schema_from_parser_mode .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder to update .IP \(bu 2 \fBparser_mode\fP (enum fy_parser_mode) – Parser mode whose schema to adopt .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Converts a fy_parser_mode value to the closest fy_generic_schema and calls \fBfy_gb_set_schema()\fP\&. .SS Return .sp 0 on success, \-1 if \fBparser_mode\fP has no corresponding schema. .SS fy_generic_dump_primitive .INDENT 0.0 .TP .B void fy_generic_dump_primitive(FILE *fp, int level, fy_generic vv) Dump a fy_generic value to a FILE stream for debugging. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfp\fP (FILE*) – Destination FILE stream (e.g. stderr) .IP \(bu 2 \fBlevel\fP (int) – Current indentation level (pass 0 for the top\-level call) .IP \(bu 2 \fBvv\fP (fy_generic) – Generic value to dump .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Recursively prints \fBvv\fP with indentation \fBlevel\fP to \fBfp\fP\&. Intended for development and debugging; output format is not stable. .SS macro fy_sequence_value .INDENT 0.0 .TP .B fy_sequence_value(\&...) Build a sequence fy_generic_value from variadic elements. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Optional builder followed by zero or more element values .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp fy_generic_value of a sequence, or fy_seq_empty_value if empty. .SS macro fy_sequence .INDENT 0.0 .TP .B fy_sequence(\&...) Build a sequence fy_generic from variadic elements. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Optional builder followed by zero or more element values .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Wraps \fBfy_sequence_value()\fP in a fy_generic struct. .SS Return .sp A sequence fy_generic, or fy_seq_empty if empty. .SS macro fy_mapping_value .INDENT 0.0 .TP .B fy_mapping_value(\&...) Build a mapping fy_generic_value from variadic key/value pairs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Optional builder followed by zero or more key/value pairs .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp fy_generic_value of a mapping, or fy_map_empty_value if empty. .SS macro fy_mapping .INDENT 0.0 .TP .B fy_mapping(\&...) Build a mapping fy_generic from variadic key/value pairs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Optional builder followed by zero or more key/value pairs .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Wraps \fBfy_mapping_value()\fP in a fy_generic struct. .SS Return .sp A mapping fy_generic, or fy_map_empty if empty. .SS macro fy_value .INDENT 0.0 .TP .B fy_value(_maybe_gb, \&...) Encode a value as a fy_generic using a builder or alloca. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_maybe_gb\fP – Either a fy_generic_builder* or a C value to encode .IP \(bu 2 \fBellipsis\fP (ellipsis) – Additional value args when \fB_maybe_gb\fP is a builder .UNINDENT .UNINDENT .UNINDENT .SS Description .sp If \fB_maybe_gb\fP is a fy_generic_builder*, uses \fBfy_gb_to_generic_value()\fP\&. Otherwise treats \fB_maybe_gb\fP as the value itself. .SS Return .sp A fy_generic wrapping the encoded value. .SS macro fy_foreach .INDENT 0.0 .TP .B fy_foreach(_v, _col) Iterate over every element (or key) of a collection. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_v\fP – Loop variable (lvalue) that receives each element/key .IP \(bu 2 \fB_col\fP – Collection to iterate (fy_generic sequence or mapping) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp For sequences: \fB_v\fP receives each element in order. For mappings: \fB_v\fP receives each key in order. .sp The type of \fB_v\fP determines how the element is cast via \fBfy_get_key_at_typed()\fP\&. .SS macro FY_LOCAL_OP .INDENT 0.0 .TP .B FY_LOCAL_OP(\&...) Execute a generic operation using a stack\-allocated (alloca) builder. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBellipsis\fP (ellipsis) – Same arguments as \fBfy_generic_op()\fP (flags, input, count, items, …) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a temporary fy_generic_builder backed by an alloca’d buffer and forwards the remaining arguments to \fBfy_generic_op()\fP\&. 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. .sp 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. .SS Return .sp The operation result, or fy_invalid on error. .SS macro FY_GB_OR_LOCAL_OP .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_OP(_gb_or_NULL, _flags, \&...) Dispatch to fy_generic_op or FY_LOCAL_OP based on \fB_gb_or_NULL\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_gb_or_NULL\fP – Builder pointer, or NULL to use FY_LOCAL_OP .IP \(bu 2 \fB_flags\fP – Opcode + modifiers .IP \(bu 2 \fBellipsis\fP (ellipsis) – Remaining arguments forwarded unchanged .UNINDENT .UNINDENT .UNINDENT .SS macro FY_GB_OR_LOCAL_COL .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_COL(_flags, _gb_or_first, \&...) Dispatch a single\-collection operation (no items array). .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_flags\fP – Opcode + modifiers .IP \(bu 2 \fB_gb_or_first\fP – Optional builder or first collection arg .IP \(bu 2 \fBellipsis\fP (ellipsis) – Remaining args (usually the collection when \fB_gb_or_first\fP is a builder) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp The first non\-builder argument is treated as the input collection. .SS macro FY_GB_OR_LOCAL_COL_COUNT_ITEMS .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_COL_COUNT_ITEMS(_flags, _gb_or_first, \&...) Dispatch a collection+items operation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_flags\fP – Opcode + modifiers .IP \(bu 2 \fB_gb_or_first\fP – Optional builder or first collection arg .IP \(bu 2 \fBellipsis\fP (ellipsis) – Collection (if builder given) + item arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp The first non\-builder argument is the collection; remaining arguments are encoded as the items array. .SS macro FY_GB_OR_LOCAL_COL_IDX_COUNT_ITEMS .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_COL_IDX_COUNT_ITEMS(_flags, _gb_or_first, \&...) Dispatch a collection+index+items operation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_flags\fP – Opcode + modifiers .IP \(bu 2 \fB_gb_or_first\fP – Optional builder or first collection arg .IP \(bu 2 \fBellipsis\fP (ellipsis) – Collection, index, and item arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp The first non\-builder argument is the collection, the second is the index, and remaining arguments are the items. .SS macro FY_GB_OR_LOCAL_SLICE .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_SLICE(_flags, _gb_or_first, \&...) Dispatch a half\-open slice [start, end) operation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_flags\fP – Opcode + modifier flags (e.g. FYGBOPF_SLICE). .IP \(bu 2 \fB_gb_or_first\fP – Optional builder or first sequence argument. .IP \(bu 2 \fBellipsis\fP (ellipsis) – Sequence, start index (size_t), end index (size_t). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to a builder\-backed or stack\-local slice depending on whether a leading fy_generic_builder pointer is provided. .SS macro FY_GB_OR_LOCAL_SLICE_PY .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_SLICE_PY(_flags, _gb_or_first, \&...) Dispatch a Python\-style slice operation with signed indices. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_flags\fP – Opcode + modifier flags (e.g. FYGBOPF_SLICE_PY). .IP \(bu 2 \fB_gb_or_first\fP – Optional builder or first sequence argument. .IP \(bu 2 \fBellipsis\fP (ellipsis) – Sequence, start (ssize_t), end (ssize_t). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Like \fBFY_GB_OR_LOCAL_SLICE()\fP but accepts signed (ssize_t) indices so that negative values count from the end of the sequence, matching Python slice semantics. .SS macro FY_GB_OR_LOCAL_SLICE_N .INDENT 0.0 .TP .B FY_GB_OR_LOCAL_SLICE_N(_flags, _gb_or_first, \&...) Dispatch a take\-N or drop\-N slice operation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fB_flags\fP – Opcode + modifier flags (e.g. FYGBOPF_TAKE or FYGBOPF_DROP). .IP \(bu 2 \fB_gb_or_first\fP – Optional builder or first sequence argument. .IP \(bu 2 \fBellipsis\fP (ellipsis) – Sequence, count N (size_t). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Dispatches to a builder\-backed or stack\-local take/drop depending on whether a leading fy_generic_builder pointer is provided. .SS fy_generic_emit_compact .INDENT 0.0 .TP .B int fy_generic_emit_compact(fy_generic v) Emit a generic value to stdout in compact (flow\-style) format. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to emit. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Formats \fBv\fP using flow style (all on one line) and writes the result to stdout. Intended primarily for quick debugging and interactive inspection. .SS Return .sp 0 on success, \-1 on error. .SS fy_generic_emit_default .INDENT 0.0 .TP .B int fy_generic_emit_default(fy_generic v) Emit a generic value to stdout in default (block\-style) format. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBv\fP (fy_generic) – The generic value to emit. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Formats \fBv\fP using block style (multi\-line indented) and writes the result to stdout. Intended primarily for quick debugging and interactive inspection. .SS Return .sp 0 on success, \-1 on error. .SS fy_generic_dir_get_document_count .INDENT 0.0 .TP .B int fy_generic_dir_get_document_count(fy_generic vdir) Get the number of documents in a directory generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvdir\fP (fy_generic) – The directory generic. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp A directory generic is a sequence produced by parsing with directory mode enabled. Each element is a vds (value\-with\-document\-state) generic. .SS Return .sp The number of documents, or \-1 on error. .SS fy_generic_dir_get_document_vds .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvdir\fP (fy_generic) – The directory generic. .IP \(bu 2 \fBidx\fP (size_t) – Zero\-based document index. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns the combined (root, document\-state) generic for the document at position \fBidx\fP within the directory \fBvdir\fP\&. .SS Return .sp The vds fy_generic for the requested document, or fy_invalid on error. .SS fy_generic_vds_get_root .INDENT 0.0 .TP .B fy_generic fy_generic_vds_get_root(fy_generic vds) Extract the root value from a document\-with\-state generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvds\fP (fy_generic) – The document\-with\-state generic. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp A vds generic bundles the document root together with its YAML document state. This function returns only the root value portion. .SS Return .sp The root fy_generic, or fy_invalid on error. .SS fy_generic_vds_get_document_state .INDENT 0.0 .TP .B struct fy_document_state *fy_generic_vds_get_document_state(fy_generic vds) Extract the YAML document state from a vds generic. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvds\fP (fy_generic) – The document\-with\-state generic. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp A vds generic bundles the document root together with its YAML document state. This function returns the associated \fBfy_document_state\fP pointer (version, tags, schema, etc.). .SS Return .sp Pointer to the \fBfy_document_state\fP, or NULL on error. .SS fy_generic_vds_create_from_document_state .INDENT 0.0 .TP .B 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. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBgb\fP (struct fy_generic_builder*) – Builder that will own the resulting vds generic. .IP \(bu 2 \fBvroot\fP (fy_generic) – The document root generic. .IP \(bu 2 \fBfyds\fP (struct fy_document_state*) – The YAML document state (version, tags, schema information). .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document\-with\-state (vds) generic by combining \fBvroot\fP with \fBfyds\fP into a mapping generic backed by the builder \fBgb\fP\&. .SS Return .sp The vds fy_generic, or fy_invalid on error. .SS enum fy_generic_iterator_cfg_flags .INDENT 0.0 .TP .B enum fy_generic_iterator_cfg_flags Document iterator configuration flags .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX 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 }; .EE .UNINDENT .UNINDENT .SS Constants .INDENT 0.0 .TP .B FYGICF_WANT_BODY_EVENTS Generate body events .TP .B FYGICF_WANT_DOCUMENT_BODY_EVENTS Generate document and body events .TP .B FYGICF_WANT_STREAM_DOCUMENT_BODY_EVENTS Generate stream, document and body events .TP .B FYGICF_HAS_FULL_DIRECTORY Full directory contents of vdir .TP .B FYGICF_STRIP_LABELS Strip the labels (anchors) .TP .B FYGICF_STRIP_TAGS Strip the tags .TP .B FYGICF_STRIP_COMMENTS Strip comments from the output .TP .B FYGICF_STRIP_STYLE Strip style information from the output .TP .B FYGICF_STRIP_FAILSAFE_STR Strip failsafe schema plain string tags .UNINDENT .SS Description .sp These flags control the operation of the document iterator .SS struct fy_generic_iterator_cfg .INDENT 0.0 .TP .B struct fy_generic_iterator_cfg document iterator configuration structure. .UNINDENT .SS Definition .INDENT 0.0 .INDENT 3.5 .sp .EX struct fy_generic_iterator_cfg { enum fy_generic_iterator_cfg_flags flags; fy_generic vdir; } .EE .UNINDENT .UNINDENT .SS Members .INDENT 0.0 .TP .B flags The document iterator flags .TP .B vdir The directory of the parsed input .UNINDENT .SS Description .sp Argument to the \fBfy_generic_iterator_create_cfg()\fP method. .SS fy_generic_iterator_create .INDENT 0.0 .TP .B struct fy_generic_iterator *fy_generic_iterator_create(void) Create a document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvoid\fP – no arguments .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a document iterator, that can trawl through a document without using recursion. .SS Return .sp The newly created document iterator or NULL on error .SS fy_generic_iterator_create_cfg .INDENT 0.0 .TP .B struct fy_generic_iterator *fy_generic_iterator_create_cfg(const struct fy_generic_iterator_cfg *cfg) Create a document iterator using config .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcfg\fP (const struct fy_generic_iterator_cfg*) – The document iterator to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp The newly created document iterator or NULL on error .SS fy_generic_iterator_destroy .INDENT 0.0 .TP .B void fy_generic_iterator_destroy(struct fy_generic_iterator *fygi) Destroy the given document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to destroy .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Destroy a document iterator created earlier via \fBfy_generic_iterator_create()\fP\&. .SS fy_generic_iterator_event_free .INDENT 0.0 .TP .B void fy_generic_iterator_event_free(struct fy_generic_iterator *fygi, struct fy_event \%<#\:c\:.fy_event> *fye) Free an event that was created by a document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator that created the event .IP \(bu 2 \fBfye\fP (struct fy_event \%<#\:c\:.fy_event>*) – The event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Free (possibly recycling) an event that was created by a document iterator. .SS fy_generic_iterator_stream_start .INDENT 0.0 .TP .B struct fy_event \%<#\:c\:.fy_event> *fy_generic_iterator_stream_start(struct fy_generic_iterator *fygi) Create a stream start event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a stream start event on the document iterator and advances the internal state of it accordingly. .SS Return .sp The newly created stream start event, or NULL on error. .SS fy_generic_iterator_stream_end .INDENT 0.0 .TP .B struct fy_event \%<#\:c\:.fy_event> *fy_generic_iterator_stream_end(struct fy_generic_iterator *fygi) Create a stream end event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Creates a stream end event on the document iterator and advances the internal state of it accordingly. .SS Return .sp The newly created stream end event, or NULL on error. .SS fy_generic_iterator_document_start .INDENT 0.0 .TP .B struct fy_event \%<#\:c\:.fy_event> *fy_generic_iterator_document_start(struct fy_generic_iterator *fygi, fy_generic vds) Create a document start event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to create the event .IP \(bu 2 \fBvds\fP (fy_generic) – The generic directory (or fy_null for none) .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfy_generic_iterator_document_end()\fP\&. .SS Return .sp The newly created document start event, or NULL on error. .SS fy_generic_iterator_document_end .INDENT 0.0 .TP .B struct fy_event \%<#\:c\:.fy_event> *fy_generic_iterator_document_end(struct fy_generic_iterator *fygi) Create a document end event using the iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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 \fBfy_generic_iterator_document_start()\fP can now be released. .SS Return .sp The newly created document end event, or NULL on error. .SS fy_generic_iterator_body_next .INDENT 0.0 .TP .B struct fy_event \%<#\:c\:.fy_event> *fy_generic_iterator_body_next(struct fy_generic_iterator *fygi) Create document body events until the end .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .sp 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. .sp 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. .SS Return .sp The newly created document body event or NULL at an error, or an end of the event stream. Use \fBfy_generic_iterator_get_error()\fP to check if an error occured. .SS fy_generic_iterator_generic_start .INDENT 0.0 .TP .B void fy_generic_iterator_generic_start(struct fy_generic_iterator *fygi, fy_generic v) Start a document node iteration run using a starting point .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to run with .IP \(bu 2 \fBv\fP (fy_generic) – The generic to start on .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Starts an iteration run starting at the given node. .SS fy_generic_iterator_generic_next .INDENT 0.0 .TP .B fy_generic fy_generic_iterator_generic_next(struct fy_generic_iterator *fygi) Return the next node in the iteration sequence .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to use for the iteration .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Returns a pointer to the next node iterating using as a start the node given at \fBfy_generic_iterator_node_start()\fP\&. The first node returned will be that, followed by all the remaing nodes in the subtree. .SS Return .sp The next node in the iteration sequence or NULL at the end, or if an error occured. .SS fy_generic_iterator_generate_next .INDENT 0.0 .TP .B struct fy_event \%<#\:c\:.fy_event> *fy_generic_iterator_generate_next(struct fy_generic_iterator *fygi) Create events from document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to create the event .UNINDENT .UNINDENT .UNINDENT .SS Description .sp This is a method that will handle the complex state of generating stream, document and body events on the given iterator. .sp When generation is complete a NULL event will be generated. .SS Return .sp The newly created event or NULL at an error, or an end of the event stream. Use \fBfy_generic_iterator_get_error()\fP to check if an error occured. .SS fy_generic_iterator_get_error .INDENT 0.0 .TP .B bool fy_generic_iterator_get_error(struct fy_generic_iterator *fygi) Get the error state of the document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to use for checking it’s error state. .UNINDENT .UNINDENT .UNINDENT .SS Description .sp 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. .SS Return .sp true if it was in an error state, false otherwise. .SS fy_parser_set_generic_iterator .INDENT 0.0 .TP .B int fy_parser_set_generic_iterator(struct fy_parser *fyp, enum fy_parser_event_generator_flags \%<#\:c\:.fy_parser_event_generator_flags> flags, struct fy_generic_iterator *fygi) Associate a parser with a document iterator .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBfyp\fP (struct fy_parser*) – The parser .IP \(bu 2 \fBflags\fP (enum fy_parser_event_generator_flags \%<#\:c\:.fy_parser_event_generator_flags>) – The event generation flags .IP \(bu 2 \fBfygi\fP (struct fy_generic_iterator*) – The document iterator to associate .UNINDENT .UNINDENT .UNINDENT .SS Description .sp Associate a parser with a generic iterator, that is instead of parsing the events will be generated by the generic iterator. .SS Return .sp 0 on success, \-1 on error .SH Copyright 2019-2026, Pantelis Antoniou .\" End of generated man page.