Apama Documentation : Developing Apama Applications : Developing Apama Applications in EPL : Using Correlator Plug-ins in EPL : Using the TimeFormat Event Library : Format specification for the TimeFormat functions
Format specification for the TimeFormat functions
The format and parse functions make use of the SimpleDateFormat class provided in the International Components for Unicode libraries. SimpleDateFormat is a class for formatting and parsing dates in a language-independent manner.
Pattern letters in format strings
The TimeFormat functions use the SimpleDateFormat class to transform between a string that contains a time and/or date and a normalized representation of that time and/or date. In this case, the normalized representation is the number of seconds since the epoch.
For the operation to succeed, it is important to define the format string so that it exactly represents the format of the time and/or date you provide as a string in the timeDate parameter to a parse function, or expect to be returned from a format function. You specify the format as a time pattern. In this pattern, all ASCII letters are reserved as pattern letters.
The number of pattern letters determines the format as follows:
*For pattern letters that represent text
*If you specify four or more letters, the SimpleDataFormat class transforms the full form. For example, EEEE formats/parses Monday.
*If you specify fewer than four letters, the SimpleDataFormat class transforms the short or abbreviated form if it exists. For example, E, EE, and EEE each formats/parses Mon.
*For pattern letters that represent numbers
*Specify the minimum number of digits.
*If necessary, SimpleDateFormat prepends zeros to shorter numbers to equal the number of digits you specify. For example, m formats/parses 6, mm formats/parses 06.
*Year is handled specially. If the count of y is 2, the year is truncated to 2 digits. For example, yyyy formats/parses 1997, while yy formats/parses 97.
*Unlike other fields, fractional seconds are padded on the right with zeros.
*For pattern letters that can represent text or numbers
*If you specify three or more letters, the SimpleDataFormat class transforms text. For example, MMM formats/parses Jan, while MMMM formats/parses January.
*If you specify one or two letters, the SimpleDataFormat class transforms a number. For example, M formats/parses 1, and MM formats/parses for 01.
The following table provides the meaning of each letter you can specify in a pattern. After the table, there are a number of combined examples.
Descriptions of pattern letters in format strings:
Symbol
Meaning
Presentation
Example
Sample Result
G
Era designator
Text
G
G
AD
BC
y (lowercase)
Year
Number
yy
yyyy
96
1996
Y (uppercase)
Year for indicating which week of the year. Use with the w symbol. See "Week in year" later in this table.
Number
See example for "Week in year".
u
Extended year
Number
uuuu
5769
M
Month in year
Text or Number
M
MM
MMM
MMMM
9
09
Sep
September
d
Day in month
Number
d
dd
dd
7
07
25
h
Hour in AM or PM (1-12)
Number
hh
05
H
Hour in day (0-23)
Number
H
HH
HH
0
05
14
m
Minute in hour
Number
m
mm
mm
3
03
55
s
Second in minute
Number
s
ss
ss
5
05
59
S
Fractional second
Number
S
SS
SSS
2
20
200
E
Day of week
Text
E
EE
EEE
EEEE
Fri
Fri
Fri
Friday
e
Day of week (1-7)
This is locale dependent. Typically, Monday is 1.
Number
e
4
D
Day in year
Number
D
DD
DDD
DDD
7
07
007
123
F
Day of particular week in month (1-7). Use with W (uppercase) for week in month. See "Week in month" later in this table.
Number
See example for "Week in month".
w (lowercase)
Week in year. Use with uppercase Y.
The week that contains January 1st is week 1.
For example, if a week starts on Monday and ends on Sunday, and if January 1st is a Sunday, then week 1 contains December 26 - 31 plus January 1.
Number
The first example below uses uppercase Y. The second example shows the difference when you use lowercase y.
"'Week' w YYYY"
"'Week' w yyyy"
Suppose you are transforming December 31st, 2008, which is a Wednesday.
"Week 1 2009"
"Week 1 2008"
W (uppercase)
Week in month.
The week that contains the 1st of the month is week 1.
For example, if a week starts on Monday and ends on Sunday, and if July 1 is a Friday (5), then week 1 of July contains June 27 - 30 and July 1 - 3.
Number
"'Day' F 'of Week' W"
"Day 2 of Week 3"
a
AM/PM marker
Text
a
a
AM
PM
k
Hour in day (1-24)
Number
k
kk
kk
1
01
24
K
Hour in AM/PM (0-11)
Number
K
KK
KK
0
07
11
z
Time zone
Text
z
Pacific Standard Time
Z
Time zone (RFC 822)
Number
Z
-0800
v
Generic time zone
Text
v
Pacific Time
V
Time zone abbreviation
Text
V
PT
VVVV
Time zone location
Text
VVVV
United States (Los Angeles)
g
Julian day
Number
g
2451334
A
Milliseconds in day
Number
A
69540000
'
Escape for text
Delimiter
"'Week' w YYYY"
"Week 1 2009"
''
Single quote
Literal
"KK 'o''clock'"
"11 o'clock"
Any character in the format pattern that is not in the range of ['a'..'z'] or ['A'..'Z'] is treated as quoted text. For example, the following characters can be in a timeDate string without being enclosed in quotation marks:
:
.
,
#
@
A pattern that contains an invalid pattern letter results in a -1 return value.
The following table gives examples that assume the US locale:
Format pattern
Suitable timeDate string
yyyy.MM.dd G 'at' HH:mm:ss z
1996.07.10 AD at 15:08:56 PDT
EEE, MMM d, ''yy
Wed, July 10, '96
h:mm a
12:08 PM
hh 'o''clock' a, zzzz
12 o'clock PM, Pacific Daylight Time
K:mm a, z
0:00 PM, PST
yyyyy.MMMMM.dd GGG hh:mm aaa
1996.July.10 AD 12:08 PM
When parsing a date string using the abbreviated year pattern (y or yy), SimpleDateFormat (and hence all parse functions) must interpret the abbreviated year relative to some century. It does this by adjusting dates to be within 79 years before and 19 years after the time the SimpleDateFormat instance is created. For example, using a pattern of MM/dd/yy and a SimpleDateFormat instance created on Jan 1, 1997, the string 01/11/12 would be interpreted as Jan 11, 2012 while the string 05/04/64 would be interpreted as May 4, 1964. During parsing, only strings consisting of exactly two digits, as defined by Unicode::isDigit(), will be parsed into the default century. Any other numeric string, such as a one digit string, a three or more digit string, or a two digit string that is not all digits (for example, -1), is interpreted literally. So 01/02/3 or 01/02/003 are parsed, using the same pattern, as Jan 2, 3 A.D. Likewise, 01/02/-3 is parsed as Jan 2, 4 B.C. Behavior is undefined if you specify a two-digit date that might be either twenty years in the future or eighty years in the past.
If the year pattern has more than two y characters, the year is interpreted literally, regardless of the number of digits. So using the pattern MM/dd/yyyy, 01/11/12 parses to Jan 11, 12 A.D.
When numeric fields abut one another directly, with no intervening delimiter characters, they constitute a run of abutting numeric fields. Such runs are parsed specially. For example, the format HHmmss parses the input text 123456 to 12:34:56, parses the input text 12345 to 1:23:45, and fails to parse 1234. In other words, the leftmost field of the run is flexible, while the others keep a fixed width. If the parse fails anywhere in the run, then the leftmost field is shortened by one character, and the entire run is parsed again. This is repeated until either the parse succeeds or the leftmost field is one character in length. If the parse still fails at that point, the parse of the run fails.
For time zones that have no names, SimpleDateFormat uses strings GMT+hours:minutes or GMT-hours:minutes.
The calendar defines what is the first day of the week, the first week of the year, whether hours are zero based or not (0 vs. 12 or 24), and the time zone. There is one common number format to handle all the numbers; the digit count is handled programmatically according to the pattern.
Midnight and noon
The format "HH:mm" parses "24:00" as midnight that ends the day. Given the formal "hh:mm a", both "00:00 am" and "12:00 am" parse as the midnight that begins the day. Note that "00:00 pm" and "12:00 pm" are both midday.
Copyright © 2013-2016 Software AG, Darmstadt, Germany.

Product LogoContact Support   |   Community   |   Feedback