virtual P6R::P6ERR P6R::p6ISafeString::formatString ( P6CHAR *  pBuffer, P6SIZE  cBuffer, P6SIZE *  pcWritten, const P6CHAR *  pszFormat, const P6ARG *  pArgs, P6SIZE  cArgs  )

pure virtual

Provides a safer, enhanced snprintf replacement.

It does not use use varargs and instead takes an array of P6ARG structs. There are helper macros available to help intitialize the P6ARG's (see P6ARGINITBOOL(), P6ARGINITCHAR(), P6ARGINITINT32() etc.).

The format string uses positional notation to allow I18N issues to be easily handled.

position$

Position indicates the argument position in the pArgs argument array that should be rendered. This value begins at 1 (not zero).

Parameters

pBuffer	[ out ] The address of a P6CHAR buffed in which to place the output string.
cBuffer	[ in ] Specified the size in characters of the buffer pointer to by pBuffer
pcWritten	[out, optional] The address of a P6SIZE in which will be returned the number of characters written to pBuffer. NULL may also be passed here if this information is not needed.
pszFormat	[ in ] A NULL terminated P6CHAR string containing the format string to use.
pArgs	[ in ] The address of an array of P6R::P6ARG structures that define the aruments that are to be expanded.
cArgs	[ in ] The number of array elements in pArgs.

Returns

Success	P6R::eOk
Failure	P6R::eInvalidArg	pBuffer or pszFormat is NULL, or cBuffer is zero
	P6R::eEndOfRecord	A position was specified that is out range with regards to the number of arguments in the array. On exit the pBuffer will contain 1 to 5 plus signs '+' to indicate this error.
	P6R::eFormatError	The format string is invalid. Replacements must have the form, 'position$' OR and invalid format type (P6ARGFMT) was specified in the P6ARG array. If the terminating dollar sign is missing the output buffer will contain 1 to 5 '$' characters. If an argument index was not specified pBuffer will contain 1 to 5 'i' characters. If P6AT_XXXX tye was specified that is not currently handled by format string, then pBuffer will contain 1 to 5 '?' characters.
	P6R::eTooSmall	The expanded string would not fit in the specified buffer.