Format Specification Defect Handling

Typedefs
typedef int(*	fastformat_illformedHandler_t )(void *param, ff_parse_code_t code, ff_char_t const *format, size_t formatLen, size_t replacementIndex, ff_char_t const *defect, size_t defectLen, int parameterIndex, void *reserved0, size_t reserved1, void *reserved2)
	Ill-formed format handler callback function.
typedef int(*	fastformat_mismatchedHandler_t )(void *param, ff_replacement_code_t code, size_t numParameters, int parameterIndex, ff_string_slice_t *slice, void *reserved0, size_t reserved1, void *reserved2)
	Mismatched replacement index handler callback function.
Enumerations
enum	ff_parse_code_t {   FF_PARSECODE_SUCCESS = 0,   FF_PARSECODE_INCOMPLETEREPLACEMENT = 1,   FF_PARSECODE_INVALIDINDEX = 2 }
	Represents format parsing conditions. More...
enum	ff_replacement_code_t {   FF_REPLACEMENTCODE_SUCCESS = 0,   FF_REPLACEMENTCODE_MISSING_ARGUMENT = 1,   FF_REPLACEMENTCODE_UNREFERENCED_ARGUMENT = 2 }
	Represents parameter replacement conditions. More...
Functions
ff_illformed_handler_info_t	fastformat_getProcessIllformedHandler (void)
	Gets the ill-formed format handler for the calling process.
ff_illformed_handler_info_t	fastformat_setProcessIllformedHandler (fastformat_illformedHandler_t handler, void *param)
	Sets the ill-formed format handler for the calling process.
ff_illformed_handler_info_t	fastformat_getThreadIllformedHandler (void)
	Gets the ill-formed format handler for the calling thread.
ff_illformed_handler_info_t	fastformat_setThreadIllformedHandler (fastformat_illformedHandler_t handler, void *param)
	Sets the ill-formed format handler for the calling thread.
ff_mismatched_handler_info_t	fastformat_getProcessMismatchedHandler (void)
	Gets the mismatched parameter handler for the calling process.
ff_mismatched_handler_info_t	fastformat_setProcessMismatchedHandler (fastformat_mismatchedHandler_t handler, void *param)
	Sets the mismatched parameter handler for the calling process.
ff_mismatched_handler_info_t	fastformat_getThreadMismatchedHandler (void)
	Gets the mismatched parameter handler for the calling thread.
ff_mismatched_handler_info_t	fastformat_setThreadMismatchedHandler (fastformat_mismatchedHandler_t handler, void *param)
	Sets the mismatched parameter handler for the calling thread.
ff_illformed_handler_info_t	getProcessIllformedHandler ()
	Equivalent to fastformat_getProcessIllformedHandler().
ff_illformed_handler_info_t	setProcessIllformedHandler (illformedHandler_t handler, void *param)
	Equivalent to fastformat_setProcessIllformedHandler().
ff_illformed_handler_info_t	getThreadIllformedHandler ()
	Equivalent to fastformat_getThreadIllformedHandler().
ff_illformed_handler_info_t	setThreadIllformedHandler (illformedHandler_t handler, void *param)
	Equivalent to fastformat_setThreadIllformedHandler().
ff_mismatched_handler_info_t	getProcessMismatchedHandler ()
	Equivalent to fastformat_getProcessMismatchedHandler().
ff_mismatched_handler_info_t	setProcessMismatchedHandler (mismatchedHandler_t handler, void *param)
	Equivalent to fastformat_setProcessMismatchedHandler().
ff_mismatched_handler_info_t	getThreadMismatchedHandler ()
	Equivalent to fastformat_getThreadMismatchedHandler().
ff_mismatched_handler_info_t	setThreadMismatchedHandler (mismatchedHandler_t handler, void *param)
	Equivalent to fastformat_setThreadMismatchedHandler().

---

Typedef Documentation

typedef int( * fastformat_illformedHandler_t)(void *param, ff_parse_code_t code, ff_char_t const *format, size_t formatLen, size_t replacementIndex, ff_char_t const *defect, size_t defectLen, int parameterIndex, void *reserved0, size_t reserved1, void *reserved2)

Ill-formed format handler callback function.

This function is invoked when an ill-formed format string is encountered during parsing

Parameters:

	param	The parameter specified, along with the function pointer, to fastformat_parseFormat()
	format	Pointer to the format string being parsed. It may not be NULL, but the string it points to does not have to be nul-terminated.
	formatLen	The number of characters in the string pointed to by format
	replacementIndex	The 0-based index of the string fragment being parsed
	defect	Pointer in the string where the defect lies occurred
	defectLen	Length of the area of error
	parameterIndex	The replacement parameter number, or -1 for a literal fragment
	reserved0	Reserved for future use. Must be NULL
	reserved1	Reserved for future use. Must be zero
	reserved2	Reserved for future use. Must be NULL

Returns:

Cancels, or continues, processing in light of error.

Return values:

	0	Cancel processing.
	>0	Continue processing.
	<0	Continue processing, and don't invoke this function again.

Note:

The memory pointed to by format and defect is not valid outside the scope of the handler. Any implementing functions must copy these parameters if they wish to utilise the information outside this scope, e.g. within an exception.

typedef int( * fastformat_mismatchedHandler_t)(void *param, ff_replacement_code_t code, size_t numParameters, int parameterIndex, ff_string_slice_t *slice, void *reserved0, size_t reserved1, void *reserved2)

Mismatched replacement index handler callback function.

The function can do/request one of four things:

1. It can throw an exception. In this case, there is no return value 2. It can request that the invalid replacement parameter be left as is in the resultant string - the return value is 0 3. It can request that the invalid replacement parameter be replaced with the value contained in *slice, to which it will write the replacement form - the return value is >0 4. It can request that the current and all subsequent invalid replacement parameters be replaced with the value contained in *slice, to which it will write the replacement form - the return value is <0

In cases 3 and 4, the function implementation is responsible for ensuring that the contents of *slice remain valid until it is next called. To assist with this, when the mismatched handler is invoked and returns non-0 within a given replacements fill operation, a further call to the handler will be made in which slice is NULL, to indicate the end of the operation. This does not indicate that the contents of *slice may be invalidated, because the sink has not yet received the arguments, but it does provide an anchor to the invocation cycle. An implementation may note this sentinel value call, and know that the next time it is called a new cycle will be underway, and the previously allocated memory may be freed.

Parameters:

	param	The caller-supplied parameter passed to fastformat_fillReplacements()
	numParameters	The number of parameters
	parameterIndex	The mismatched parameter index
	slice	A pointer to a slice to receive any replacement string for the bad parameter
	reserved0	Reserved for future use. Must be NULL
	reserved1	Reserved for future use. Must be zero
	reserved2	Reserved for future use. Must be NULL

Returns:

A value that will control the behaviour of fastformat_fillReplacements()

Note:

The memory pointed to by format and defect is not valid outside the scope of the handler. Any implementing functions must copy these parameters if they wish to utilise the information outside this scope, e.g. within an exception.

---

Enumeration Type Documentation

enum ff_parse_code_t

Represents format parsing conditions.

Enumerator:

FF_PARSECODE_SUCCESS	The parsing is .
FF_PARSECODE_INCOMPLETEREPLACEMENT	The replacement is not complete; the terminating '}' is missing.
FF_PARSECODE_INVALIDINDEX	The replacement is empty, or contains invalid symbols.

enum ff_replacement_code_t

Represents parameter replacement conditions.

Enumerator:

FF_REPLACEMENTCODE_SUCCESS	The replacement is successful.
FF_REPLACEMENTCODE_MISSING_ARGUMENT	One or more required arguments are missing from the argument list.
FF_REPLACEMENTCODE_UNREFERENCED_ARGUMENT	One or more arguments are unreferenced in the format.

---

Function Documentation

ff_illformed_handler_info_t fastformat::fastformat_getProcessIllformedHandler

(

void

)

Gets the ill-formed format handler for the calling process.

Returns:

The previous handler for the process

Referenced by fastformat::getProcessIllformedHandler().

ff_mismatched_handler_info_t fastformat::fastformat_getProcessMismatchedHandler

(

void

)

Gets the mismatched parameter handler for the calling process.

Returns:

The previous handler for the process

Referenced by fastformat::getProcessMismatchedHandler().

ff_illformed_handler_info_t fastformat::fastformat_getThreadIllformedHandler

(

void

)

Gets the ill-formed format handler for the calling thread.

Returns:

The previous handler for the thread

Referenced by fastformat::getThreadIllformedHandler().

ff_mismatched_handler_info_t fastformat::fastformat_getThreadMismatchedHandler

(

void

)

Gets the mismatched parameter handler for the calling thread.

Returns:

The previous handler for the thread

Referenced by fastformat::getThreadMismatchedHandler().

ff_illformed_handler_info_t fastformat::fastformat_setProcessIllformedHandler	(	fastformat_illformedHandler_t	handler,
		void *	param
	)

Sets the ill-formed format handler for the calling process.

Parameters:

	handler	The new handler for the process
	param	The parameter associated with the handler

Returns:

The previous handler for the process

Referenced by fastformat::setProcessIllformedHandler().

ff_mismatched_handler_info_t fastformat::fastformat_setProcessMismatchedHandler	(	fastformat_mismatchedHandler_t	handler,
		void *	param
	)

Sets the mismatched parameter handler for the calling process.

Parameters:

	handler	The new handler for the process
	param	The parameter associated with the handler

Returns:

The previous handler for the process

Referenced by fastformat::setProcessMismatchedHandler().

ff_illformed_handler_info_t fastformat::fastformat_setThreadIllformedHandler	(	fastformat_illformedHandler_t	handler,
		void *	param
	)

Sets the ill-formed format handler for the calling thread.

Parameters:

	handler	The new handler for the thread
	param	The parameter associated with the handler

Returns:

The previous handler for the thread

Referenced by fastformat::setThreadIllformedHandler().

ff_mismatched_handler_info_t fastformat::fastformat_setThreadMismatchedHandler	(	fastformat_mismatchedHandler_t	handler,
		void *	param
	)

Sets the mismatched parameter handler for the calling thread.

Parameters:

	handler	The new handler for the thread
	param	The parameter associated with the handler

Returns:

The previous handler for the thread

Referenced by fastformat::setThreadMismatchedHandler(), and mismatched_arguments_scope_base::~mismatched_arguments_scope_base().

ff_illformed_handler_info_t fastformat::getProcessIllformedHandler

(

)

[inline]

Equivalent to fastformat_getProcessIllformedHandler().

References fastformat::fastformat_getProcessIllformedHandler().

ff_mismatched_handler_info_t fastformat::getProcessMismatchedHandler

(

)

[inline]

Equivalent to fastformat_getProcessMismatchedHandler().

References fastformat::fastformat_getProcessMismatchedHandler().

ff_illformed_handler_info_t fastformat::getThreadIllformedHandler

(

)

[inline]

Equivalent to fastformat_getThreadIllformedHandler().

References fastformat::fastformat_getThreadIllformedHandler().

ff_mismatched_handler_info_t fastformat::getThreadMismatchedHandler

(

)

[inline]

Equivalent to fastformat_getThreadMismatchedHandler().

References fastformat::fastformat_getThreadMismatchedHandler().

ff_illformed_handler_info_t fastformat::setProcessIllformedHandler	(	illformedHandler_t	handler,
		void *	param
	)			[inline]

Equivalent to fastformat_setProcessIllformedHandler().

References fastformat::fastformat_setProcessIllformedHandler().

ff_mismatched_handler_info_t fastformat::setProcessMismatchedHandler	(	mismatchedHandler_t	handler,
		void *	param
	)			[inline]

Equivalent to fastformat_setProcessMismatchedHandler().

References fastformat::fastformat_setProcessMismatchedHandler().

ff_illformed_handler_info_t fastformat::setThreadIllformedHandler	(	illformedHandler_t	handler,
		void *	param
	)			[inline]

Equivalent to fastformat_setThreadIllformedHandler().

References fastformat::fastformat_setThreadIllformedHandler().

ff_mismatched_handler_info_t fastformat::setThreadMismatchedHandler	(	mismatchedHandler_t	handler,
		void *	param
	)			[inline]

Equivalent to fastformat_setThreadMismatchedHandler().

References fastformat::fastformat_setThreadMismatchedHandler().