fastformat Namespace Reference

---

Detailed Description

The FastFormat root namespace - fastformat.

This the the root namespace for FastFormat, and contains the C-API functions, along with appropriate type-defs

Classes
class	openrj_bundle
	A resource bundle that reads Open-RJ Jar files. More...
class	properties_bundle
	A resource bundle that reads properties files. More...
class	windows_resource_bundle
	A resource bundle that reads Windows INI files. More...
class	winini_bundle
	A resource bundle that reads Windows INI files. More...
class	fastformat_exception
	Root class for all FastFormat exception. More...
class	format_parsing_exception
	Root class for all format parsing exceptions. More...
class	illformed_format_exception
	Exception class that represents an illformed format string. More...
class	mismatched_replacements_exception
	Root class for all parameter replacement exceptions. More...
class	missing_argument_exception
	Exception class that represents the case where one or more replacement parameters are specified in the format string but no matching arguments are presented in the argument list. More...
class	unreferenced_argument_exception
	Exception class that represents the case where one or more arguments in the argument list are unreferenced in the format. More...
class	bundle_exception
	Root class for all bundle exceptions. More...
struct	ff_string_slice_t
	Read-only string slice. More...
struct	ff_illformed_handler_info_t
	Structure returned from fastformat_getProcessIllformedHandler(), fastformat_setProcessIllformedHandler(), fastformat_getThreadIllformedHandler(), and fastformat_setThreadIllformedHandler(). More...
struct	ff_mismatched_handler_info_t
	Structure returned from fastformat_getProcessMismatchedHandler(), fastformat_setProcessMismatchedHandler(), fastformat_getThreadMismatchedHandler(), and fastformat_setThreadMismatchedHandler(). More...
class	ignore_missing_arguments_scope
	Scoping class that suppresses the reporting of unreferenced arguments during its lifetime. More...
class	ignore_unreferenced_arguments_scope
	Scoping class that suppresses the reporting of unreferenced arguments during its lifetime. More...
class	mismatched_arguments_scope_base
	Base class for scoping classes that customise the behaviour in response to mismatched arguments. More...
struct	ff_format_element_t
	Format element. More...
Namespaces
namespace	filters
	Namespace within which FastFormat filtering conversion shim functions are defined.
namespace	internal
	Namespace within which internal FastFormat types and functions are defined.
namespace	iterators
	Namespace within which FastFormat iterators are defined.
namespace	sinks
	Namespace within which FastFormat sink functions are defined.
namespace	util
	FastFormat utility namespace.
Typedefs
typedef char	ff_char_t
	Character type used by the library.
typedef ff_string_slice_t	string_slice_t
	Equivalent to ff_string_slice_t.
typedef ff_format_element_t	format_element_t
	Equivalent to ff_format_element_t.
typedef ff_parse_code_t	parse_code_t
	Equivalent to ff_parse_code_t.
typedef ff_replacement_code_t	replacement_code_t
	Equivalent to ff_replacement_code_t.
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 fastformat_illformedHandler_t	illformedHandler_t
	Equivalent to fastformat_illformedHandler_t.
typedef ff_illformed_handler_info_t	illformed_handler_info_t
	Equivalent to ff_illformed_handler_info_t.
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.
typedef fastformat_mismatchedHandler_t	mismatchedHandler_t
	Equivalent to fastformat_mismatchedHandler_t.
typedef ff_mismatched_handler_info_t	mismatched_handler_info_t
	Equivalent to ff_mismatched_handler_info_t.
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
int	fastformat_init (void)
	Initialises the FastFormat library.
void	fastformat_uninit (void)
	Uninitialises the FastFormat library.
ff_char_t const *	fastformat_getInitCodeString (int code)
	Returns a constant pointer to a non-NULL non-modifiable nul-terminated string representing the initialisation code.
size_t	fastformat_getInitCodeStringLength (int code)
	Returns the length of the string returned by fastformat_getInitCodeString().
int	init ()
	Equivalent to fastformat_init().
void	uninit ()
	Equivalent to fastformat_uninit().
ff_char_t const *	getInitCodeString (int code)
	Equivalent to fastformat_getInitCodeString().
size_t	getInitCodeStringLength (int code)
	Equivalent to fastformat_getInitCodeStringLength().
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.
size_t	fastformat_calculateNumberOfRequiredReplacements (ff_char_t const *format, size_t cchFormat)
	Calculates the exact number of replacements required for the given format.
unsigned	fastformat_parseFormat (ff_char_t const *format, size_t cchFormat, ff_format_element_t *formatElements, size_t numFormatElements, fastformat_illformedHandler_t handler, void *param)
	Parses a format string into an array of replacement element descriptors.
size_t	fastformat_fillReplacements (ff_string_slice_t *resultElements, ff_format_element_t const *formatElements, size_t numElements, ff_string_slice_t const *arguments, size_t numArguments, fastformat_mismatchedHandler_t handler, void *param, size_t *pnumResultElements)
	Takes a number of pattern and replacement elements and populates an array of result elements.
size_t	fastformat_accumulateSliceLengths (size_t numSlices, ff_string_slice_t const *slices)
	Calculates the total length of an array of string slices.
unsigned	fastformat_lookupPattern (ff_char_t const *pattern, size_t cchPattern, ff_format_element_t const **elements)
	Looks up the array of replacement element descriptors, corresponding to the given pattern, from the pattern cache.
ff_string_slice_t	fastformat_getNewlineForPlatform (void)
	Returns a slice representing the CR/LF combination for the current platform.
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().
string_slice_t	getNewlineForPlatform ()
	Equivalent to fastformat_getNewlineForPlatform().
char const *	c_str_data_a (ff_string_slice_t const &slice)
	Returns a possibly non-nul-terminated non-NULL C-style string representing the slice.
ff_char_t const *	c_str_data (ff_string_slice_t const &slice)
	Returns a possibly non-nul-terminated non-NULL C-style string representing the slice.
size_t	c_str_len_a (ff_string_slice_t const &slice)
	Returns the number of characters in the length of the C-style string representing the slice.
size_t	c_str_len (ff_string_slice_t const &slice)
	Returns the number of characters in the length of the C-style string representing the slice.

---

Typedef Documentation

typedef char ff_char_t

Character type used by the library.

This will be wchar_t if FASTFORMAT_USE_WIDE_STRINGS is defined, otherwise char.

Examples:

examples/example.arguments.character/example.arguments.character.cpp.

typedef ff_format_element_t format_element_t

Equivalent to ff_format_element_t.

typedef ff_illformed_handler_info_t illformed_handler_info_t

Equivalent to ff_illformed_handler_info_t.

typedef fastformat_illformedHandler_t illformedHandler_t

Equivalent to fastformat_illformedHandler_t.

typedef ff_mismatched_handler_info_t mismatched_handler_info_t

Equivalent to ff_mismatched_handler_info_t.

typedef fastformat_mismatchedHandler_t mismatchedHandler_t

Equivalent to fastformat_mismatchedHandler_t.

typedef ff_parse_code_t parse_code_t

Equivalent to ff_parse_code_t.

typedef ff_replacement_code_t replacement_code_t

Equivalent to ff_replacement_code_t.

typedef ff_string_slice_t string_slice_t

Equivalent to ff_string_slice_t.

---

Function Documentation

ff_char_t const* fastformat::c_str_data

(

ff_string_slice_t const &

slice

)

[inline]

Returns a possibly non-nul-terminated non-NULL C-style string representing the slice.

References c_str_data_a().

char const* fastformat::c_str_data_a

(

ff_string_slice_t const &

slice

)

[inline]

Returns a possibly non-nul-terminated non-NULL C-style string representing the slice.

Referenced by c_str_data().

size_t fastformat::c_str_len

(

ff_string_slice_t const &

slice

)

[inline]

Returns the number of characters in the length of the C-style string representing the slice.

References c_str_len_a().

size_t fastformat::c_str_len_a

(

ff_string_slice_t const &

slice

)

[inline]

Returns the number of characters in the length of the C-style string representing the slice.

Referenced by c_str_len().

size_t fastformat::fastformat_accumulateSliceLengths	(	size_t	numSlices,
		ff_string_slice_t const *	slices
	)

Calculates the total length of an array of string slices.

size_t fastformat::fastformat_calculateNumberOfRequiredReplacements	(	ff_char_t const *	format,
		size_t	cchFormat
	)

Calculates the exact number of replacements required for the given format.

Parameters:

	format	Pointer to the format string. Does not have to be nul-terminated. May not be NULL, unless cchFormat is 0
	cchFormat	Number of characters in the string pointed to by format

Precondition:

(0 == cchFormat || NULL != format)

size_t fastformat::fastformat_fillReplacements	(	ff_string_slice_t *	resultElements,
		ff_format_element_t const *	formatElements,
		size_t	numElements,
		ff_string_slice_t const *	arguments,
		size_t	numArguments,
		fastformat_mismatchedHandler_t	handler,
		void *	param,
		size_t *	pnumResultElements
	)

Takes a number of pattern and replacement elements and populates an array of result elements.

Returns:

The total number of characters required in the resultant string

Parameters:

pnumResultElements

Pointer to variable to receive the number of result elements. This may be greater than the number of pattern elements in the case where formatting (width) is applied

ff_string_slice_t fastformat::fastformat_getNewlineForPlatform

(

void

)

Returns a slice representing the CR/LF combination for the current platform.

Referenced by fastformat::sinks::fmt_slices(), getNewlineForPlatform(), vectored_file_sink::write(), string_array_sink::write(), OutputDebugString_sink::write(), char_buffer_sink::write(), and c_string_sink::write().

unsigned fastformat::fastformat_lookupPattern	(	ff_char_t const *	pattern,
		size_t	cchPattern,
		ff_format_element_t const **	elements
	)

Looks up the array of replacement element descriptors, corresponding to the given pattern, from the pattern cache.

Parameters:

	pattern	Pointer to an array of characters representing the string
	cchPattern	The number of characters in the string parameter pattern
	elements	Pointer to a variable to receive the pointer to the array of replacement element descriptors.

Returns:

The number of replacement element descriptors.

unsigned fastformat::fastformat_parseFormat	(	ff_char_t const *	format,
		size_t	cchFormat,
		ff_format_element_t *	formatElements,
		size_t	numFormatElements,
		fastformat_illformedHandler_t	handler,
		void *	param
	)

Parses a format string into an array of replacement element descriptors.

Parameters:

	format	Pointer to the format string. Does not have to be nul-terminated. May not be NULL, unless cchFormat is 0
	cchFormat	Number of characters in the string pointed to by format
	formatElements	Pointer to an array of replacements into which the parsed replacement slices are written
	numFormatElements	Number of format elements
	handler	Handler for ill-formed format
	param	Parameter to be passed to handler

Precondition:

(0 == cchFormat || NULL != format)

The number of replacements provided must be of sufficient size for the given format. To obtain the exact number required guaranteed to be sufficient, call fastformat_calculateNumberOfRequiredReplacements(). To obtain a quick value guaranteed to be sufficient, use the format length divided by 2.

Returns:

Information describing the number of elements written/required