Pattern characters used to format non-string values to strings

A variety of characters are available for the patterns that you specify in the StringLib.format system function and in several StrLib system functions.

Sections are as follows:

Numeric patterns

The following table lists the symbols you can use to specify a pattern to format a number.

Table 1. Numeric patterns
Symbol Meaning
# A digit that uses a space as the fill character for a leading zero (unless the < character is also present).
* A digit that uses an asterisk (*) as the fill character for a leading zero (unless the < character is also present).
& A digit that uses a zero as the fill character for a leading zero (unless the < character is also present).
< Left justify the number. Leading zeros are not represented in the output.
, Use a locale-dependent numeric separator unless the position contains a leading zero.
. Use a locale-dependent decimal point.
- Use a minus sign (-) for values less than 0; use a space for values greater than or equal to 0.
+ Use a minus sign for values less than 0; use a plus sign (+) for values greater than or equal to 0.
(...) Enclose negative values with parentheses. The positions of the parentheses in the format string determine their positions in the result.
$ Precede the value with the locale-dependent currency symbol. This symbol is useful only when you place it at the beginning of the pattern.
@ Place the locale-dependent currency symbol after the value.

The following table provides examples of numeric patterns, where the letter "b" represents a blank space.

Table 2. Examples of numeric patterns
Format Pattern Data Value Formatted Result Comments
"#####" 0 bbbbb No zero symbol
"&&&&&" 0 00000  
"$$$$$" 0 bbbb$ No zero symbol
"*****" 0 ***** No zero symbol
"<<<<<" 0   Empty string
"<<<,<<<" 12345 12,345  
"<<<,<<<" 1234 1,234  
"<<<,<<<" 123 123  
"<<<,<<<" 12 12  
"##,###" 12345 12,345  
"##,###" 1234 b1,234  
"##,###" 123 bbb123  
"##,###" 12 bbbb12  
"##,###" 1 bbbbb1  
"##,###" -1 bbbbb1 No negative sign
"&&,&&&" 12345 12,345  
"&&,&&&" 1234 01,234  
"&&,&&&" 123 000123  
"&&,&&&" 12 000012  
"&&,&&&" 1 000001  
"&&,&&&" -1 000001 No negative sign
"&&,&&&" 0 000000  
"&&,&&&.&&" 12345.67 12,345.67  
"&&,&&&.&&" 1234.56 01,234.56  
"&&,&&&.&&" 123.45 000123.45  
"&&,&&&.&&" 0.01 000000.01  
"$$,$$$" 12345 ****** Overflow
"$$,$$$" 1234 $1,234  
"$$,$$$" 123 bb$123  
"$$,$$$" 12 bbb$12  
"$$,$$$" 1 bbbb$1  
"$$,$$$" 0 bbbbb$ No zero symbol

Date and timestamp patterns

For dates or timestamps, use letters to indicate the components of the date or time. To include letters in the date/time string without that text being parsed as a component of the date or time, enclose that letter or letters in single quotation marks. To display a single quotation mark in the date, time, or timestamp, use two single quotation marks.

The following table lists the letters; their values in the pattern; and their types, which are important for the detail provider later in this topic.

Letter Date or time component Type Examples
G Era designator Text AD
y Year Year 1996; 96
M Month in year Month July; Jul; 07
w Week in year Number 27
W Week in month Number 2
D Day in year Number 189
d Day in month Number 10
F Day in week Number 2
E Day of week Text Tuesday; Tue
a AM/PM marker Text PM
H Hour in day (0-23) Number 0
k Hour in day (1-24) Number 24
K Hour in AM/PM (0-11) Number 0
h Hour in AM/PM (1-12) Number 12
m Minute in hour Number 30
s Second in minute Number 55
S Millisecond Number 978
z Time zone General time zone Pacific Standard Time; PST; GMT-08:00
Z Time zone RFC 822 time zone -800
C Century Century 20; 21

Multiples of the same letter used consecutively in the pattern determine aspects of the corresponding characters in the string. The interpretation depends on the type of pattern character:

Text
If the number of letters is greater than 4, the full form is used. Otherwise, an abbreviation is used, if available.
Number
The number of pattern letters represents the minimum number of digits. If the number of pattern letters is greater than required to format the number, zeros are prepended to the number.
Year
If the number of pattern letters is 1 or 2, the year is truncated to 2 digits. If the number of pattern letters is 3 or 4, the year has 4 digits. If the number of pattern letters is greater than 4, zeros are prepended to the four-digit year.
Month
If the number of letters is 1 or 2, a numeric month value is formatted. If the number of letters is 3 or 4, an abbreviated text is used with no more characters than the specified number of letters in the subpattern for Month. If the number of letters is greater than 4, the name of the month is used.
General time zone
General time zones are interpreted as the Text type if they have names. For time zones representing a GMT offset value, the following syntax is used:

GMTOffsetTimeZone = GMT Sign Hours Minutes

Sign
Either + or -
Hours
A one-digit or two-digit number from 0 to 23. The format is locale independent and must be taken from the Basic Latin block of the Unicode standard.
Minutes
A two-digit number from 00 to 59. The format is locale independent and must be taken from the Basic Latin block of the Unicode standard.

For parsing, RFC 822 time zones are also accepted.

RFC 822 time zone
For formatting, the RFC 822 4-digit time zone format is used

RFC822TimeZone = Sign TwoDigitHours Minutes

TwoDigitHours must be a two-digit number from 00 to 23. The other definitions are the same as the General time zone type.

For parsing, General time zones are also accepted.

Century
Displayed as a Number type that shows the result of the following calculation: full year divided by 100, with the remainder ignored.

The following table lists some examples of date and time patterns interpreted in the U.S. locale. All use the same date: 4 July, 2001, 12:08:56 in the afternoon, Pacific Daylight Time.

Date and Time Pattern Result
yyyy.MM.dd G 'at' HH:mm:ss z 2001.07.04 AD at 12:08:56 PDT
EEE, MMM d, ''yy Wed, Jul 4, '01
h:mm a 12:08 PM
hh 'o''clock' a, zzzz 12 o'clock PM, Pacific Daylight Time
K:mm a, z 0:08 PM, PDT
yyyyy.MMMMM.dd GGG hh:mm aaa 02001.July.04 AD 12:08 PM
EEE, d MMM yyyy HH:mm:ss Z Wed, 4 Jul 2001 12:08:56 -0700
yyMMddHHmmssZ 010704120856-0700

A two-letter calendar specifier can come at the beginning of a date pattern and must have an uppercase letter first and a lowercase letter second. The following table lists the available calendars.

Table 3. Calendars
Calendar specifier Calendar
Bu Buddhist
Ch Chinese
Gr Gregorian
He Hebrew
Is Islamic
Ja Japanese

Compatibility

Table 4. Compatibility
Target Issue
Java No issues.
JavaScript
For dates, only the following symbols are valid:
  • yyyy for the 4-digit year
  • yy for the 2-digit year
  • MM for the 2-digit month
  • dd for the 2-digit day
  • Separators such as hyphens, slashes, and blanks
For timestamps, only the following symbols are valid:
  • HH for the 2-digit hour (0 to 23) in military time
  • hh for the 2-digit hour (1 to 12) mm for the 2-digit minute in the hour
  • ss for the 2-digit second in the minute
  • SSSSSS for a fractional second; specifically, a 3-digit millisecond followed by three zeros as a result of restrictions in JavaScript
  • a for AM or PM separators such as hyphens, slashes, and blanks