VARIANT

Description

A variant is a generic data type with automatic type conversion. It is first assigned a value from a supported type; then queried by requesting its value in the same or any other supported type. Type conversion, if needed, is handled automatically. A variant holds up to a 64-bit signed/unsigned integer or a double-precision floating-point number. See VARIANT_Type for supported types. The unsigned int type supports multiple string conversion styles by choosing from different VARIANT_Base representations.

Variants allow for arbitrary parameter count with automatic types on functions through the framework. For example, see VARIANT_ParseStringArgs() and VARIANT_ParseString.

API guide

Common use cases

Persistent data/named variables

A typical variable containing a value that is read or modified multiple times. A VARIANT must be instantiated. Then a value can be set by assignment:

struct VARIANT v = VARIANT_CreateUint (42);

or by taking the object instance address:

struct VARIANT v;
VARIANT_SetUint (&v, 42);

The following functions work on an existing VARIANT instance; VARIANT_Create* returns an object to set by assignment, while VARIANT_Set* updates the instance stored value. Both methods are equal in terms of the final result.

VARIANT_CreateUint()
VARIANT_CreateInt()
VARIANT_CreateFp()
VARIANT_CreatePointer()
VARIANT_CreateBaseString()
VARIANT_CreateString()
VARIANT_CreateCopy()
VARIANT_CreateBoolean()
VARIANT_CreateBaseUint()
VARIANT_SetUint()
VARIANT_SetInt()
VARIANT_SetFp()
VARIANT_SetPointer()
VARIANT_SetBaseString()
VARIANT_SetString()
VARIANT_SetCopy()
VARIANT_SetBoolean()

Inline/unnamed instances

These VARIANT unnamed allocations are immediately destroyed after use by going out-of-context. Used to convenientry pass parameters to functions that take them:

:c:macro:`LOG` (NOBJ, "Hello `0", VARIANT_SpawnString("World"));

or convert to and from supported types:

char *str = "1234";
uint32_t num = VARIANT_ToUint (&VARIANT_SpawnString(str));

The VARIANT_Spawn* macros perform inline/unnamed VARIANT instantiations with explicit data type:

VARIANT_SpawnBaseUint
VARIANT_SpawnUint
VARIANT_SpawnInt
VARIANT_SpawnFp
VARIANT_SpawnPointer
VARIANT_SpawnBaseString
VARIANT_SpawnString
VARIANT_SpawnCopy
VARIANT_SpawnBoolean

or by automatic parameter data type acquisition, statically detected at compile-time:

VARIANT_SpawnBaseAuto

VARIANT_SpawnAuto

for example:

char *str = "1234";
uint32_t num = VARIANT_ToUint (&VARIANT_SpawnAuto(str));

the aforementioned “Auto” macros allow automatic instantiation of multiple length, multiple type parameter lists:

VARIANT_SpawnAutoVector

VARIANT_AutoParams

Design and development status

Feature-complete.

Changelog

Version	Date*	Author	Comment
1.0.0	2022.9.7	sgermino	Initial release.

* Date format is Year.Month.Day.

API reference

type VARIANT_PSA_OutProc

Function pointer type used in VARIANT_ParseStringArgs(). This function pointer references a user-defined function. In each call, the function should append or transmit the octets provided to form a complete parsed string.

Parameters

Param – Parameter passed by the caller.
Data – Pointer to a const array of uint8_t elements containing available data to store.
Octets – Number of octets in the Data array.

VARIANT_CONV_SIZE_MAX_OCTETS: Maximum length of a string conversion associated to a VARIANT, in octets. This holds the worst case, lenghtiest conversions: an unsigned integer with base VARIANT_Base.VARIANT_Base_Oct converted to a string, or to a string formatted as an Octal number. The constant is calculated as follows: 2^64 for a 64-bit number gives 22 Octal digits, plus the “o” suffix and null-termination for a maximum of 24 octets.

enum VARIANT_Type

Initial value type assigned to a VARIANT instance by using VARIANT_Spawn* or VARIANT_Set* functions.

enumerator VARIANT_Type_Uint: uint64_t 64-bit unsigned integer.

enumerator VARIANT_Type_Int: int64_t 64-bit signed integer.

enumerator VARIANT_Type_Fp: double double precision floating point.

enumerator VARIANT_Type_Pointer: void memory pointer.

enumerator VARIANT_Type_String: char string pointer. Pointed data must be static.

enumerator VARIANT_Type_Boolean: _Bool boolean.

enum VARIANT_Base

Variant numeric bases. Used to convert an unsigned integer value to string or a string to an unsigned integer.

enumerator VARIANT_Base_Dec_NoSuffix: Default decimal style: no suffix.

enumerator VARIANT_Base_Oct_Suffix: Octal, “o” suffix.

enumerator VARIANT_Base_Oct_NoSuffix: Octal, no suffix.

enumerator VARIANT_Base_Hex_LowerSuffix: Hexadecimal. Lowercase digits, “h” suffix.

enumerator VARIANT_Base_Hex_LowerNoSuffix: Hexadecimal. Lowercase digits.

enumerator VARIANT_Base_Hex_UpperSuffix: Hexadecimal. Uppercase digits, “h” suffix.

enumerator VARIANT_Base_Hex_UpperNoSuffix: Hexadecimal. Uppercase digits.

enumerator VARIANT_Base_Oct: Default octal style: suffix.

enumerator VARIANT_Base_Dec: Default decimal style: no suffix.

enumerator VARIANT_Base_Hex: Default hexadecimal style: uppercase digits and suffix.

struct VARIANT: The user should treat this as an opaque structure. No member should be directly accessed or modified.

VARIANT_SpawnBaseUint(_b, _u)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_Uint.

Parameters

_b – VARIANT_Base to format the contained value when converted to string.
_u – Uint value.

VARIANT_SpawnUint(_u)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_Uint with a default base VARIANT_Base.VARIANT_Base_Dec.

Parameters

_u – Uint value.

VARIANT_SpawnInt(_i)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_Int

Parameters

_i – Int value.

VARIANT_SpawnFp(_d)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_Fp

Parameters

_d – Floating point value.

VARIANT_SpawnPointer(_p)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_Pointer

Parameters

_p – Pointer value.

VARIANT_SpawnBaseString(_b, _s)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_String.

Parameters

_b – VARIANT_Base to interpret the string when converted to a numeric type.
_s – String value.

VARIANT_SpawnString(_s)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_String. The string will be interpreted as of base VARIANT_Base.VARIANT_Base_Dec when converted to a numeric type.

Parameters

_s – String value.

VARIANT_SpawnBoolean(_b)

Creates an unnamed VARIANT of type VARIANT_Type.VARIANT_Type_Boolean.

Parameters

_b – Boolean value.

VARIANT_SpawnCopy(_v)

Creates an unnamed exact copy of a VARIANT.

Parameters

_v – a valid VARIANT instance.

VARIANT_SpawnBaseAuto(_b, _v)

Automatically creates an unnamed VARIANT of the specified type and base.

Parameters

_b – VARIANT_Base to interpret the string when converted to a numeric type, or to format the unsigned value when converted to a string.
_v – Generic unsigned or string types.

VARIANT_SpawnAuto(_v)

Automatically creates an unnamed VARIANT by using the specified type.

Parameters

_v – Any generic supported type.

VARIANT_SpawnAutoVector(...)

Automatically creates an unnamed VARIANT array consisting of automatically created unnamed VARIANTs from a list of variable-length macro parameters.

Parameters

... – Up to 16 parameters consisting of generic supported types.

VARIANT_AutoParams(...)

Takes a list of variable-length macro parameters and automatically creates the following two elements, separated by a single comma:

An unnamed VARIANT array consisting of automatically created unnamed VARIANTs from a list of variable-length macro parameters.
Array element count, as literal.

The resulting macro-expanded parameters are convenient to call functions (whose names usually end in “Args”) that take those as a mechanism of variable-length, typed parameters in “C”.

For example, VARIANT_ParseString properly calls VARIANT_ParseStringArgs() by constructing its required array and array length parameters from __VA_ARGS__.

Parameters

... – Up to 16 parameters consisting of generic supported types.

VARIANT_ParseString(_oc, _mx, _s, _op, _opp, ...)

Automatically instances the parameters list and parameter count required to call VARIANT_ParseStringArgs().

Parameters

_oc – OutColumn, see VARIANT_ParseStringArgs().
_mx – MaxOctets, see VARIANT_ParseStringArgs().
_s – Str, see VARIANT_ParseStringArgs().
_op – OutProc, see VARIANT_ParseStringArgs().
_opp – OutProcParam, see VARIANT_ParseStringArgs().
... – Up to 16 parameters consisting of generic supported types.

Returns

see VARIANT_ParseStringArgs().

struct VARIANT VARIANT_CreateBaseUint(const enum VARIANT_Base Base, const uint64_t Uint)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_Uint.

Parameters

Base – VARIANT_Base to format Uint when converted to a string.
Uint – Unsigned int value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateUint(const uint64_t Uint)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_Uint and VARIANT_Base.VARIANT_Base_Dec base.

Parameters

Uint – Unsigned int value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateInt(const int64_t Int)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_Int.

Parameters

Int – Signed int value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateFp(const double Fp)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_Fp.

Parameters

Fp – Floating point value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreatePointer(const void *const Pointer)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_Pointer.

Parameters

Pointer – Pointer value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateBaseString(const enum VARIANT_Base Base, const char *const String)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_String.

Warning

The object created will keep a pointer copy; it won’t duplicate the original string contents. to avoid a dangling pointer, care must be taken to guarantee that the string pointer passed will not change its memory allocation.

Parameters

Base – The format of String is VARIANT_Base. Used when converting to a numeric type.
String – String pointer.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateString(const char *const String)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_String.

Warning

The object created will keep a pointer copy; it won’t duplicate the original string contents. to avoid a dangling pointer, care must be taken to guarantee that the string pointer passed will not change its memory allocation.

Parameters

String – String value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateCopy(const struct VARIANT *const V)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_String.

Note

If the original instance is of type VARIANT_Type.VARIANT_Type_String then a dangling pointer warning also applies to the second instance, as discussed in VARIANT_SetString().

Parameters

String – String value.

Returns

A VARIANT.

struct VARIANT VARIANT_CreateBoolean(const _Bool Boolean)

Returns a VARIANT of type VARIANT_Type.VARIANT_Type_Boolean.

Parameters

Boolean – Boolean value.

Returns

A VARIANT.

void VARIANT_SetBaseUint(struct VARIANT *const V, const enum VARIANT_Base Base, const uint64_t Value)

Sets a VARIANT instance to hold an unsigned int value. VARIANT_ToString() will use the VARIANT_Base specified to print value as a string.

Parameters

Base – A base in the VARIANT_Base enum.
Value – Unsigned int value.

Usage example:

struct VARIANT v;

VARIANT_SetBaseUint (&v, VARIANT_Base_Dec, 2748);
const char * str = VARIANT_ToString (&v);
// 'str' points to the string "2748".

VARIANT_SetBaseUint (&v, VARIANT_Base_Hex, 2748);
const char * str = VARIANT_ToString (&v);
// 'str' points to the string "ABCh".

VARIANT_SetBaseUint (&v, VARIANT_Base_Oct, 2748);
const char * str = VARIANT_ToString (&v);
// 'str' points to the string "5274o".

void VARIANT_SetUint(struct VARIANT *const V, const uint64_t Value)

Sets a VARIANT instance to hold a signed integer value using a default base of VARIANT_Base.VARIANT_Base_Dec.

Parameters

Value – Unsigned integer value.

Usage example:

struct VARIANT v;

VARIANT_SetUint (&v, 2748);
const char * str = VARIANT_ToString (&v);
// 'str' points to the string "2748".

void VARIANT_SetInt(struct VARIANT *const V, const int64_t Value)

Sets a VARIANT instance to hold a signed integer value.

Parameters

Value – Signed integer value.

void VARIANT_SetFp(struct VARIANT *const V, const double Value)

Sets a VARIANT instance to hold a double-precision floating-point value.

Parameters

Value – Double-precision floating-point value.

void VARIANT_SetPointer(struct VARIANT *const V, const void *const Ptr)

Sets a VARIANT instance to hold a pointer value.

Parameters

Ptr – Pointer value.

void VARIANT_SetBaseString(struct VARIANT *const V, const enum VARIANT_Base Base, const char *const Str)

Sets a VARIANT instance to hold a pointer to a string.

Warning

This instance will keep a pointer copy; it won’t duplicate the original string contents. Care must be taken to avoid a dangling pointer by ensuring that the string pointer passed will not change its memory allocation in the lifetime of this VARIANT object.

Parameters

Base – The string has a number formatted according to the VARIANT_Base specified. It is used to convert from string to a numeric data type.
Str – String pointer.

Usage example:

struct VARIANT v;

VARIANT_SetBaseString (&v, VARIANT_Base_Hex, "ABC");
const VARIANT_Uint v = VARIANT_ToUint (&v);
// 'v' equals 2748.

VARIANT_SetBaseString (&v, VARIANT_Base_Oct, "777");
const VARIANT_Uint v = VARIANT_ToUint (&v);
// 'v' equals 511.

void VARIANT_SetString(struct VARIANT *const V, const char *const Str)

Sets a VARIANT instance to hold a pointer to a string. This string may or may not represent a number. Nevertheless, string to integer conversion defaults to VARIANT_Base.VARIANT_Base_Dec.

Warning

This instance will keep a pointer copy; it won’t duplicate the original string contents. Care must be taken to avoid a dangling pointer by ensuring that the string pointer passed will not change its memory allocation in the lifetime of this VARIANT object.

Parameters

Str – string pointer.

Usage example:

struct VARIANT v;

VARIANT_SetString (&v, "12345");
const VARIANT_Uint v = VARIANT_ToUint (&v);
// 'v' equals 12345.

void VARIANT_SetCopy(struct VARIANT *const V, struct VARIANT *const A)

Copies type and value of a VARIANT instance into a second existing instance object. The following example code performs the same operation:

struct VARIANT v;
struct VARIANT a;

v = a;

Note

If the original instance is of type VARIANT_Type.VARIANT_Type_String then a dangling pointer warning also applies to the second instance, as discussed in VARIANT_SetString().

void VARIANT_SetBoolean(struct VARIANT *const V, const _Bool Value)

Sets a VARIANT instance to hold a boolean value.

Parameters

Value – Boolean value.

uint64_t VARIANT_ToUint(struct VARIANT *const V)

Gets the original VARIANT instance hold value as an unsigned integer number.

Returns: Value as an unsigned integer.

int64_t VARIANT_ToInt(struct VARIANT *const V)

Gets the VARIANT instance hold value as a signed integer number.

Note

A value of type VARIANT_Type.VARIANT_Type_Pointer cannot be converted to a signed integer. Do not call this function on pointers; this condition is asserted.

Returns: Value as a signed integer.

double VARIANT_ToDouble(struct VARIANT *const V)

Gets the VARIANT instance hold value as a double-precision floating-point number.

Note

Conversion from VARIANT_Type.VARIANT_Type_Pointer or VARIANT_Type.VARIANT_Type_Boolean to floating-point is invalid; this condition is asserted. Do not call this function on a VARIANT holding those types.

Returns: Value as a double-precision floating-point.

const char *VARIANT_ToString(struct VARIANT *const V)

Gets the VARIANT instance hold value as a string.

Returns

Pointer to the VARIANT instance temporary buffer with its value converted to a string.

Warning

Except for a VARIANT of type VARIANT_Type.VARIANT_Type_Boolean where values are statically allocated, the returned string pointer contents are temporary and may change on subsequent calls. The caller must duplicate the contents immediately to preserve them.

void VARIANT_ToStringBuffer(struct VARIANT *const V, char *const Buffer, const uint32_t Size)

Gets the VARIANT instance hold value converted to a string and copy it to an already allocated char array buffer. Buffer must hold the entire string including its trailing NULL character. This condition is asserted.

Parameters

Buffer – An already allocated char array.
Size – Char array size, in octets.

_Bool VARIANT_ToBoolean(struct VARIANT *const V)

Gets the VARIANT instance hold value as a boolean; either one (True) or zero (False).

Returns: Value as a boolean.

enum VARIANT_Base VARIANT_ChangeBaseUint(struct VARIANT *const V, const enum VARIANT_Base Base)

Changes base conversion on a VARIANT instance of type VARIANT_Type.VARIANT_Type_Uint. It does nothing on other types.

Parameters

Base – New base. VARIANT_ToString() will format this unsigned value accordingly. If zero, nothing will be changed and the return value will be zero.

Returns

Last base. Zero if the VARIANT instance is not of type VARIANT_Type.VARIANT_Type_Uint or Base is zero.

uint32_t VARIANT_StringOctetCount(struct VARIANT *const V)

Gets the VARIANT instance hold value as a string and return the number of octets required to store the string, including its trailing NULL.

Returns: Octet count.

_Bool VARIANT_IsEqual(struct VARIANT *const V, struct VARIANT *const A)

Checks types and values of two VARIANT instances for equality.

Returns: true if both types and values are equal, false otherwise.

_Bool VARIANT_IsEqualAsUint(struct VARIANT *const V, struct VARIANT *const A)

Checks values of two VARIANT instances for equality by converting both values to unsigned int.

Returns: true if both unsigned int values are equal, false otherwise.

uint32_t VARIANT_ParseStringArgs(const uint32_t OutColumn, const size_t MaxOctets, const char *const Str, const VARIANT_PSA_OutProc OutProc, void *const OutProcParam, struct VARIANT *const ArgValues, const uint32_t ArgCount)

Parses a UTF-8 string to interpret and substitute special character sequences with corresponding arguments in a VARIANT array, insert characters to fill spaces, perform argument tabulation, or specify argument formatting. The character that initiates a interpreted character sequence is the grave accent (`).

There are four special interpreted character sequence categories, each one starts with the grave accent:

Markers: `0 to `99.
Marker style specifiers: `o, `O, `d, `x, `X, `h, `H, `U, `l, `c, and `w.
Commands: `R, `S, `P, `T, `M, `F, and `L.
Parser state options: `$, `#, `^, and `&.

Markers follows the format “`n”, where ‘n’ represents a decimal number from 0 to 99 inclusive, for example “`0”, “`7”, “`25”. A marker indexes a zero-based array of VARIANT arguments to output that indexed array value in place of the marker.

Markers have the following advantages over classic printf() format specifiers:

They represent indices to an array of VARIANT; there is no need to state argument types as any VARIANT knows the type it contains and can automatically convert it to a string.
They can be placed on the string in non-sequential order (”`6`0`3”) or be repeated (”`0`0”), helping string translation and internationalization.
The argument parameter list is automatically constructed from user supplied arguments. There is no risk of illegal memory accesses or memory corruption when referencing undefined arguments.

A marker will be replaced with a Unicode replacement character (�) if there is an error retrieving the VARIANT value. For example, when the marker index is higher or equal than array elements available.

Marker style specifiers modifies the marker argument (‘n’) output as follows:

`on: Octal (base 8).
`On: Octal (base 8) suffixed with an “o”.
`dn: Decimal (base 10).
`xn: Hexadecimal (base 16) with lowercase digits (a-f).
`Xn: Hexadecimal (base 16) with uppercase digits (A-F).
`hn: Hexadecimal (base 16) with lowercase digits (a-f), suffixed with an “h”.
`Hn: Hexadecimal (base 16) with uppercase digits (A-F), suffixed with an “h”.

As an example, “`o2” will format the output of ArgValues[2] to octal, while “`H1” will format ArgValues[1] as hexadecimal with uppercase digits and an appended “h” suffix.

Note

Base conversion will only work with a VARIANT whose original data type is an unsigned integer. it will do nothing on a signed integer, double, string or pointer values. While it is possible to represent signed integers with different bases, it is a limitation of snprintf; the standard function internally used by VARIANT to convert an integer to string.

The default representation for all numeric types is decimal.

The following marker style specifiers only affect 7-bit ASCII character strings, any other character or UTF-8 sequence will be ignored:

`Un: Uppercase.
`ln: Lowercase.
`cn: Lowercase with capitalisation.
`wn: Lowercase with capitalisation on each word.

Note

Marker style specifiers are mutually exclusive: only a single specifier modifies the foremost marker. Sequences like “`X`l1” are invalid.

The purpose of Commands is to generate spacing, tabulation and centering by inserting a number of characters from a character pattern. A command follows the format “`Xp”, where ‘X’ is a single letter that represents the command and ‘p’ is the command parameter: a decimal number from 0 to 99 inclusive.

The following commands are available:

`Rp - Reset pattern

Resets current character pattern by assigning a predefined pattern ‘p’ as shown in the following table:

Pattern ‘p’	Characters	Sample output
0	‘ ‘	” “
1	‘-’	“-----”
2	‘.’	“…..”
3	‘*’	“*****”
4	‘-’, ‘ ‘	“- - -”
5	‘.’, ‘ ‘	“. . .”
6	‘*’, ‘ ‘	“* * *”
7	‘0’	“00000”

`Sp - Set pattern

Stores the next ‘p’ UTF-8 characters as the current character pattern to use in spacing and tabulation commands. Up to four characters of three octets each can be stored. Stored characters are considered part of the command itself and won’t be printed.

Note

Reset pattern 0 is the default. A set pattern is persistent thorough the parsed string.

`Pp - Out pattern: Inserts ‘p’ pattern characters.
`Tp - Next marker argument tabulation: Tabulates the next marker argument to the left of line column ‘p’ by inserting sufficient pattern characters.
`Mp - Next marker argument centering: Centers the next marker argument around column ‘p’ by inserting sufficient pattern characters.
`Fp - Fill to column: Inserts sufficient pattern characters to reach column ‘p’.
`Lp - Newline: Inserts ‘p’ newline sequences (”\r\n”). An `L with no numeric parameter placed right before the string end (”`L\0”) will print a single newline.

For example, “`T30`0” places ArgValues[0] to the left of column 30, “`M15`1” centers ArgValues[1] around column 15, and “`R7`T8`X0” formats an eight-digit hexadecimal number with leading zeros.

Note

Argument tabulation and centering commands insert no pattern characters when line column ‘p’ is lower than the argument character count.

Finally, Parser state options changes the parser behavior on command parameters and controls printing of hints on argument types.

`# - Command parameter behaviour: immediate mode.

Command parameter (‘p’) is passed as-is to the command. This is the default. For example, the command “`#`P5” will insert five pattern characters.

`$ - Command parameter behaviour: indirect mode.

Command parameter (‘p’) is interpreted as a marker (‘n’) to index ArgValues. Then, the command gets the VARIANT_ToUint() conversion of ArgValues[n] as its parameter. For example, the command “`$`P2” will insert VARIANT_ToUint(ArgValues[2]) pattern characters.

`^x - Argument type hint for strings.

Decorates arguments of type VARIANT_Type.VARIANT_Type_String as follows:

‘x’	Effect on strings	Sample output
0	Print verbatim	This is a “test”.
1	Double quotes	“This is a \”test\”.”
2	Single quotes	‘This is a “test”.’

`&x - Argument value hint for numbers.

Decorates arguments of types other than VARIANT_Type.VARIANT_Type_String as follows:

‘x’	Effect on numbers	Sample output = 255 (base hex, upper, no suffix)
0	Print verbatim	FF
1	Base as subscript	FF₁₆

For example, let ArgValues[0] == “String value”, ArgValues[1] == false, and parser string “Sample: `^21`0, `1”. The resulting message will be: “Sample: ‘String value’, false₂”.

To escape the grave accent character, use two grave acents “``”. Any other octet after the grave accent not discussed above is invalid, for example: “`!”, “`V”, or “`Z”. An interpreted character sequence or octet can immediately follow a previous valid sequence. These are valid examples: “`4`5”, “`h`0[`P3`1]`L2”, or “`0`0``”.

The resulting parsed string is sequentially stored in one or more calls using the user-supplied VARIANT_PSA_OutProc function.

Note

There is no way to know how many octets will require a parsed string without parsing it first. The application programmer can implement a VARIANT_PSA_OutProc function to store partial results to a fixed-sized buffer but should also handle out of memory situations whilst parsing. There are convenient alternatives already designed and thoroughly used across the framework:

Use the same fixed-sized buffer but managed through a CYCLIC data structure with no risk of memory overruns. See CYCLIC_IN_FromParsedStringArgs().
Use a STREAM to directly output to, for example, a hardware UART implementation. See STREAM_IN_FromParsedStringArgs().

Both implement their own VARIANT_PSA_OutProc internally.

Parameters

OutColumn – Initial output column in current line. Usually the last output column retured from a previous call.
MaxOctets – The null termination in Str must appear before reaching MaxOctets; this condition is asserted.
Str – Pointer to a string with VARIANT markers to substitute. It may be UTF-8 encoded.
OutProc – Function that stores resulting string octets as Str is parsed and substituted. See VARIANT_PSA_OutProc for details.
OutProcParam – Optional parameter passed by the caller to the OutProc function.
ArgValues – Array of VARIANT, or NULL if there are no arguments available.
ArgCount – Number of elements in the ArgValues array or zero if ArgValues is NULL.

Returns

Last output column in current line. Useful to keep track of last output column between parsing calls. Typically zero if Str ended with a newline character or newline command.