|
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 an 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 lld lli llo llx llX 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.
|
|
Extended real number formatters
These formatters are equivalent to regular %g, %f and %e, but provide more options and are implemented by fast U++ internal conversion routine.
m
|
equivalent of %g
|
M
|
equivalent of %G (with capital E in exponent)
|
me
|
equivalent of %e
|
mE
|
equivalent of %E
|
mf
|
equivalent of %f
|
ml, Ml, mle, mlE, mlf
|
adding 'l' after 'm' activates locale customization based on language. At the moment this replaces decimal point with local version.
|
|
The format of options of alternative real number formatters is
[+|<space>][[-][width][,|.][precision][!|?||^|&|#]..
+
|
always prepend the number with sign
|
<space>
|
if number is positive, prepend it with space
|
[-][width]
|
requested minimal width. If the formatted number is smaller, it is padded with spaces or with zeros when width starts with zero. If width is negative, padding added is on the right (otherwise left).
|
, .
|
separates width from precision. ',' sets decimal point to ','.
|
precision
|
number of valid digits for %m, number of places after decimal point for %me and %mf.
|
!
|
preserve insignificant zeros in %m format
|
?
|
if number is inf or nan, do not print "inf" or "nan" and leave the output empty
|
_
|
do not prepend '-' for negative zero
|
^
|
do not add plus sign to exponent
|
&
|
make exponent minimal - 1e9 instead of 1e+09
|
#
|
preserve insignificant zeros and/or always print the decimal point
|
|
Legacy real number formatters
These are legacy U++ formatters, superseded by %m family
n
|
fixed decimals
|
v
|
valid decimals
|
ne, ve
|
force exponential notation
|
nf, vf
|
force fixed notation
|
nl, vl
|
locale/language-based formatting (can use ',' instead of '.' and add thousands separators)
|
|
The format of options of alternative real number formatters is
[+][[-]digits][@][,][!][^[+]expdig]
+
|
always prepend sign (even if positive number)
|
[-]digits
|
number of decimals to print (negative = left of decimal point, default = 6)
|
@
|
do not use thousands separators (in internationalized formatting nl or vl)
|
,
|
use ',' instead of '.' for decimal point
|
!
|
keep insignificant zeros
|
^
|
exponent options:
+
|
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("%dpt", 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", 1234567.89)
|
1.234568e+006
|
Format("%E", 1234567.89)
|
1.234568E+006
|
Format("%f", 1234567.89)
|
1234567.890000
|
Format("%g", 1234567.89)
|
1.23457e+006
|
Format("%G", 1234567.89)
|
1.23457E+006
|
Format("%m", 1234567.89)
|
1.23457e+06
|
Format("%M", 1234567.89)
|
1.23457E+06
|
Format("%,m", 1234567.89)
|
1,23457e+06
|
Format("%+m", 1234567.89)
|
+1.23457e+06
|
Format("% m", 1234567.89)
|
1.23457e+06
|
Format("%.10m", 1234567.89)
|
1234567.89
|
Format("%.10!m", 1234567.89)
|
1234567.890
|
Format("%.6m", 1234567.89)
|
1.23457e+06
|
Format("%.7m", 1234567.89)
|
1234568
|
Format("%.7#m", 1234567)
|
1234567.
|
Format("%m", -0.0)
|
-0
|
Format("%_m", -0.0)
|
0
|
Format("%m", 1e9)
|
1e+09
|
Format("%^m", 1e9)
|
1e09
|
Format("%&m", 1e9)
|
1e+9
|
Format("%&^m", 1e9)
|
1e9
|
Format("%m", log(-1))
|
-nan
|
Format("%?m", log(-1))
|
|
Format("%.5mf", 1234567.89)
|
1234567.89000
|
Format("%.2me", 1234567.89)
|
1.23e+06
|
Format("%.2mE", 1234567.89)
|
1.23E+06
|
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())
|
11/11/2011
|
Format("%", GetSysTime())
|
11/11/2011 14:44:11
|
Format("%", "text")
|
text
|
|
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.
Format registration functions
|
|
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 bool, 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.
void RegisterNullFormatter(const char *id, Formatter f)
Registers formatter id to be applied when the Value argument is Void (Value()) or ErrorValue.
|
