Text formatting
String Format(const char *format, const Vector<Value>& args)
String Format(const char *format, Value arg1 [, Value argn]... )
String Format(int language, const char *s, const Vector<Value>& v)
String Format(int language, const char *format, Value arg1 [, Value argn]... )
Format forms output text based on format, inserting actual arguments to placeholders. Argument values are converted to text using formatters. U++ specifies set of standard formatters; application can freely register their own formatters for specific Value types too.
Note that the variable number of Value arguments is implemented by overloading the Format up to 20 parameters.
Placeholders start with % and have format:
%[commands][options][formatter-id][`]
commands are interpreted by Format routine (not specific formatter). Each command sequence ends with character specifying the kind of command, this delimits it from options and/or formatter.
Available commands:
|
position:
|
Seeks to an argument at position. Allows to "reorganize" ordering of arguments, useful with translations.
|
width<
|
Places formatter result into field with width characters, aligns left.
|
width>
|
Places formatter result into field with width characters, aligns right.
|
width=
|
Places formatter result into field with width characters, aligns to center.
|
[text]~
|
If argument is Null, uses text instead of formatter result.
|
|
|
formatter-id must consist of alpha characters only, unlike C identifiers, digits or '_' are not allowed. Everything between commands and formatter-id is considered to be options and passed to formatter. Note that formatter-id is Value type specific - the same name can specify different formatter depending on Value type. formatter-id is case-sensitive.
Character * in options section is replaced by argument converted using AsString.
If options are to contain alpha characters, they need to be escaped using [ ] to distinguish options from formatter-id.
Placeholder can end either by non-alpha character or by `. formatter-id can be left empty; in that case Format uses AsString to convert Value to text (defined in RichValue interface) - the most trivial placeholder is therefore %`.
While Format implements all of classic printf formatter, please notice two incompatibilities:
All arguments of Format must be convertible (and are converted) to Value. On the positive side, Value performs natural conversions like double -> int, so it is possible to e.g. use %d for double value.
formatter-id "eats" all alpha characters. This is a problem when non-placeholder alpha character is to follow placeholder, e.g. %dpt - this has to be written as %d`pt (` delimits the formatter-id).
Standard formatters
default formatter
If formatter-id is empty, Value is converted using AsString (implemented in RichValue interface).
printf formatters
Most printf formatters are supported:
c d i o x X ld li lo lx lX e E f g G s
Please refer to printf documentation for the description.
switch formatter
This is special number formatter (registered for double, int and int64 values). options of switch formatter contain a list of values and respective texts - a text for actual argument is printed. formatter-id is s.
The format of switch options is
[modulo%][case:text;]...[default]
|
modulo
|
If this optional part is present, modulo of argument is used for switch cases.
|
case
|
Numeric case.
|
text
|
Text for given numeric case.
|
default
|
Default text when no case is matched.
|
|
|
Note that as text usually contains letters, whole switch options section is almost always escaped using [ ].
simple integer formatters
These formatters are registered for double, int and int64 values.
|
formatter-id
|
Description
|
month
|
Lower-case month name.
|
Month
|
Month name with first letter upper-case, rest lower-case.
|
MONTH
|
Upper-case month name.
|
mon
|
Abbreviated lower-case month name.
|
Mon
|
Abbreviated month name, first letter upper-case, rest lower-case.
|
MON
|
Abbreviated upper-case month name.
|
day
|
Lower-case day name.
|
Day
|
Day name with first letter upper-case, rest lower-case.
|
DAY
|
Upper-case day name.
|
dy
|
Abbreviated lower-case day name.
|
Dy
|
Abbreviated day name, first letter upper-case, rest lower-case.
|
DY
|
Abbreviated upper-case day name.
|
tw
|
12-hour modulo format.
|
a
|
Letter format, 1: a, 2: b, ... 26: z, 27: aa, ...
|
A
|
Letter format, 1: a, 2: b, ... 26: z, 27: aa, ...
|
r
|
Lower-case roman numbers.
|
R
|
Upper-case roman numbers.
|
|
|
alternate real number formatters
|
ne, ve |
force exponential notation |
|
nf, vf |
force fixed notation |
|
nl, vl |
language-based formatting |
The format of options is
[+][[-]digits][!][^[+]expdig]
|
[-]digits |
number of decimals to print (negative = left of decimal point, default = 6) |
|
! |
keep insignificant zeros |
|
+ |
always prepend sign to exponent |
|
expdig |
exponent padding width |
Examples of standard formatters
|
Format("%d, %s", 123, "TEXT")
|
123, TEXT
|
Format("%2:s, %1:d", 123, "TEXT")
|
TEXT, 123
|
Format("%010d", 123)
|
0000000123
|
Format("%0*d", 11, 123)
|
00000000123
|
Format("|%20<d|", 123)
|
|123 |
|
Format("|%20>d|", 123)
|
| 123|
|
Format("|%20=d|", 123)
|
| 123 |
|
Format("%d`pt", 123)
|
123pt
|
Format("%[empty]~d, %[empty]~d", 123, Null)
|
123, empty
|
Format("%`", 123)
|
123
|
Format("%c", 65)
|
A
|
Format("%d", 123)
|
123
|
Format("%i", 123)
|
123
|
Format("%o", 123)
|
173
|
Format("%x", 123)
|
7b
|
Format("%X", 123)
|
7B
|
Format("%e", 1.23)
|
1.230000e+000
|
Format("%E", 1.23)
|
1.230000E+000
|
Format("%f", 1.23)
|
1.230000
|
Format("%g", 1.23)
|
1.23
|
Format("%G", 1.23)
|
1.23
|
Format("%n", 1.23)
|
1.23
|
Format("%1n", 1.23)
|
1.2 (explicit number of decimals)
|
Format("%3!n", 1.23)
|
1.230 (force insignificant zeros)
|
Format("%ne", 1.23)
|
1.23e0
|
Format("%2^+3ne", 1.23)
|
1.2e+000 (exponent formatting)
|
Format("%nf", 1.23e30)
|
1230000000000000000000000000000
|
Format("%nl", 1.23)
|
1,23
|
Format("%v", 1.23)
|
1.23
|
Format("%2v", 1.23)
|
1.2 (2 valid digits)
|
Format("%2v", 123)
|
120 (2 valid digits)
|
Format("%ve", 1.23)
|
1.23e0
|
Format("%vf", 1.23e30)
|
1230000000000000000000000000000
|
Format("%vl", 1.23)
|
1,23
|
Format("%[1:one;2:two;3:three;another]s", 2)
|
two
|
Format("%[1:one;2:two;3:three;another]s", 20)
|
another
|
Format("%[3%1:one;2:two;3:three;another]s", 20)
|
two
|
Format("%month", 6)
|
june
|
Format("%Month", 6)
|
June
|
Format("%MONTH", 6)
|
JUNE
|
Format("%mon", 6)
|
jun
|
Format("%Mon", 6)
|
Jun
|
Format("%MON", 6)
|
JUN
|
Format("%day", 6)
|
saturday
|
Format("%Day", 6)
|
Saturday
|
Format("%DAY", 6)
|
SATURDAY
|
Format("%dy", 6)
|
sa
|
Format("%Dy", 6)
|
Sa
|
Format("%DY", 6)
|
SA
|
Format("%tw", 0)
|
12
|
Format("%tw", 5)
|
5
|
Format("%tw", 15)
|
3
|
Format("%0tw", 15)
|
03
|
Format("%a", 1)
|
a
|
Format("%a", 123)
|
es
|
Format("%A", 1)
|
A
|
Format("%A", 123)
|
ES
|
Format("%r", 8)
|
viii
|
Format("%R", 1231)
|
MCCXXXI
|
Format("%`", GetSysDate())
|
08/25/2006
|
Format("%`", GetSysTime())
|
08/25/2006 20:37:09
|
Format("%`", "text")
|
text
|
Format("%`", GetSysDate())
|
25.08.2006
|
|
|
Registering custom formatters
typedef String (*Formatter)(const Formatting& fmt)
Formatter has to have form of function with single Formatting argument.
struct Formatting
This structure passes all informations to format Value argument to the formatter.
int language
Language of resulting text.
Value arg
Actual argument.
String format
Formatting options.
String id
Formatter-id.
void RegisterFormatter(int type, const char *id, Formatter f)
Registers formatter for specific Value type. If type is VALUE_V, formatter is applied to all Value types if no formatter for specific type is specified.
void RegisterNumberFormatter(const char *id, Formatter f)
Registers formatter for int, double and int64 types.
void RegisterStringFormatter(const char *id, Formatter f)
Registers formatter for String and WString types.
void RegisterDateTimeFormatter(const char *id, Formatter f)
Registers formatter for Date and Time types.
void RegisterValueFormatter(const char *id, Formatter f)
Registers formatter to be applied when no formatter for specific type is specified.
|
