Falcon::Format Class Reference

Item to string format class. More...

#include <format.h>

Inheritance diagram for Falcon::Format:

[legend]

List of all members.

Public Types
Public Member Functions
virtual FalconData *	clone () const
t_convType	convType () const
void	decimals (uint8 d)
uint8	decimals () const
void	fieldSize (uint16 size)
uint16	fieldSize () const
void	fixedSize (bool f)
bool	fixedSize () const
bool	format (VMachine *vm, const Item &source, String &target)
	Formats given item into the target string.
bool	format (const Item &source, String &target)
	Formats given item into the target string.
	Format (const String &fmt)
	Format ()
virtual void	gcMark (uint32 mark)
void	grouping (uint8 g)
uint8	grouping () const
bool	isValid () const
	Checks if this format is valid.
void	mismatchAction (t_convMismatch t)
t_convMismatch	mismatchAction () const
void	negFormat (t_negFormat f)
t_negFormat	negFormat () const
void	nilFormat (t_nilFormat f)
t_nilFormat	nilFormat () const
void	numFormat (t_numFormat t)
t_numFormat	numFormat () const
const String &	originalFormat () const
void	paddingChr (uint32 chr)
uint32	paddingChr () const
bool	parse (const String &fmt)
	Parses a format string.
void	reset ()
	sets default values
void	rightAlign (bool b)
bool	rightAlign () const

---

Detailed Description

Item to string format class.

---

Member Enumeration Documentation

enum Falcon::Format::t_convMismatch

Action to perform on type mismatch / impossible conversion.

Enumerator:

e_actNoAction	Just return false. In the VM, this will cause the formatter to return nil, or to raise an error if embedded in strings.
e_actNil	Act as incompatible types were nil.
e_actZero	Act as incompatible types were zero or empty.
e_actRaise	Raise a type error.
e_actConvertNil	Try to convert, if conversion fails act as if nil.
e_actConvertZero	Try to convert, if conversion fails act as if zero of empty.
e_actConvertRaise	Try to convert, if conversion fails raise a type error.

enum Falcon::Format::t_convType

Conversion type.

Enumerator:

e_tNum	Basically a numeric conversion.
e_tStr	Basically a string conversion.
e_tError	Wrong format / parse error.

enum Falcon::Format::t_negFormat

negative representation style

Enumerator:

e_minusFront	Optional minus in front of the number if negative.
e_plusMinusFront	Plus and minus in front of the number.
e_minusBack	Minus after the number if negative.
e_plusMinusBack	Plus or minus after the number always.
e_minusEnd	Minus at field alignment end.
e_plusMinusEnd	Plus or minus at field alignment end.
e_parenthesis	In parenthesis if negative.
e_parpad	In parenthesis if negative, add padding space if positive.

enum Falcon::Format::t_nilFormat

How to represent a nil.

Enumerator:

e_nilEmpty	Nil is not represented.
e_nilNil	Nil is written as 'Nil'.
e_nilN	Nil is written as 'N'.
e_nilnil	Nil is written as 'nil'.
e_nilNA	Nil is written as N/A.
e_nilNone	Nil is written as None.
e_nilNULL	Nil is written as NULL.
e_nilNull	Nil is written as Null.
e_nilPad	Nil is written as padding.

enum Falcon::Format::t_numFormat

Integer representation style.

Enumerator:

e_decimal	No transformation.
e_binary	To binary.
e_binaryB	To binary, add b after the number.
e_octal	To octal.
e_octalZero	To octal, add 0 in front.
e_hexLower	To hex, lower case.
e_hexUpper	To hex, upper case.
e_cHexLower	To hex, lowercase, add 0x in front.
e_cHexUpper	To hex, uppercase, add 0x in front.
e_scientific	To scientific notation.

---

Constructor & Destructor Documentation

Falcon::Format::Format

(

)

[inline]

References reset().

Falcon::Format::Format

(

const String &

fmt

)

[inline]

References parse(), and reset().

---

Member Function Documentation

virtual FalconData* Falcon::Format::clone

(

)

const [virtual]

Implements Falcon::FalconData.

t_convType Falcon::Format::convType

(

)

const [inline]

void Falcon::Format::decimals

(

uint8

d

)

[inline]

uint8 Falcon::Format::decimals

(

)

const [inline]

void Falcon::Format::fieldSize

(

uint16

size

)

[inline]

uint16 Falcon::Format::fieldSize

(

)

const [inline]

void Falcon::Format::fixedSize

(

bool

f

)

[inline]

bool Falcon::Format::fixedSize

(

)

const [inline]

bool Falcon::Format::format	(	VMachine *	vm,
		const Item &	source,
		String &	target
	)

Formats given item into the target string.

The target string is not cleared before format occours; in other words, the format output is just appended to the end of the string. Use a pre-allocated string for better performance.

In case the source item is an object, its toString() method is called on the given VM. In case of raise from the routine, the method will return false; if raise on failure is set, then the exception is left untouched and it will be passed to the calling routine, else the exception will be reset and the format routine will simply fail.

See also:

parse for format details.

Returns:

true on success, false on error.

bool Falcon::Format::format	(	const Item &	source,
		String &	target
	)			[inline]

Formats given item into the target string.

This version doesn't require a VM, but will fail if source item is an object.

Also, in case of failure there will be no report about the error context, as that would be normally reported by raising an exception in the VM.

See also:

bool format( VMachine *vm, const Item &source, String &target )

Parameters:

	source	the item to be formatted
	target	the string where to output the format.

Returns:

true on success, false on error.

virtual void Falcon::Format::gcMark

(

uint32

mark

)

[inline, virtual]

Implements Falcon::FalconData.

void Falcon::Format::grouping

(

uint8

g

)

[inline]

uint8 Falcon::Format::grouping

(

)

const [inline]

bool Falcon::Format::isValid

(

)

const [inline]

Checks if this format is valid.

References e_tError.

void Falcon::Format::mismatchAction

(

t_convMismatch

t

)

[inline]

t_convMismatch Falcon::Format::mismatchAction

(

)

const [inline]

void Falcon::Format::negFormat

(

t_negFormat

f

)

[inline]

t_negFormat Falcon::Format::negFormat

(

)

const [inline]

void Falcon::Format::nilFormat

(

t_nilFormat

f

)

[inline]

t_nilFormat Falcon::Format::nilFormat

(

)

const [inline]

void Falcon::Format::numFormat

(

t_numFormat

t

)

[inline]

t_numFormat Falcon::Format::numFormat

(

)

const [inline]

const String& Falcon::Format::originalFormat

(

)

const [inline]

void Falcon::Format::paddingChr

(

uint32

chr

)

[inline]

uint32 Falcon::Format::paddingChr

(

)

const [inline]

bool Falcon::Format::parse

(

const String &

fmt

)

Parses a format string.

Transforms a format string into a setup for this format object.

The format is a sequence of commands that are parsed independently from their position. Commands are usually described by one, two or more character.

Formats are meant to deal with different item types. A format thought for a certain kind of object, for example, a number, may be applied to something different, for example, a string, or the other way around.

For this reason, Falcon formats include also what to do if the given item is not thought for the given format.

Format elements:

• Size: The minimum field lengt; it can be just expressed by a number. if the formatted output is wide as or wider than the allocated size, the output will NOT be truncated, and the resulting string may be just too wide to be displayed where it was intented to be. The size can be mandatory by adding '*' after it. In this case, the function will return false (and eventually raise an error) if the conversion caused the output to be wider than allowed.

• Padding: the padding character is appended after the formatted size, or it is prepended before it alignment is right. To define padding character, use 'p' followed by the character. For example, p0 to fill the field with zeroes. Of course, the character may be any Unicode character (the format string accepts standard falcon character escapes). In the special case of p0, front sign indicators are placed at the beginning of the field; for example "4p0+" will produce "+001" "-002" and so on, while "4px+" will produce "xx+1", "xx-2" etc.

• Numeric base: the way an integer should be rendered. It may be:
  • Decimal; as it's the default translation, no command is needed; a 'N' character may be added to the format to specify that we are actually expecting a number.
  • Hexadecimal: Command may be 'x' (lowercase hex), 'X' (uppercase Hex), 'c' (0x prefixed lowercase hex) or 'C' (0x prefixed uppercase hex).
  • Binary: 'b' to convert to binary, and 'B' to convert to binary and add a "b" after the number.
  • Octal: 'o' to display an octal number, or '0' to display an octal with "0" prefix.
  • Scientific: 'e' to display a number in scientific notation W.D+/-eM. Format of numbers in scientific notation is fixed, so thousand separator and decimal digit separator cannot be set, but decimals cipher setting will still work.

• Decimals: '.' followed by a number indicates the number of decimal to be displayed. If no decimal is specified, floating point numbers will be displayed with all significant digits digits, while if is's set to zero, decimal numbers will be rounded.

• Decimal separator: a 'd' followed by any non-cipher character will be interpreted as decimal separator setting. For example, to use central european standard for decimal nubmers and limit the output to 3 decimals, write ".3d,", or "d,.3". The default value is '.'.

• (Thousand) Grouping: actually it's the integer part group separator, as it will be displayed also for hexadecimal, octal and binary conversions. It is set using 'g' followed by the separator character, it defaults to ','. Normally, it is not displayed; to activate it set also the integer grouping digit count; normally is 3, but it's 4 in Jpanaese and Chinese localses, while it may be useful to set it to 2 or 4 for hexadecimal, 3 for octal and 4 or 8 for binary. For example 'g4-' would group digits 4 by 4, grouping them with a "-". Zero would disable grouping.

• Grouping Character: If willing to change only the grouping character and not the default grouping count, use 'G'.

• Alignment: by default the field is aligned to the left; to align the field to the right use 'r'.

• Negative display format: By default, a '-' sign is appended in front of the number if it's negative. If the '+' character is added to the format, then in case the number is positive, '+' will be appended in front. '--' will postpend a '-' if the number is negative, while '++' will postpend either '+' or '-' depending on the sign of the number. To display a parenthesis around negative numbers, use '[', or use ']' to display a parenthesis for negative numbers and use the padding character in front and after positive numbers. Using parenthesis will prevent using '+', '++' or '--' formats. Format '-^' will add a - in front of padding space if the number is negative, while '+^' will add plus or minus depending on number sign. For example, "5+" would render -12 as " -12", while "5+^" will render as "- 12". If alignment is to the right, the sign will be added at the other side of the padding: "5+^r" would render -12 as "12 -". If size is not mandatory, parenthesis will be wrapped around the formatted field, while if size is mandatory they will be wrapped around the whole field, included padding. For example "5[r" on -4 would render as " (4)", while "5*[r" would render as "( 4)".

• Object specific format: Objects may accept an object specific formatting as parameter of the standard "toString" method. A pipe separator '|' will cause all the following format to be passed unparsed to the toString method of objects eventually being formatted. If the object does not provides a toString method, or if it's not an object at all, an error will be raised. The object is the sole responsible for parsing and applying its specific format.

• Nil format: How to represent a nil. It may be one of the following:
  • 'nn': nil is not represented (mute).
  • 'nN': nil is represented by "N"
  • 'nl': nil is rendered with "nil"
  • 'nL': nil is rendered with "Nil". This is also the default.
  • 'nu': nil is rendered with "Null"
  • 'nU': nil is rendered with "NULL"
  • 'no': nil is rendered with "None"
  • 'nA': nil is rendered with "NA"

• Action on error: Normally, if trying to format something different from what is expected, format() the method will simply return false. For example, to format a string in a number, a string using the date formatter, a number in a simple pad-and-size formatter etc. To change this behavior, use '/' followed by one of the following:
  • 'n': act as the wrong item was nil (and uses the defined nil formatter).
  • '0': act as if the given item was 0, the empty string or an invalid date, or anyhow the neuter member of the expected type.
  • 'r': raise a type error. A 'c' letter may be added after the '/' and before the specifier to try a basic conversion into the expected type before triggering the requested effect. This will, for example, cause the toString() method of objects to be called if the formatting is detected to be a string-type format.

If the pattern is invalid, a paramter error will be raised. Examples:

• "8*Xs-g2": Mandatory 8 characters, Hexadecimal uppercase, grouped 2 by 2 with '-' characters. A result may be "0A-F1-DA".
• "12.3'0r+/r" - 12 ciphers, of which 3 are fixed decimals, 0 padded, right aligned. + is always added in front of positive numbers. In case the formatted item is not a number, a type error is raised.

Note:

ranges will be represented as [n1:n2] or [n1:] if they are open. Size, alignment and padding will work on the whole range, while numeric formatting will be applied to each end of the range.

Returns:

true if parse is succesful, false on parse format error.

Referenced by Format().

void Falcon::Format::reset

(

)

sets default values

Referenced by Format().

void Falcon::Format::rightAlign

(

bool

b

)

[inline]

bool Falcon::Format::rightAlign

(

)

const [inline]

---

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

• /home/gian/Progetti/falcon/core/include/falcon/format.h