Formatting

Modules
	Formattable interface

Macros
#define	strFormat(out, fmt, ...)    _strFormat(out, fmt, count_macro_args(__VA_ARGS__), (stvar[]) { __VA_ARGS__ })

Detailed Description

Type-safe string formatter with variable substitution and rich formatting options.

Though the function prototype itself is extremely simple, the usage is not. On a basic level, the formatter works similarly to printf, but is type safe and has many convenience features.

Format syntax

The format string is copied as-is unless the character sequence ${ is encountered. This sequence triggers a variable replacement, and everything until the next } is considered to be part of the variable. If a literal ${ is needed, it can be escaped with a backtick – i.e. `${

Variable substitution follows the following format:

type#(width,fmtopts)extra;default

type is a type name (see below), and the number indicates the n-th instance of that particular type in the format arguments. The type is REQUIRED and the number is OPTIONAL. If the number is omitted, an internal count is maintained, and each time that type name is used, the count is increased.

For example, ${string} indicates the next string in the argument sequence, and ${int3} uses the third integer.

Optional prefixes

An optional prefix may precede the type name. Supported prefixes are:

• - For numeric types, leave an extra space for the sign if positive
• + For numeric types, always print the sign
• 0 For numeric types, add leading zeros to fill out the width

Format options

fmtopts is a comma-delimited list of formatting options, most of which are specific to particular types – see below for details. A formatting option that is just a number by itself is interpreted to be the field width.

Most types right-justify within the field width if it is present – this can be overridden with the formatting options of left, or center.

Supported types

• string - Supported fmtopts:
  • upper - Transforms string to all uppercase
  • lower - Transforms string to all lowercase
  • name - Transforms string to all lowercase, capitalizes first character (ASCII only)
  • empty - Replaces empty strings with the default if set
  • null - Replaces null strings with the default if set
• int - Supported fmtopts:
  • min:# - Minimum number of digits to output. Different from width in that this will not truncate, and always 0-pads
  • hex - Outputs a Base 16 number (can be modified by upper)
  • octal - Outputs a Base 8 number
  • binary - Outputs a Base 2 number
  • prefix - Adds an 0x prefix for hex, and a 0 prefix for octal
  • utfchar - Outputs a UTF-8 encoded Unicode character. Argument is treated as unsigned, and width is ignored.
• uint - Unsigned integers are considered a different type and do not support the +/- prefixes. They otherwise support all of the int fmtopts.
• float - Supported fmtopts:
  • sig:# - Maximum number of significant digits
  • fixed - Fixed mode. Will never use scientific notation, and may produce a very long string.
  • dec:# - Maximum number of digits following the decimal point. Defaults to 6 for fixed mode, 0 for auto.
  • zero - Zero-pads after the decimal point if used with dec:#
  • If fixed is not specified, automatic mode is the default. If used without sig, this will try to output the shortest possible string that can be converted back to the original floating point number. Not 100% guaranteed to be the shortest form, but is the shortest 99.6% of the time and is extremely fast. Adding sig or dec will round the number instead of being precise.
  • If a field width is specified, automatically sets sig in order to fit.
• ptr - By default, the pointer value is output in the form 1234abcd. A 0 prefix causes the pointer to be zero-padded up to the pointer size.
  • upper - Uses uppercase hex digits
  • prefix - Adds a 0x prefix (not affected by upper)
• suid - Supported fmtopts:
  • upper - Uses uppercase SUID (not recommended)
• object - Requires that the object in question implement the Formattable interface. fmtopts are passed to the object and may vary.

Extra field modifiers

The 'extra' field may follow one of two forms and acts as a modifier on the type:

• type[#] - Uses the first matching argument that is an sarray of type. The number specifies the 0-based array index. [] without an index may be used to increment an internal counter.
• type:key - Uses the first matching argument that is a hashtable with string keys and values of the specified type. The string 'key' is looked up in the hashtable in order to find the matching value.

Default values

If there is an error such as not being able to find an argument of the appropriate type, the normal behavior is for strFormat to return false and produce no output. However, if the variable contains a ;default section, instead of failing the entire format operation, the literal text of 'default' (anything after the semicolon) will be inserted in place of the variable instead. A } character may be escaped with `} in this section.

Macro Definition Documentation

strFormat

#define strFormat	(		out,
			fmt,
			...
	)		_strFormat(out, fmt, count_macro_args(__VA_ARGS__), (stvar[]) { __VA_ARGS__ })

bool strFormat(string *out, strref fmt, ...)

Type-safe string formatter with variable substitution and rich formatting options

Copies the format string as-is, replacing ${...} sequences with formatted variables. See detailed documentation sections above for complete syntax and formatting options.

Parameters

out	Pointer to string to receive the formatted result
fmt	Format string with ${type} variable sequences
...	Variable arguments, each wrapped with stvar(type, value)

Returns

true on success, false if a required variable is missing or type mismatch occurs

Example:

string s = 0;
strFormat(&s, _S"Hello ${string}, you have ${int} messages",
          stvar(string, name), stvar(int32, count));

Definition at line 130 of file format.h.