AllocateAndFormatStringByTagsIndirectA()

char* Chusov::String::AllocateAndFormatStringByTagsIndirectA	(	const char *restrict	lpszTagFormat,
		unsigned int	cNumberOfTagsPresent,
		const TAG_DESCRIPTION_PARAM_A *restrict	pTagsParams
	)

Allocates and initializes a string formatted by user-defined tags.

Parameters

[in]	lpszTagFormat	is a zero-terminated multibyte string specifying format using tag words placed within brackets, e.g. <tag>. The text outside of tags is copied to the formatted output. To specify brackets for the output use "<<" for '<' and ">>" for '>'.
	cNumberOfTagsPresent	is a number of different tags specified in the format string which is equal to a number of elements in the pTagsParams array of TAG_DESCRIPTION_PARAM_A structures.
[in]	pTagsParams	is an array of TAG_DESCRIPTION_PARAM_A structures containing information for the parser to retrieve strings associated with each tag and to replace the tag in the input by it.

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 Chusov::Memory or Chusov::String namespaces. On failure the function returns NULL. Use GetLastChsvError function to get extended error information.

Remarks

The format sequences "<<" and ">>" produce left and right brackets in the output respectively.

If tags in the format string do not correspond to tags in the pTagsParams vector (comparison is case sensitive), the function fails with the CHSVERROR_INVALID_PARAMETER code.

The Chusov::String namespace provides analogous functions for wide strings for every counterpart working with single-byte strings. The analogues are declared without an 'A' suffix at the end of the name, e.g. AllocateStringW, FreeStringW, AllocateAndFormatStringByTagsW, AllocateAndFormatStringVW, AllocateAndFormatStringByTagsVW, etc.

The function itself does not generate exceptions. However, exceptions generated by the callback functions, specified by the pTagsParams, are not handled and passed to the caller.

Warning

User-defined callback functions specified in the pTagsParams elements must return a pointer to memory allocated using functions of this namespace and file, such as AllocateStringA.

See also

AllocateAndFormatStringByTagsVA;
AllocateAndFormatStringByTagsA;
PFNGET_TAG_DESCRIPTION_PROCA;
AllocateStringA;
AllocateAndFormatStringA;
FreeStringA;
SecureFreeStringA.