Falcon::Format Class Reference

Item to string format class. More...

#include <format.h>

Inheritance diagram for Falcon::Format:

Inheritance graph
[legend]

List of all members.

Public Types


Public Member Functions

virtual FalconDataclone () 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 StringoriginalFormat () 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

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.

Conversion type.

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

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.

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.

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:

Generated on Mon Oct 19 10:11:35 2009 for Falcon_Core by  doxygen 1.5.8