NAME

libfyaml-misc - libfyaml miscellaneous API

UTILITIES

This header provides the low-level building blocks shared by all other libfyaml public headers. It has no libfyaml dependencies of its own and is safe to include in isolation.

Platform portability

ssize_t shim for MSVC / Windows toolchains
struct iovec shim for Windows (sys/uio.h substitute)
FY_EXPORT / FY_DEPRECATED / FY_FORMAT — symbol visibility and compiler-attribute portability macros
FY_UNUSED, FY_ALWAYS_INLINE, FY_DEBUG_UNUSED — compiler hint wrappers with safe fallbacks on non-GCC/Clang toolchains
FY_CONSTRUCTOR / FY_DESTRUCTOR — GCC-style constructor/destructor attributes with availability guards (FY_HAS_CONSTRUCTOR, FY_HAS_DESTRUCTOR)

Core constants and sentinel values

FY_BIT(x) — single-bit mask (1U << x)
FY_NT — sentinel meaning “null-terminated”; pass as a length argument to indicate that the string length should be inferred via strlen

Memory helpers

FY_ALLOCA_COPY_FREE / FY_ALLOCA_COPY_FREE_NO_NULL — copy a malloc-returned string onto the stack and immediately free the heap allocation; produces an alloca-lifetime copy in a single expression
fy_vsprintfa / fy_sprintfa — printf-style formatting into a stack-allocated (alloca) buffer; the result is valid for the lifetime of the enclosing function

Container and array helpers

container_of — recover a pointer to an enclosing struct from a pointer to one of its members
ARRAY_SIZE — number of elements in a stack-allocated array

Type safety and compile-time checks

FY_SAME_TYPE / FY_CHECK_SAME_TYPE — assert two expressions share the same C type (wraps __builtin_types_compatible_p with a fallback)
FY_COMPILE_ERROR_ON_ZERO — produce a compile-time error when the argument evaluates to zero; used for macro-level static assertions

Overflow-safe arithmetic

•: FY_ADD_OVERFLOW, FY_SUB_OVERFLOW, FY_MUL_OVERFLOW — wrappers around __builtin_*_overflow with portable fallback implementations

Miscellaneous

FY_IMPOSSIBLE_ABORT — mark unreachable code paths; aborts at runtime
FY_STACK_SAVE / FY_STACK_RESTORE — save and restore the stack pointer for alloca-based temporary arenas
Lambda / closure macros and a CPP metaprogramming framework for building variadic generic APIs
Diagnostic helpers and floating-point precision constants

This section implements a portable FY_CPP_* macro toolkit that enables applying an operation to every argument in a __VA_ARGS__ list — the equivalent of a compile-time map() function.

The core challenge: The C preprocessor does not support recursion. A macro cannot call itself. The standard workaround is deferred evaluation: a macro is “postponed” so that it is not expanded in the current scan pass, only in a future one. Multiple passes are forced by the FY_CPP_EVALn ladder which re-expands the token stream a power-of-two number of times.

Evaluation levels (FY_CPP_EVAL1 .. FY_CPP_EVAL):

FY_CPP_EVAL1 — one pass (no re-expansion)
FY_CPP_EVAL2 — 2 passes
FY_CPP_EVAL4 — 4 passes
FY_CPP_EVAL8 — 8 passes
FY_CPP_EVAL16 — 16 passes (GCC only; Clang craps out at 8)
FY_CPP_EVAL — full depth (32 passes on GCC, 16 on Clang)

Each doubling allows mapping over twice as many arguments. FY_CPP_EVAL supports lists of up to ~32 elements (GCC) or ~16 elements (Clang) in practice.

Argument accessors — extract positional arguments from __VA_ARGS__:

FY_CPP_FIRST(...) — first argument (0 if list is empty)
FY_CPP_SECOND(...) — second argument
FY_CPP_THIRD(...) — third argument
FY_CPP_FOURTH(...) — fourth argument
FY_CPP_FIFTH(...) — fifth argument
FY_CPP_SIXTH(...) — sixth argument
FY_CPP_REST(...) — all arguments after the first (empty if < 2)

Map operations:

FY_CPP_MAP(macro, ...) — expand macro(x) for each argument x.
FY_CPP_MAP2(a, macro, ...) — expand macro(a, x) for each x, threading a fixed first argument a through every call.

Utility:

FY_CPP_VA_COUNT(...) — number of arguments (integer expression).
FY_CPP_VA_ITEMS(_type, ...) — compound-literal array of _type from varargs.
FY_CPP_EMPTY() — deferred empty token (used to postpone macros).
FY_CPP_POSTPONE1(macro) — postpone a one-argument macro one pass.
FY_CPP_POSTPONE2(a, macro) — postpone a two-argument macro one pass.

Short-name mode (FY_CPP_SHORT_NAMES):

By default the implementation uses abbreviated internal names (_E1, _FM, etc.) to reduce token-expansion buffer pressure. Define FY_CPP_SHORT_NAMES_DEBUG before including this header to force the original long-name implementation (FY_CPP_EVAL1, _FY_CPP_MAP_ONE, etc.) which is easier to read in expansion traces.

Example:

// Count and collect variadic integer arguments into a C array:
int do_sum(int count, int *items) { ... }
#define do_sum_macro(...) \
    do_sum(FY_CPP_VA_COUNT(__VA_ARGS__), \
           FY_CPP_VA_ITEMS(int, __VA_ARGS__))
// do_sum_macro(1, 2, 5, 100) expands to:
// do_sum(4, ((int [4]){ 1, 2, 5, 100 }))

Portable wrappers around GCC/Clang #pragma GCC diagnostic directives. Use FY_DIAG_PUSH() and FY_DIAG_POP() to bracket a region where a specific warning is suppressed:

FY_DIAG_PUSH
FY_DIAG_IGNORE_ARRAY_BOUNDS
... code that triggers -Warray-bounds ...
FY_DIAG_POP

On compilers other than GCC/Clang all macros in this group expand to nothing.

Portable wrappers for the mantissa-digit and decimal-digit counts of float, double, and long double. Each macro tries three sources in order:

1.: The standard <float.h> macro (e.g. FLT_MANT_DIG).
2.: The GCC/Clang predefined macro (e.g. __FLT_MANT_DIG__).
3.: A conservative hard-coded fallback.

These constants are used when formatting floating-point values as YAML scalars to ensure round-trip fidelity.

macro __has_builtin

__has_builtin(x): Fallback for compilers that do not provide __has_builtin.

Parameters

•: x – The builtin name to query.