These functions use the printf idiom to make it convenient to create structured Fleece values in memory with one call. More...

Functions
NODISCARD FLEECE_PUBLIC FLValue	FLValue_NewWithFormat (const char *format,...) __printflike(1
	Translates the JSON-style format string into a tree of mutable Fleece objects, adding values from the following arguments wherever a printf-style `%` specifier appears.

NODISCARD FLEECE_PUBLIC FLValue NODISCARD FLEECE_PUBLIC FLValue	FLValue_NewWithFormatV (const char *format, va_list args)
	Variant of FLValue_NewWithFormat that takes a pre-existing `va_list`.

FLEECE_PUBLIC void	FLMutableArray_UpdateWithFormat (FLMutableArray, const char *format,...) __printflike(2
	Like FLValue_NewWithFormat, except it operates on an existing mutable array.

FLEECE_PUBLIC void FLEECE_PUBLIC void	FLMutableDict_UpdateWithFormat (FLMutableDict, const char *format,...) __printflike(2
	Like FLValue_NewWithFormat, except it operates on an existing mutable dict.

FLEECE_PUBLIC void FLEECE_PUBLIC void FLEECE_PUBLIC void	FLValue_UpdateWithFormatV (FLValue, const char *format, va_list args)
	Like FLMutableArray_UpdateWithFormat / FLMutableDict_UpdateWithFormat but takes a pre-existing `va_list`.

Detailed Description

These functions use the printf idiom to make it convenient to create structured Fleece values in memory with one call.

They create or modify a FLMutableArray or `FLMutableDict by reading the given format string and the following arguments.

The format string is basically JSON5, except that any value in it may be a printf-style '' specifier instead of a literal, in which case that value will be read from the next argument. The supported format specifiers are:

Boolean: c (cast the arg to char to avoid a compiler warning)
Integer: i or d (use size specifiers l, ll, or z)
Unsigned integer: u (use size specifiers l, ll, or z)
Floating point: f (arg can be float or double; no size spec needed)
C string: s
Ptr+length string: %.*s (takes two args, a const char* and an int. See FMTSLICE.)
Fleece value: p (arg must be a FLValue)
[Core]Foundation: %@ (Apple platforms only: arg must be a NSString, NSNumber, NSArray, NSDictionary, NSNull, or equivalent CFTypeRef)

A - can appear after the %, indicating that the argument should be ignored if it has a default value, namely false, 0, or an empty string. This means the corresponding item won't be written (a Dict item will be erased if it previously existed.)

If an argument is a NULL pointer nothing is written, and any pre-existing Dict item will be removed.

Note: It's legal for a dict key to be repeated; later occurrences take precedence, i.e. each one overwrites the last.

Function Documentation

◆ FLMutableArray_UpdateWithFormat()

FLEECE_PUBLIC void FLMutableArray_UpdateWithFormat	(	FLMutableArray	,
		const char *	format,
			... )

Like FLValue_NewWithFormat, except it operates on an existing mutable array.

The values parsed from the format string and arguments will be appended to it.

◆ FLMutableDict_UpdateWithFormat()

FLEECE_PUBLIC void FLEECE_PUBLIC void FLMutableDict_UpdateWithFormat	(	FLMutableDict	,
		const char *	format,
			... )

Like FLValue_NewWithFormat, except it operates on an existing mutable dict.

(Pre-existing properties not appearing in the format string are preserved.)

◆ FLValue_NewWithFormat()

NODISCARD FLEECE_PUBLIC FLValue FLValue_NewWithFormat	(	const char *	format,
			... )

Translates the JSON-style format string into a tree of mutable Fleece objects, adding values from the following arguments wherever a printf-style % specifier appears.

Note: The result will be either an FLMutableArray or FLMutableString depending on the syntax of the format string.

Warning: The returned value must be released when you're done with it.

◆ FLValue_NewWithFormatV()

NODISCARD FLEECE_PUBLIC FLValue NODISCARD FLEECE_PUBLIC FLValue FLValue_NewWithFormatV	(	const char *	format,
		va_list	args )

Variant of FLValue_NewWithFormat that takes a pre-existing va_list.

Warning: The returned value must be released when you're done with it.

◆ FLValue_UpdateWithFormatV()

FLEECE_PUBLIC void FLEECE_PUBLIC void FLEECE_PUBLIC void FLValue_UpdateWithFormatV	(	FLValue	,
		const char *	format,
		va_list	args )

Like FLMutableArray_UpdateWithFormat / FLMutableDict_UpdateWithFormat but takes a pre-existing va_list.