User-defined formats

General syntax

A user-defined format is described by a sequence of special characters.

Arbitrary characters specified before and after the format strings will be printed as is.

To prevent the interpretation of a special character, you have to quote it with the \ character.

Format syntax for a numeric expression

+ Print the sign of the number.
- Print the sign of the number only if it is negative.
# Print a digit only if necessary.

The number is left-padded with spaces so that the number of printed characters before the decimal point is greater or equal than the number of # before the decimal point.
0 Always print a digit, padding with a zero if necessary.
. Print the decimal separator.
, Print the thousand separators.
% Multiply the number by 100 and print a per-cent sign.
E Introduces the exponential part of a Float number. The sign of the exponent is always printed.

Examples

PRINT Format$(Pi, "-#.###")
 3.142

PRINT Format$(Pi, "+0#.###0")
+03.1416

PRINT Format$(Pi / 10, "###.# %")
 31.4 %

PRINT Format$(-11 ^ 11, "#.##E##")
-2.85E+11

Format syntax for currencies

To format currencies, you can use all numeric format characters, and the following ones:

$ Print the national currency symbol.
$$ When the $ is doubled, the international currency symbol is printed instead.
( Print the representation of negative currencies. This must be the first character of the format. You can specify a closed brace ) at the end of the format.

Examples

PRINT Format$(1972.06, "$#.###")
$1972.06

PRINT Format$(-1972.06, "$,#.###")
-$1,972.06

PRINT Format$(-1972.06, "($$,#.###)")
(USD 1,972.06)

Format syntax for dates

yy Print the year on two digits.
yyyy Print the year on four digits.
m Print the month.
mm Print the month on two digits.
mmm Print the month in an abbreviated localized string form.
mmmm Print the month in its full localized string form.
d Print the day.
dd Print the day on two digits.
ddd Print the week day in an abbreviated localized form.
dddd Print the week day in its full localized form.
/ Print the date separator.
h Print the hour.
hh Print the hour on two digits.
n Print the minutes.
nn Print the minutes on two digits.
s Print the seconds.
ss Print the seconds on two digits.
: Print the time separator.
u Print a point and the milliseconds, if they are different from zero.
uu Print a point and the milliseconds with three digits.
t Print the timezone alphabetic abbreviation.
Sinds 3.1
tt Print the timezone in HHMM format.
Sinds 3.1
AM/PM Print the localized equivalent of AM or PM, according to the hour, and force the hour to be between 1 and 12.

Since Gambas 3, the u date format does not print a point anymore. You must add it explicitly in the format string.

Examples

PRINT Format$(Now, "mm/dd/yyyy hh:nn:ss.u")
04/15/2002 09:05:36.26

PRINT Format$(Now, "mm/dd/yyyy hh:nn:ss.uu")
04/15/2002 09:05:36.026

PRINT Format$(Now, "m/d/yy h:n:s")
4/15/02 9:5:36

PRINT Format$(Now, "ddd dd mmm yyyy")
Mon 15 Apr 2002

PRINT Format$(Now, "dddd dd mmmm yyyy")
Monday 15 April 2002

PRINT Format$(Now, "yyyy-mm-dd hh-nn-ss")
PRINT Format$(Now, "yyyy/mm/dd hh:nn:ss")
2006-04-29 07-41-11
2006.04.29 07:41:11