StringFormatter Class Reference
[Utils - String formatting]

Class for generating formatted strings in a similar way to the C standard library function sprintf. More...

#include <stringf.h>

Inheritance diagram for StringFormatter:

Classes
class	ConversionSpec
	Information about a single conversion specification. More...
Public Member Functions
size_t	VFormat (const char *formatString, va_list args)
size_t	Format (const char *formatString,...)
size_t	HexDumpLine (const void *data, size_t size, ptrdiff_t addressOffset=0)
Static Public Member Functions
static char *	PushHex (ulonglong val, char *dst, int precision=-1, int x='x', int prefix=false)
static char *	PushOctal (ulonglong val, char *dst, int precision=-1, int prefix=false)
static char *	PushDecimal (ulonglong val, char *dst, int precision=-1)
Static Public Attributes
static const size_t	FormatTextBufferSize = 130
static const size_t	HexDumpLineSize
Protected Types
enum	Flags { FlagMinus = 1<<0, FlagPlus = 1<<1, FlagSpace = 1<<2, FlagHash = 1<<3, FlagZero = 1<<4, LengthMod_hh = 1<<8, LengthMod_h = 1<<9, LengthMod_l = 1<<10, LengthMod_ll = 1<<11, LengthMod_L = 1<<12, LengthMod_unknown = 1<<13, SignedInt = 1<<15 }
Protected Member Functions
virtual void	Out (const char *text, size_t textSize)=0
virtual void	Out (char character, size_t repeatCount)=0
virtual char *	UnkownFormat (char *&dstEnd, ConversionSpec &spec)
char *	DefaultUnkownFormat (char *&dstEnd, ConversionSpec &spec)
Friends
class	StringFormatter::ConversionSpec

Detailed Description

Class for generating formatted strings in a similar way to the C standard library function sprintf.

The produced text is passed to the pure virtual Out(const char*,size_t) and Out(char,size_t) methods which are responsible for storing or outputing the string. For an example see StringBufferFormatter.

Supported conversion specifiers are:

diouxX - Integers. May have optional length modifier.
c - Character argument. Any length modifier is ignored.
s - String argument. Any length modifier is ignored.
p - Pointer argument.
n - Number of characters written so far. May have optional length modifier.

Valid length modifiers are:

hh - char
h - short
l - long
ll - long long
j - intmax_t
z - size_t
t - ptrdiff_t

The default implementation correctly parses the following conversion specifiers (but produces no output)

aAeEfgG - Floating point number with optional 'L' length modifier.

Definition at line 79 of file stringf.h.

Member Enumeration Documentation

enum StringFormatter::Flags [protected]

Flags indicating the format of a single conversion specification. See StringFormatter::ConversionSpec.

Enumerator:

FlagMinus	Format flag '-' is present.
FlagPlus	Format flag '+' is present.
FlagSpace	Format flag ' ' is present.
FlagHash	Format flag '#' is present.
FlagZero	Format flag '0' is present.
LengthMod_hh	Format length modifier 'hh' is present. I.e. argument is a char.
LengthMod_h	Format length modifier 'h' is present. I.e. argument is a short.
LengthMod_l	Format length modifier 'l' is present. I.e. argument is a long.
LengthMod_ll	Format length modifier 'll' is present. I.e. argument is a long long.
LengthMod_L	Format length modifier 'L' is present. I.e. argument is a double.
LengthMod_unknown	Used to indicate that the argument size is unkown.
SignedInt	Used to indicate that an integer argument is signed.

Definition at line 145 of file stringf.h.

Member Function Documentation

size_t StringFormatter::VFormat	(	const char *	formatString,
		va_list	args
	)

Produce a formatted string.

Parameters:

	formatString	A string specifying the format of the string. This is specified in the same way as the C standard library sprintf function.
	args	The arguments for the formatted string.

Returns:: The size of the resulting string.

Definition at line 405 of file stringf.cpp.

size_t StringFormatter::Format	(	const char *	formatString,
			...
	)

Produce a formatted string.

Parameters:

	formatString	A string specifying the format of the string. This is specified in the same way as the C standard library sprintf function.
	...	The arguments for the formatted string.

Returns:: The size of the resulting string.

Definition at line 580 of file stringf.cpp.

size_t StringFormatter::HexDumpLine	(	const void *	data,
		size_t	size,
		ptrdiff_t	addressOffset = `0`
	)

Produce a single line of a hex dump. Each line represents the contents of up to 16 bytes.

The format of the text is like:

	12345678  61 62 63 64  65 66 67 68  69 6a 6b 6c  6d 6e 6f 70  abcdefghijklmnop

Parameters:

	data	Address of data to be dumped.
	size	Size of data to be dumped. If >16 then only 16 bytes are dumped.
	addressOffset	Value to add to data for the address value to display in the dump.

Returns:: The number of bytes remaining to dump. I.e. size-16 if size was greater 16, else zero.

Definition at line 592 of file stringf.cpp.

virtual void StringFormatter::Out	(	const char *	text,
		size_t	textSize
	)			`[protected, pure virtual]`

Called to 'output' generated text.

Parameters:

	text	Pointer to text.
	textSize	Size of text.

Implemented in StringBufferFormatter.

virtual void StringFormatter::Out	(	char	character,
		size_t	repeatCount
	)			`[protected, pure virtual]`

Called to 'output' a repeated single character.

Parameters:

	character	The character to output.
	repeatCount	Number of times character should be output.

Implemented in StringBufferFormatter.

char * StringFormatter::UnkownFormat	(	char *&	dstEnd,
		ConversionSpec &	spec
	)			`[protected, virtual]`

Called when an conversion specification is found which is not recognised.

The implementation of this method should produce text corresponding to the specified format, or handle it as an error in an implementation specific manner.

The default implementation of this method just calls DefaultUnkownFormat. If you wish to provide your own implementation, define the macro STRINGFORMATTER_UNKOWNFORMAT_DEFINED when compiling stringf.cpp, this will omit the implementation defined in that file.

Parameters:

`[in,out]`	dstEnd	End of buffer where any generated text is stored. This is initialise to the end of a buffer of FormatTextBufferSize bytes which this function can optionally make use of.
	spec	The decoded conversion specification which is to be handed.

Returns:: The start of the generated text. (The address immediately after the text is returned in dstEnd.)

Definition at line 397 of file stringf.cpp.

char * StringFormatter::DefaultUnkownFormat	(	char *&	dstEnd,
		ConversionSpec &	spec
	)			`[protected]`

Default implemenation for UnkownFormat.

This returns an empty sting and also discards any float type argument from args if the conversion specifier is any of 'a', 'A', 'e', 'E', 'f', 'F', 'g' or 'G'.

Parameters:

`[in,out]`	dstEnd	End of buffer where any generated text is stored. This is left unchanged.
	spec	The decoded conversion specification which is to be handed.

Returns:: /a dstEnd.

Definition at line 372 of file stringf.cpp.

char * StringFormatter::PushHex	(	ulonglong	val,
		char *	dst,
		int	precision = `-1`,
		int	x = `'x'`,
		int	prefix = `false`
	)			`[static]`

Convert an unsigned integer into a hexadecimal numeric string.

The number is left padded with zeros if it contains less that precision digits, and is optionally prefixed by "0x".

Parameters:

	val	The value to convert.
	dst	The address of the character immediately after where the string is to be stored. I.e. this specifies where the string will end, not where it starts.
	precision	Minimum number of digits to store. A -ve value signifies 'use as many as required'.
	x	This must be either 'x' or 'X'. If 'x', all alphabetic characters are coverted in lower case, if 'X', they are coverted in upper case,
	prefix	If true, the converted value is prefixed with "0x".

Returns:: Pointer to the first character in the produced string.

Definition at line 222 of file stringf.cpp.

char * StringFormatter::PushOctal	(	ulonglong	val,
		char *	dst,
		int	precision = `-1`,
		int	prefix = `false`
	)			`[static]`

Convert an unsigned integer into a octal numeric string.

The number is left padded with zeros if it contains less that precision digits.

Parameters:

	val	The value to convert.
	dst	The address of the character immediately after where the string is to be stored. I.e. this specifies where the string will end, not where it starts.
	precision	Minimum number of digits to store. A -ve value signifies 'use as many as required'.
	prefix	If true, the converted value is prefixed "0" if it doesn't already start with one.

Returns:: Pointer to the first character in the produced string.

Definition at line 261 of file stringf.cpp.

char * StringFormatter::PushDecimal	(	ulonglong	val,
		char *	dst,
		int	precision = `-1`
	)			`[static]`

Convert an unsigned integer into a decimal numeric string.

The number is left padded with zeros if it contains less that precision digits.

Parameters:

	val	The value to convert.
	dst	The address of the character immediately after where the string is to be stored. I.e. this specifies where the string will end, not where it starts.
	precision	Minimum number of digits to store. A -ve value signifies 'use as many as required'.

Returns:: Pointer to the first character in the produced string.

Definition at line 289 of file stringf.cpp.

Member Data Documentation

const size_t StringFormatter::FormatTextBufferSize = 130 [static]

Size of internal buffer used for the storing the generated text for a single conversion specification. This sets a limit on the precision value for integers.

Definition at line 325 of file stringf.h.

const size_t StringFormatter::HexDumpLineSize [static]

Size of buffer required for HexDumpLine.

Definition at line 330 of file stringf.h.

The documentation for this class was generated from the following files: