Synesis Software STLSoft - ... Robust, Lightweight, Cross-platform, Template Software ...

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]

ff_mismatched_handler_info_t fastformat::getProcessMismatchedHandler (  )  [inline]

ff_illformed_handler_info_t fastformat::getThreadIllformedHandler (  )  [inline]

ff_mismatched_handler_info_t fastformat::getThreadMismatchedHandler (  )  [inline]

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

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

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

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


FastFormat Library documentation © Matthew Wilson, 2006-2009 SourceForge.net Logo