Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site













SourceForge.net Logo

Format - 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 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.

 

 

Alternative real number formatters

 

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("%n", 1234567.89)

1234567.89

Format("%,n", 1234567.89)

1234567,89

Format("%+n", 1234567.89)

+1234567.89

Format("%2,n", 123.456)

123,46

Format("%2,n", 123)

123

Format("%2!,n", 123)

123.00

Format("%ne", 1234567.89)

1234567.89

Format("%nf", 1234567.89e30)

1234567890000000000000000000000000000

Format("%nl", 1234567.89)

1,234,567.89

Format("%@nl", 1234567.89)

1234567.89

Format("%@,nl", 1234567.89)

1234567,89

Format("%v", 1234567.89)

1234570

Format("%ve", 1234567.89)

1234570

Format("%vf", 1234567.89e30)

1234570000000000000000000000000000000

Format("%vl", 1234567.89)

1,234,570

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.

 

Formatting

 

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.

 

 

Last edit by cxl on 10/11/2017. Do you want to contribute?. T++