AllocateAndFormatStringByTagsA()

char* Chusov::String::AllocateAndFormatStringByTagsA	(	const char *restrict	lpszTagFormatString,
		unsigned int	cNumberOfTagsPresent,
			...
	)

Allocates and initializes a multibyte string defined by format specified using PrintfA_s control sequences and user-defined tags.

Parameters

[in]	lpszTagFormatString	is a zero-terminated multibyte string specifying format using PrintfA_s control sequences and tag words. The last ones are delimited by single left and right brackets, i.e. <tag>. The brackets themselves are encoded as "<<" for '<' and ">>" for '>'.
	cNumberOfTagsPresent	is a number of different tags specified in the format string and, therefore, a number of groups of entities of the variable parameters list. See remarks for further explanation.
	...	is a set of parameters for formatting the output. The first part of the set is a group of parameters defining tags. The second one is a subset of parameters for the sPrintfA_s format fields. The parameters for the tag formatting are defined by groups. Each one consists on a tag name string, a pointer to a callback procedure associating the tag with the user-defined description, a user defined parameter for the callback and the flag signaling if the description would be the same for the all instances of the tag in the format. See remarks for further explanation.

Returns

On success the function returns a pointer to the allocated memory holding the string constructed according to the specified format. The returned string buffer must be freed using one of the free functions defined in the chsvmem.h header. On failure the function returns NULL. Use GetLastChsvError function to get extended error information.

Each tag (a string between brackets) is specified by a series of variable parameters as follows.

const char* pszTagName, PFNGET_TAG_DESCRIPTION_PROCA pfnGetDescription, uintptr_t nUserParam, bool fDeterministicDescription

One such group must be specified for each type of tags. I.e. one tag name, found in the format string once or multiply times, must accord exactly to one group of name, callback procedure, callback parameter and one boolean flag. These parameters are given as follows.

Parameters for a tag

Name	Meaning
pszTagName	A C-string specifying the tag without delimiting brackets.
pfnGetDescription	A mandatory callback function of type PFNGET_TAG_DESCRIPTION_PROCA. It must allocate a description for the specified tag name using one of the allocating functions defined within the Chusov::Memory or Chusov::String namespaces. See PFNGET_TAG_DESCRIPTION_PROCA for more detailed definition of the function interface.
nUserParam	A user-defined parameter passed to the callback function "as-is".
fDeterministicDescription	A flag specifying if the description returned for one tag may or may not be changed from call to call to the pfnGetDescription. If the flag is set, the description of the specified tag is supposed constant (not changing from call to call). Therefore, the function optimizes execution so that the callback function is called only once for the tag. If the flag is reset the description is considered volatile. In this case the callback function is called each time the tag is met in the format string. The nCallCounter parameter of the callback function specifies a number of the call which is initially zero.

To produce left and right angles in the output string use "<<" and ">>" format sequences respectively.

If tags in the format string do not correspond to tags in the list of variable parameters (comparison is case sensitive), the function fails with the CHSVERROR_INVALID_PARAMETER code.

In the variable lists the parameters of tags must always precede sPrintfA_s variable parameters. Firstly, the function performs the PrintfA_s formatting and then the tag formatting.

The Chusov::String namespace provides functions for wide strings which are similar to every corresponding multibyte string counterpart. The analogues are declared with a 'W' (instead of 'A') suffix at the end of the name, e.g. AllocateStringW, FreeStringW, etc.

The function itself does not generate exceptions. Although exceptions generated by the callback functions are not handled and passed to the caller.

See also

AllocateAndFormatStringByTagsW;
AllocateAndFormatStringByTagsVA;
AllocateAndFormatStringByTagsIndirectA;
AllocateStringA;
AllocateAndFormatStringA;
FreeStringA;
SecureFreeStringA.

Examples

chsvmem\AllocateAndFormatStringByTagsA.c.