Format strings: libnkutils Reference Manual

Format strings

Format strings — powerful format strings engine

Functions

GQuark	nk_format_string_error_quark ()
NkFormatString *	nk_format_string_parse ()
NkFormatString *	nk_format_string_parse_enum ()
NkFormatString *	nk_format_string_ref ()
void	nk_format_string_unref ()
GVariant *	(*NkFormatStringReplaceReferenceCallback) ()
gchar *	nk_format_string_replace ()

Types and Values

	NkFormatString
enum	NkFormatStringError
#define	NK_FORMAT_STRING_ERROR

Description

Functions

nk_format_string_error_quark ()

GQuark
nk_format_string_error_quark (void);

nk_format_string_parse ()

NkFormatString *
nk_format_string_parse (gchar *string,
                        gunichar identifier,
                        GError **error);

Parses string

Parameters

string	a format string.	[transfer full]
identifier	the reference identifier character (e.g. '$')
error	return location for a GError, or `NULL`

Returns

an NkFormatString, NULL on error.

[transfer full]

nk_format_string_parse_enum ()

NkFormatString *
nk_format_string_parse_enum (gchar *string,
                             gunichar identifier,
                             const gchar * const *tokens,
                             guint64 size,
                             guint64 *used_tokens,
                             GError **error);

Parses string as nk_format_string_parse().

Once parsed, each reference is checked against tokens

If used_tokens is non-NULL, size must be inferior or equal to 64.

If the function returns an NkFormatString, used_tokens is filled with a bitfield corresponding to all used tokens. Each bit set to 1 at position x (1 << x) means the token x was used.

If the function returns NULL, used_tokens is left untouched.

Parameters

string	a format string.	[transfer full]
identifier	the reference identifier character (e.g. '$')
tokens	a list of tokens.	[array length=size]
size	the size of `tokens`
used_tokens	return location for the used tokens mask.	[out][nullable]
error	return location for a GError, or `NULL`

Returns

an NkFormatString, NULL on error.

[transfer full]

nk_format_string_ref ()

NkFormatString *
nk_format_string_ref (NkFormatString *format_string);

Increments the reference counter of format_string .

Parameters

format_string

an NkFormatString

Returns

the NkFormatString.

[transfer full]

nk_format_string_unref ()

void
nk_format_string_unref (NkFormatString *format_string);

Decrements the reference counter of format_string . If it reaches 0, free format_string .

Parameters

format_string

an NkFormatString

NkFormatStringReplaceReferenceCallback ()

GVariant *
(*NkFormatStringReplaceReferenceCallback)
                               (const gchar *name,
                                guint64 value,
                                gpointer user_data);

Retrieve the data referenced in the format string.

The function should return a GVariant containing the data referenced by name or value.

If the return value is a floating reference (see g_variant_ref_sink()), the NkFormatString takes ownership of it.

Parameters

name	the reference name
value	the reference value (for enum-based NkFormatString only)
user_data	user_data passed to `nk_format_string_replace()`

Returns

a GVariant containing the referenced data, may be NULL if no data.

[nullable]

nk_format_string_replace ()

gchar *
nk_format_string_replace (const NkFormatString *format_string,
                          NkFormatStringReplaceReferenceCallback callback,
                          gpointer user_data);

Replaces all references in format_string by data retrieved by callback .

See NkFormatStringReplaceReferenceCallback.

Parameters

format_string	an NkFormatString
callback	an NkFormatStringReplaceReferenceCallback used to retrieve replacement data
user_data	user_data for `callback`

Returns

the result string

Types and Values

NkFormatString

typedef struct _NkFormatString NkFormatString;

An opaque structure holding the format string.

enum NkFormatStringError

Members

NK_FORMAT_STRING_ERROR_WRONG_KEY	Wrong index value in `${reference[index]}` notation
NK_FORMAT_STRING_ERROR_UNKNOWN_MODIFIER	Unknown modifier in `${reference:modifier}` notation
NK_FORMAT_STRING_ERROR_WRONG_RANGE	Error in `${reference:[;range]}` notation
NK_FORMAT_STRING_ERROR_WRONG_SWITCH	Error in `${reference:{;true;false}}` notation
NK_FORMAT_STRING_ERROR_WRONG_PRETIFFY	Error in `${reference(prettify)}` notation
NK_FORMAT_STRING_ERROR_REGEX	Wrong regex in `${reference/regex/replacement}` notation
NK_FORMAT_STRING_ERROR_UNKNOWN_TOKEN	Unknown token in enum-based format list

NK_FORMAT_STRING_ERROR

#define NK_FORMAT_STRING_ERROR (nk_format_string_error_quark())