Format Specifiers

There is a general Format routine. The second parameter is always a format specification string. This document covers the format of these specifications.

Number Formats

The format string for any Number value will have a single format field of the form :-

fmtfield ::= code [ + ] [ length [ . places ] ] [[ suffix]] [#base ]

The code will be one of :-

Code	Meaning
I	Always write as integer - round if necessary
R	Always write as real number
E	Write in exponent notation
N	Treat as I or R based on the actual value

The '+' means that the sign should always be written, even if positive.

The length refers to the overall length of the string to produce. If the number is shorter the the allowed with the number fill be padded. If the number is longer then the field will be expanded. If omitted there will be no padding

The places refers to the number of decimal places to show.

The suffix is a set of options controlling the format.

Suffix	Meaning
r	Right justify
t	Add thousand separator ( integers only)
z	Pad with zeros

The #base is the base for writing integers.

Not all combinations will be valid but the system will do its best to generate meaning fill output. For example padding only applies to right justified numbers and the base only applies to integer output. The user should check what works.

Logical Formats

fmtfield ::= code [ length ] [ case ] [ p ] [ r ]

The Logical values are treated effectively as an enumerate type ( see below ). The value for False and True are 0 and 1 respectively. The text values are taken from the current language file.

Code

The code is a single letter as listed below :-

Code	Meaning
T	Format as text
N	Format as number

Length

The length field specifies the maximum number of letters to write.

Case

The case suffix indicates which version of the name to use.

Code	Meaning
u	Upper case
l	Lower case
c	Capitalised
d	Default

Other

Code	Meaning
p	Padding
r	Right Align

The Padding option specifies that short names should be padded out with spaces at the end to fill to the specified length. The Right Align option specifies that the padding should be placed at the front so the the right hand ends are aligned.

Enum Formats

fmtfield ::= code [ length ] [ p ] [ r ]

Enumerated can be written as text or ( rarely ) as numbers.

Code	Meaning
T	Format as text
N	Format as number

The interpretation of the length value If padding is specified then any short names will be padded to the length. There is also an alignment code 'r' for right align ( the default is left ). If both are specified the padding must be specified first.

Other

Code	Meaning
p	Padding
r	Right Align

Time and Date Formats

A date format string consists of a series of field format specifiers with other characters interspersed. Any characters not matching a code will be copied as is. All the examples are based on the language file for English as supplied with the system.

The general form of a field specifier is :-

It is also possible to extract individual numeric fields and format them with the more flexible number formatting specifiers.

fmtfield ::= code [ length ] [ case ] [ padding ] [ r ]

Code

The code is a single letter as listed below :-

Code	Meaning
Y	Year
M	Month as number
N	Name of month
D	Day of month as number
R	Ordinal suffix of day
W	Day of week as a word
H or h	Hour
T or m	Minutes
S or s	Seconds
F or f	fraction of second ( milliseconds )
A or a	am/pm indicator

For the month and day names and the am/pm indicator the actual names come from the language file as specified in the initialisation file or on the command line.

Not all the modifiers are allowed in all the fields. Any options included must be in the order given above.

Any character not recognised as a code will be displayed as is. To explicitly print a code character, precede it with a '\' ( as backslashes themselves need to be preceded by backslashes in the source you and up with two ). It is safer to use more that one Format statement and use text concatenation to handle this sort of thing.

If one of the date related specifiers is used then the Time value must contain a date part ( not just a time part ).

Length

The length field's meaning varies according to the code.

For field where the output is a word ( N, D, R, A ) the length specifies the maximum number of letters to write - any word longer than this will be truncated. If the value is omitted the full name is always written.

For the year field ( Y ) the value must be 2 or 4. If the value is 2 then only the last two digits will be written.

For the hour field ( H/h ) the length is either 1 for 12 hour clock or 2 for 24 hour clock - if omitted a 24 hour clock will be assumed. The actual field length will be 2.

For the minute and second fields ( T/m, S/s ) the lengths default to 2.

For the fraction of a second ( F/f ) the value should be 1, 2 or 3 decimal places ( the value will be truncated ).

Case

The case suffix indicates which version of the name to use.

Code	Meaning
u	Upper case
l	Lower case
c	Capitalised
d	Default

The actual case versions are taken directly from the language current language file.

Padding

The p suffix determines how short names are padded out to the full specified lengths. If it is present then short strings or number will be padded out. The year field uses its own padding rules. Padding only works if you use a fixed pitch font.

Code	Meaning
p	Pad with spaces
z	Pad with zeros

The zero padding option only applies to numbers.

Right Justify

The r suffix says that and padding should be placed in from of the text to ensure that the right hand side of the fields align. This is not used for the numeric fields.

Examples -

Full example

Time start = '2010-12-25@11:32:05.135';
 . . .
str := Format(start, "Wc, DRl Nd, Y4 \\a\\t H2z:Tz:Sz.F3");

[= better to use =]
str := Format(start, "Wc, DRl Nd, Y4") + " at " + Format(start, "H2z:Tz:Sz.F3");

This will yield :-

"Saturday, 25th December, 2010 at 11:32:05.135"