String-based patterns (masks)

In JBCL components, the pattern syntax for all edit masks, display masks, and import/export masks, and for parsing such masks, is a direct extension of that used by the format classes in the java.text package. There are separate patterns and symbols for numeric data, date/time data, text data and boolean data (see borland.jbcl.util.BooleanFormat).

Some of these symbols, such as the braces to indicate optional portions, are additions to the JDK. The JBCL classes ensure that such extensions are never sent to the JDK classes (which would not understand them). The extensions are used and then stripped from the pattern.

Note: For ease of use, the symbol definitions are designed to be compatible with those in Borland's Delphi product. In those cases where Visual Basic is different from, but not incompatible with Delphi, those symbols are defined as well.


Numeric data patterns

A numeric pattern consists of two formats, separated by a semicolon. The second pattern, when present, determines how negative numbers are formatted and displayed.

To format the display or editing of a numeric data, use the symbols in the tables below.


JDK standard numeric format symbols

Symbol Meaning Notes
0 In an edit pattern, a required digit
In a display pattern, indicates that leading zeroes are displayed.
# In an edit pattern, an optional digit
In a display pattern, indicates that leading zeroes do not display.
.
(period)
Placeholder for the decimal separator. This is not necessarily the actual character displayed as the separator. That is determined by your Locale.
,
(comma)
Placeholder for the grouping (thousands) separator, showing the grouping to be used. This is not necessarily the actual character displayed as the separator. That is determined by your Locale.
;
(semicolon)
Format separator. Place a semicolon between the format pattern for a positive number (first) and the pattern for a negative number (second).
% Divide entry by 100 and show as a percentage.
-
(hyphen)
A leading minus sign appears for negative numbers. Do not use together with parentheses.
() The entire expression is enclosed in parentheses to show that it is negative, for example: ($#,###.##). Do not use together with the hyphen.
\nnnn Single character literal. Enter the octal, hexidecimal, or Unicode number for the desired character. This symbol escapes even out of single quotes.


JBCL additional numeric format symbols

Symbol Meaning Notes
{} Use to bracket optional portions of the pattern. Entering ####.{##} allows the user to choose whether to enter the decimal fraction.
^
(carat)
Sets the initial cursor position when editing.
'
(single quote)
Enclose text constants. This method of including constants is preferred to the other symbol styles, as being more reliable. 'Lira' yields the words "Lira" in the data.


Date/time data patterns

To format the display or editing of a date or timestamp data, use the symbols in the tables that follow.


JDK standard date/time format symbols

Symbol Meaning Presentation
G Era designator. A "G" in the pattern yields AD.
y Year. Enter four "y"s to format to all four digits of the year. Enter "y" or "yy" to yield the last two digits of the year. yyyy yields 1996
yy yields 96.
M The month of the year. "M" yields the number of the month (February would be 2).
"MM" yields the number of the month, but single digits have leading zeroes (02).
"MMM" yields the abbreviation of the month (Feb).
"MMMM" yields the full name of the month (February).
d The day of the month. For Christmas Day, entering:
"d" yields 25
"dd" yields 25
"ddd" yields 025
"dddd" yields 0025.
h The hour in the day, using a 12-hour clock. 1 through 12
H The hour in the day, using a 24-hour clock. 0 through 23
m The minute in the hour. 1 through 59
s The second in the minute. 1 through 59
S The millisecond. 1 through 999
E The day in the week. "EEEE" yields the full name of the day, e.g., Tuesday.
"EEE" (or fewer) yields the abbreviation, e.g., Tues.
D The day in the year, as a Julian date (number). July 7 would be 189.
F The ordinal of the day of the week in the month. For example, the second Tuesday in July. For January 7, 1997, entering:
"F" yields 1
"FF" yields 01
"FFF" yields 001
"FFFF" yields 0001.
w The week in the year, as a number.
W The week in the month.
a Marker for am/pm. For 1600 hours, displays 8:00 pm.
k The hour in the day, using a 24-hour clock. 1 through 24
K The hour in the day, using a 12 hour clock. 0 through 11
z Time zone Entering one through three "z"s yields the abbreviation (PST)
Entering four "z"s yields the completely spelled out time zone (Pacific Standard Time).
'
(single quote)
Enclose text constants. This method of including constants is preferred of the other symbol styles, as being more reliable. 'Area Code' yields the words "Area Code" in the data.
''
(two single quotes)
Indicates a literal single quote as a part of a text constant.
\nnnn Single character literal. Enter the octal, hexidecimal, or Unicode number for the desired character. This symbol escapes even out of single quotes.


JBCL additional date/time format symbols

Symbol Meaning Presentation
{} Use to bracket optional portions of the pattern.
^
(carat)
Sets the initial cursor position when editing.


Text data patterns

Patterns for formatting and editing text datas are specific to JBCL classes. They consist of up to four parts, separated by semicolons. Only the first part is required. To include an optional third part, but not the second or fourth, enter the semicolons for each part. The parts include
  1. The actual edit or display mask.
  2. A zero or one (0 or 1), indicating whether literals should be stripped before posting information to a database. Zero indicates the literals should be stripped. If this part is omitted, literals are not stripped.
  3. The character to use as a "blank" indicator. This character indicates the spaces to be filled in the data. If this part is omitted, the underscore character is used.
  4. The character to be used to replace blank positions on output. If this part of the mask is omitted, blank positions are stripped.
To format the display or editing of a text data, use the symbols in the following table for thefirst part of the pattern.


JBCL text data format symbols

Symbol Meaning
0 A digit. 0 -9, entry required. Plus (+) and minus (-) signs not allowed.
9 A digit. 0 -9, entry optional. A space, plus (+) and minus (-) signs are not allowed.
# A digit or space, entry optional. Blank positions are converted to spaces. Plus (+) and minus (-) signs allowed.
L A letter. A through Z, entry required.
l A letter. A through Z, entry optional.
? A letter. A through Z, entry optional.
A A letter or digit, entry required.
a A letter or digit, entry optional.
C A character or space, entry required.
c A character or space, entry optional.
& A character or space, entry required.
< Converts the characters that follow to lower case.
> Converts the characters that follow to upper case.
! For an edit mask, makes the data fill from right to left, rather than from left to right, when characters to the left are optional. Can be placed anywhere in the edit mask.
\ Causes the character immediately following the back slash to be displayed as a literal. Use to display any of the syntax symbol characters.
\nnnn Single character literal. Enter the octal, hexidecimal, or Unicode number for the desired character. This symbol escapes even out of single quotes.
'
(single quote)
Enclose character constants. For example, "990' units sold' " should display as "27 units sold".
* Enclose a password encrypted string. For example, "*AAAAaaaa* describes a password of at least four, and at most eight alphanumeric characters. They echo as "*" as they are entered.
{} Enclose optional portions of a pattern.
^
(carat)
Sets the initial cursor position when editing.