- Main Page
- Modules
- Namespaces
- Classes
- Files
- Related Pages
- Examples

# 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

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

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

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

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

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

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

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

ff_illformed_handler_info_t fastformat::getProcessIllformedHandler | ( |  | ) | `[inline]`

Equivalent to fastformat_getProcessIllformedHandler().

ff_mismatched_handler_info_t fastformat::getProcessMismatchedHandler | ( |  | ) | `[inline]`

Equivalent to fastformat_getProcessMismatchedHandler().

ff_illformed_handler_info_t fastformat::getThreadIllformedHandler | ( |  | ) | `[inline]`

Equivalent to fastformat_getThreadIllformedHandler().

ff_mismatched_handler_info_t fastformat::getThreadMismatchedHandler | ( |  | ) | `[inline]`

Equivalent to fastformat_getThreadMismatchedHandler().

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

Equivalent to fastformat_setProcessIllformedHandler().

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

Equivalent to fastformat_setProcessMismatchedHandler().

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

Equivalent to fastformat_setThreadIllformedHandler().

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

Equivalent to fastformat_setThreadMismatchedHandler().

FastFormat Library documentation © Matthew Wilson, 2006-2009 |