LOTUSSCRIPT LANGUAGE


Format function
Example

Formats a number, a date/time, or a string according to a supplied format.

Syntax

Format[$] ( expr [ , fmt ] )

Elements

expr


fmt
Return value

Format returns a Variant containing a string, and Format$ returns a String.

If expr is a string and fmt is a numeric format string, LotusScript attempts to convert the string to a number. If successful, LotusScript then formats the result.

If the string can't be converted to a number, LotusScript attempts to interpret it as a date/time, and attempts to convert it to a numeric value. If successful, LotusScript then formats the result.

If expr can't be converted to the data type of the format string, Format returns expr without formatting it.

Formatting codes

Numeric formats

If expr is numeric, you can use one of the named numeric formats shown in the following section, or create a custom numeric format using the numeric formatting codes shown in the subsequent section.

Named numeric formats

Format nameDisplay of the value of expr is ...
General NumberAs stored, without thousands separators
CurrencyAs defined in the operating system's international settings. For example, you can format currency values with thousands separators, negative values in parentheses, and two digits to the right of the decimal separator.

In OS/2, the function does not append the currency symbol to the number.

FixedWith at least one digit to the left of the decimal separator, and with two digits to the right of the decimal separator.
StandardWith thousands separators, with at least one digit to the left of the decimal separator, and with two digits to the right of the decimal separator.
Percentexpr multiplied by 100, with at least one digit to the left of the decimal separator. Two digits are displayed to the right of the decimal separator, and a percent sign (%) follows the number.
ScientificIn standard scientific notation: with one digit to the left of the decimal separator and two digits to the right of the decimal separator, followed by the letter E or e and a number representing the exponent.
Yes/NoNo if the number is 0, and Yes otherwise.
True/FalseFalse if the number is 0, and True otherwise.
On/OffOff if the number is 0, and On otherwise.

Custom numeric formatting codes

The following table describes the characters you can use in fmt to create custom formats for numeric values.

Formatting codeMeaning
"" (Empty string)Display the number with no formatting
0 (zero)Digit forced display. A digit is displayed for each zero in fmt, with leading or trailing zeros to fill unused spaces. All digits to the left of the decimal separator are displayed. If the number includes more decimal places than fmt, it is rounded appropriately.
# (pound sign)Digit conditional display. The same display as 0 (digit forced display), except that no leading or trailing zeros are displayed.
. (period)Decimal separator. The position of the decimal separator in fmt. Unless your formatting code includes a 0 immediately to the left of the decimal separator, numbers between -1 and 1 begin with the decimal separator, The actual decimal separator used in the returned formatted value is the decimal separator specified in the operating system's international settings.
% (percent sign)Percentage placeholder. Multiplies the number by 100 and inserts the percent sign (%) in the position where it appears in fmt. If you include more than one percentage placeholder, the number is multiplied by 100 for each %. For example, %% means multiplication by 10000.
, (comma)Thousands separator. To separate groups of three digits, counting left from the decimal separator, within numbers that include at least four digits to the left of the decimal separator, enclose the comma between a pair of the digit symbols 0 or #. The actual thousands separator used in the returned formatted value is the thousands separator specified in the operating system's international settings.
A special case is when the comma is placed immediately to the left of the decimal separator (or the position of the implied decimal separator). This causes the number to be divided by 1000. For example, this returns "100":

x = Format$(100000,"##0,.")

If 100000 is replaced in this example by a number less than 1000 in absolute value, then this function returns "0."

E- E+ e- e+Scientific notation. The number of digit symbols (0 or #) to the left of the decimal separator specifies how many digits are displayed to the left of the decimal separator, and the resulting magnitude of the exponent.
Use E+ or e+ to display the sign of all exponents (the symbol + or -). Use E- or e- to display the sign of negative exponents only (the symbol -).
All exponent digits are displayed, regardless of how many digit symbols follow the E-, E+, e-, or e+. If there are no digit symbols (the symbol 0 or #), an exponent of zero is not displayed; otherwise at least one exponent digit is displayed. Use 0 to format a minimum number of exponent digits, up to a maximum of three.
$ (dollar sign)Currency symbol. Designates a currency value. The actual currency symbol used in the returned formatted value is the currency symbol specified in the operating system's international settings.
- + ( ) spaceLiteral characters. These are displayed as they appear in the format string.
\ (backslash)Literal character prefix. The character following the backslash is displayed as is; for example, \# displays #. To display a backslash itself, precede it with another backslash; that is, \\ displays \.
"ABC"Literal string enclosed in double quotation marks. To specify the double quotation mark character in the fmt argument, you must use Chr(34).

The characters enclosed in quotation marks are displayed as they appear in the format string.

; (semicolon)Format section separator. Separates the positive, negative, zero, and NULL sections in fmt. If you omit the negative or zero format sections, but include the semicolons representing them, they are formatted like the positive section.
A custom format string for numeric values can have from one to four sections, separated by semicolons. In a format string with more than one section, each section applies to different values of expr. The number of sections determines the values to which each individual section applies. The following table describes how each section of a one-part or multi-part format string is used.

Number of sectionsDescription
OneThe format applies to all numbers.
TwoThe first section formats positive numbers and 0.
The second section formats negative numbers.
ThreeThe first section formats positive numbers.
The second section formats negative numbers.
The third section formats 0.
FourThe first section formats positive numbers.
The second section formats negative numbers.
The third section formats 0.
The fourth section formats NULL.

Date/time formats

Since date/time values are stored as floating point numbers, date/time values can be formatted with numeric formats. They can also be formatted with date/time formats. You can either use one of the named date/time formats shown in the following section, or create a custom date/time format using the date/time formatting codes shown in the subsequent section.

Named date/time formats

Format nameDisplay of the date/time value is ...
General DateIn a standard format. Converts a floating-point number to a date/time. If the number includes no fractional part, this displays only a date. If the number includes no integer part, this displays only a time.
Long DateA Long Date as defined in the operating system's international settings.
Medium Datedd-mmm-yy (yy/mmm/dd in Japan)
Short DateA Short Date as defined in the operating system's international settings.
Long TimeA Long Time as defined in the operating system's international settings. Long Time always includes hours, minutes, and seconds.
Medium TimeHours (0 - 12) and minutes using the time separator and AM/PM notation (AMPM notation in Japan)
Short TimeHours (0 - 23) and minutes using only the time separator.

Custom date/time formatting codes

The following table describes the characters you can use in fmt to create custom formats for date/time values.

Formatting codeMeaning
: (colon)Time separator. Separates hours, minutes, and seconds in formatted time values. The actual time separator used in the returned formatted value is the time separator specified for the given country in the operating system's international settings.
/ (slash)Date separator. Separates day, month, and year in formatted date values. The actual date separator used in the returned formatted value is the date separator specified in the operating system's international settings.
cDisplays a date as ddddd, and a time as ttttt (see below). If the value includes no fractional part, only a date is displayed. If the value includes no integer part, only a time is displayed.
yDay of the year as a number (1 - 366).
dDay of the month as a number without a leading zero (1 - 31).
ddDay of the month as a number with a leading zero
(01 - 31).
dddWeekday as a three-letter abbreviation (Sun - Sat).
ddddWeekday spelled out (Sunday - Saturday).
dddddSerial date number as a complete date (day, month, and year) formatted as an international Short Date string. If there is no Short Date string provided in the operating system, the date format defaults to mm/dd/yy.
ddddddSerial date number as a complete date (day, month, and year) formatted as an international Long Date string. If there is no Long Date string provided in the operating system, the date format defaults to mmmm dd, yyyy.
wWeekday as a number (1 - 7). Sunday is 1.
wwWeek of the year as a number (1 - 53).
mMonth of the year as a number without a leading zero (1 - 12). If the character is preceded by h in fmt, it displays the minute of the hour as a number without a leading zero (0 - 59).
mmMonth of the year as a number with a leading zero (01 - 12). If the character is preceded by h in fmt, it displays the minute of the hour as a number with a leading zero (00 - 59).
mmmMonth name as a 3-letter abbreviation (Jan - Dec).
mmmmMonth name spelled out (January - December).
qQuarter of the year as a number (1 - 4).
yyThe last two digits of the year (00 - 99). If you specify yy in Notes or Domino, LotusScript interprets 50 through 99 as the years 1950 through 1999 and 00 through 49 as the years 2000 through 2049. Note that SmartSuite interprets yy differently.
yyyyThe full (four-digit) year (0100 - 9999).
hHour of the day as a number without a leading zero (0 - 23).
hhHour of the day as a number with a leading zero
(00 - 23).
nMinute of the hour as a number without a leading zero (0 - 59).
nnMinute of the hour as a number with a leading zero (00 - 59).
sSecond of the minute as a number without a leading zero (0 - 59).
ssSecond of the minute as a number with a leading zero (00 - 59).
tttttTime serial number as a complete time (including hour, minute, and second), formatted using the time separator provided in the operating system's international settings. A leading zero is displayed if the international leading zero setting is TRUE and the time is before 10:00 AM or PM. The default time format is h:mm:ss.
AM/PM am/pmUses hour values from 1 to 12, displaying AM or am for hours before noon, and PM or pm for hours after noon.
A/P a/pUses hour values from 1 to 12, displaying A or a for hours before noon, and P or p for hours after noon.
AMPMUses hour values from 1 to 12. Displays the contents of the 1159 string (s1159) in WIN.INI for hours before noon, and the contents of the 2359 string (s2359) for hours after noon. AMPM is case-insensitive, but the case of the string displayed matches the string as it exists in the operating system's international settings. The default format is AM/PM.
The following table shows some custom date/time formats applied to one date and time: 6:43:04 in the evening of April 12, 1995.

fmtDisplay
m/d/yy4/12/95
d-mmm-yy12-Apr-95
d-mmmm12-April
mmmm-yyApril-95
y102.00
hh:nn AM/PM06:43 PM
h:nn:ss a/p6:43:04 p
h:nn18:43
h:nn:ss18:43:04
m/d/yy h:nn4/12/95 18:43

String formatting codes

To format a string using Format or Format$, use the formatting codes in the following table to create a custom string format. There are no named string formats.

Custom string formats can have one section, or two sections separated by a semicolon (;). If the format has one section, the format applies to all strings. If the format has two sections, then the first applies to nonempty strings, and the second applies to the value NULL and the empty string ("").

The following table describes the characters you can use in fmt to create a custom string format.

Formatting codeMeaning
@ (at sign)Character forced display.
If the string being formatted includes a character in this position, display it. If not, display a space. @ is filled from right to left unless fmt contains an exclamation point (!).
& (ampersand)Character optional display.

If the string being formatted includes a character in this position, display it. If not, display nothing. & is filled from right to left unless fmt contains an exclamation point (!).

< (less-than sign)All characters in the formatted string are displayed in lowercase.
> (greater-than sign)All characters in the formatted string are displayed in uppercase.
! (exclamation point)Forces @ and & to fill from left to right, rather than from right to left.

Formatting dates and times in Asian languages

The Format function supports additional formatting characters for dates and times in versions of LotusScript for Japan, China, the Taiwan region, and Korea.

Only single-byte characters are recognized as formatting characters. Double-byte characters are treated as literal characters. Some of the formatting characters for LotusScript in China and the Taiwan region are case-sensitive (see the following paragraphs); all of the other Asian language date/time formatting characters are case-insensitive.

When a date/time formatting code used in the Format function in LotusScript for Japan is also a date/time formatting code in WIN.INI, LotusScript for Japan interprets the code appropriately. For example, the formatting expression "Long Date" has the same meaning in LotusScript for Japan as in English-language LotusScript. (The meaning is to use the WIN.INI Long Date format.)

These formats only have meanings in Asian versions of Lotus products.

Date/time format codes

The first table shows the formatting codes for Japan.
Formatting codeMeaning
aaaWeekday in abbreviated format (one double-byte character)
aaaaWeekday in full format
eYear in era ("0" suppressed)
eeYear in era ("0" not suppressed)
gEra name (single-byte one-character abbreviation)
ggEra name (double-byte one-character abbreviation)
gggFull era name

This table shows the formatting codes for People's Republic of China.
Formatting codeMeaning
aaaaWeekday in full format (three double-byte characters)
OMonth (double-byte)
oMonth (single-byte)
ADay (double-byte)
aDay (single-byte)
EShort year (double-byte)
eShort year (single-byte)
EELong year (double-byte)
eeYear (single-byte)

This table shows the formatting codes for the Taiwan region.
Formatting codeMeaning
aaaaWeekday in full format (three double-byte characters)
OMonth (double-byte)
oMonth (single-byte)
ADay (double-byte)
aDay (single-byte)
EYear in era (double-byte)
eYear in era (single-byte)
EEYear in era with era abbreviation (double-byte)
eeYear in era with era abbreviation (single-byte)
EEEYear in era with era name (double-byte)
eeeYear in era with era name (single-byte)
EEEEChristian year with Christian era name (double-byte)
eeeeChristian year with Christian era name (single-byte)
This table shows the formatting codes for Korea.

Formatting code Meaning
aaaWeekday in abbreviated format (one double-byte character)
aaaaWeekday in full format (three double-byte characters)

Example
See Also