com.apama.correlator.timeformat
Event TimeFormat
An event object providing a set of functions to assist with date and time formatting.
| Action summary |
com.apama.correlator.timeformat.CompiledPattern | static compilePattern(string format)
Returns a CompiledPattern object that can generate the time as a float value that corresponds to the local date/time string to be parsed. |
com.apama.correlator.timeformat.CompiledPattern | static compilePatternUTC(string format)
Returns a CompiledPattern object that can generate the time as a float value that corresponds to the UTC date/time string to be parsed. |
com.apama.correlator.timeformat.CompiledPattern | static compilePatternWithTimeZone(string format, string name)
Returns a CompiledPattern object that can generate the time as a float value that corresponds to the date/time string to be parsed, in the specified time zone. |
string | static format(float time, string format)
Converts the time parameter to the local time and returns that time in the format specified. |
string | static formatUTC(float time, string format)
Converts the time parameter to the local time and returns that time in the format specified. |
string | static formatWithTimeZone(float time, string format, string tzName)
Converts the time parameter, which is UTC, to the time in the time zone you specify and returns that time in the format you specify. |
float | static getMicroTime()
Returns a floating point (float) timestamp that represents the number of seconds since an unspecified epoch (a zero point). |
float | static getSystemTime()
Returns the local time as a float of seconds since the UNIX epoch (UTC). |
float | static parseTime(string format, string timeDate)
Parses the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting it as a date and time in the local time zone. |
float | static parseTimeUTC(string format, string timeDate)
Parses the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting the timeDate as a UTC date and time. |
float | static parseTimeWithTimeZone(string format, string timeDate, string tzName)
Parses the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting it as a date and time in the named time zone specified by the tzName parameter. |
compilePattern
com.apama.correlator.timeformat.CompiledPattern static compilePattern(string format)
Returns a CompiledPattern object that can generate the time as a float value that corresponds to the local date/time string to be parsed.
If the pattern and data contain a time zone specifier (eg zz or VV) then the time zone will be taken from the data and not the local time zone. In this case all the various compilePattern* actions will return the same value.
You can use the CompiledPattern object to make multiple calls using its parseTime() function, specifying the date/time string to be parsed. Reusing a CompiledPattern object is significantly more efficient than providing the same time pattern (format) in multiple calls to the parse functions defined on the TimeFormat event object.
Example:
The following example shows how you can use the CompiledPattern object returned by the compilePattern() function to make multiple calls using its parseTime() function:
TimeFormat timeFormat := new TimeFormat;
CompiledPattern timePattern := timeFormat.compilePattern(pattern);
t1:=timePattern.parseTime(time1);
t2:=timePattern.parseTime(time2);
t3:=timePattern.parseTime(time3);
When you call the compilePattern() function and then the CompiledPattern object's parseTime() function, the result is the same as calling one of the parse functions defined on the TimeFormat object itself. The advantage of calling the compilePattern() function and then the CompiledPattern object's parseTime() function is that it is faster. For example:
timeFormat.parseTime("yyyy.MM.dd G 'at' HH:mm:ss", "1996.07.10 AD at 15:08:56")
If you use this pattern many times, it is faster to call compilePattern() once at startup, and then use it to perform the parseTime operation, as follows:
action onload() { ... timePattern := timeFormat.compilePattern("yyyy.MM.dd G 'at' HH:mm:ss"); }
... timePattern.parseTime(c,"1996.07.10 AD at 15:08:56");
-
Parameters:
-
format - String that specifies a set of instructions for parsing a time/date object.
-
Returns:
- A CompiledPattern object that can generate the time as a float value that corresponds to the local date/time string to be parsed.
compilePatternUTC
com.apama.correlator.timeformat.CompiledPattern static compilePatternUTC(string format)
Returns a CompiledPattern object that can generate the time as a float value that corresponds to the UTC date/time string to be parsed.
If the pattern and data contain a time zone specifier (eg zz or VV) then the time zone will be taken from the data and not UTC. In this case all the various compilePattern* actions will return the same value.
You can use the CompiledPattern object to make multiple calls using its parseTime() function, specifying the date/time string to be parsed. Reusing a CompiledPattern object is significantly more efficient than providing the same time pattern (format) in multiple calls to the parse functions defined on the TimeFormat event object.
Example:
The following example shows how you can use the CompiledPattern object returned by the compilePatternUTC() function to make multiple calls using its parseTime() function:
TimeFormat timeFormat := new TimeFormat;
CompiledPattern timePattern := timeFormat.compilePatternUTC(pattern);
t1:=timePattern.parseTime(time1);
t2:=timePattern.parseTime(time2);
t3:=timePattern.parseTime(time3);
When you call the compilePatternUTC() function and then the CompiledPattern object's parseTime() function, the result is the same as calling one of the parse functions defined on the TimeFormat object itself. The advantage of calling the compilePatternUTC() function and then the CompiledPattern object's parseTime() function is that it is faster. For example:
timeFormat.parseTimeUTC("yyyy.MM.dd G 'at' HH:mm:ss", "1996.07.10 AD at 15:08:56")
If you use this pattern many times, it is faster to call compilePatternUTC() once at startup, and then use it to perform the parseTime operation, as follows:
action onload() { ... timePattern := timeFormat.compilePatternUTC("yyyy.MM.dd G 'at' HH:mm:ss"); }
... timePattern.parseTime(c,"1996.07.10 AD at 15:08:56");
-
Parameters:
-
format - String that specifies a set of instructions for parsing a time/date object.
-
Returns:
- A CompiledPattern object that can generate the time as a float value that corresponds to the UTC date/time string to be parsed.
compilePatternWithTimeZone
com.apama.correlator.timeformat.CompiledPattern static compilePatternWithTimeZone(string format, string name)
Returns a CompiledPattern object that can generate the time as a float value that corresponds to the date/time string to be parsed, in the specified time zone.
If the pattern and data contain a time zone specifier (eg zz or VV) then the time zone will be taken from the data and not the specified time zone. In this case all the various compilePattern* actions will return the same value.
You can then use the CompiledPattern object to make multiple calls using its parseTime() function, specifying the date/time string to be parsed. Reusing a CompiledPattern object is significantly more efficient than providing the same time pattern (format) in multiple calls to the parse functions defined on the TimeFormat event object.
Example:
The following example shows how you can use the CompiledPattern object returned by the compilePatternWithTimeZone() function to make multiple calls using its parseTime() function:
TimeFormat timeFormat := new TimeFormat;
CompiledPattern timePattern := timeFormat.compilePatternWithTimeZone(pattern, tzone);
t1:=timePattern.parseTime(time1);
t2:=timePattern.parseTime(time2);
t3:=timePattern.parseTime(time3);
When you call the compilePatternWithTimeZone() function and then the CompiledPattern object's parseTime() function, the result is the same as calling one of the parse functions defined on the TimeFormat object itself. The advantage of calling the compilePatternWithTimeZone() function and then the CompiledPattern object's parseTime() function is that it is faster. For example:
timeFormat.parseTimeWithTimeZone("yyyy.MM.dd G 'at' HH:mm:ss", "1996.07.10 AD at 15:08:56", "Europe/London");
If you use this pattern many times, it is faster to call compilePatternWithTimeZone() once at startup, and then use it to perform the parseTime operation, as follows:
action onload() { ... timePattern := timeFormat.compilePatternWithTimeZone("yyyy.MM.dd G 'at' HH:mm:ss", "Europe/London"); }
... timePattern.parseTime(c,"1996.07.10 AD at 15:08:56");
-
Parameters:
-
format - String that specifies a set of instructions for parsing a time/date object.
-
name - String that specifies the name of a time zone.
-
Returns:
- A CompiledPattern object that can generate the time as a float value that corresponds to the date/time string to be parsed, in the specified timezone.
format
string static format(float time, string format)
Converts the time parameter to the local time and returns that time in the format specified.
-
Parameters:
-
time - Float that indicates the time you want to format. This value is the number of seconds since the UNIX epoch in UTC. This is the same format used by the currentTime variable. For information about the currentTime variable, see "Getting the current time" in "Developing Apama Applications".
-
format - String that specifies the format that you want the returned time to have. For details about what you can specify for the format string, see "Format specification for the TimeFormat functions" in the documentation for "Developing Apama Applications".
-
Returns:
- A string representing the local time in the specified format.
formatUTC
string static formatUTC(float time, string format)
Converts the time parameter to the local time and returns that time in the format specified.
The formatUTC() function always returns UTC (GMT no matter what the local time is).
-
Parameters:
-
time - Float that indicates the time you want to format. This value is the number of seconds since the UNIX epoch in UTC. This is the same format used by the currentTime variable. For information about the currentTime variable, see "Getting the current time" in "Developing Apama Applications".
-
format - String that specifies the format that you want the returned time to have. For details about what you can specify for the format string, see "Format specification for the TimeFormat functions" in the documentation for "Developing Apama Applications".
-
Returns:
- A string representing the local time in the specified format.
formatWithTimeZone
string static formatWithTimeZone(float time, string format, string tzName)
Converts the time parameter, which is UTC, to the time in the time zone you specify and returns that time in the format you specify.
-
Parameters:
-
time - Float that indicates the time you want to format. This value is the number of seconds since the UNIX epoch in UTC. This is the same format used by the currentTime variable. For information about the currentTime variable, see "Getting the current time" in "Developing Apama Applications".
-
format - String that specifies the format that you want the returned time to have. For details about what you can specify for the format string, see "Format specification for the TimeFormat functions" in the documentation for "Developing Apama Applications".
-
tzName - String that specifies the name of a time zone.
-
Returns:
- A string representing the local time in the specified format.
getMicroTime
float static getMicroTime()
Returns a floating point (float) timestamp that represents the number of seconds since an unspecified epoch (a zero point).
The timestamp is accurate to one microsecond or better. The return value has no necessary relationship to wall time or correlator time and should be used only to compare similar timestamps.
Because the epoch is unspecified, you should use these timestamps in calculations only with other timestamps generated by the getMicroTime() function or with equivalent high-resolution timestamps generated by an Apama adapter.
For example, you might want to use high-resolution timestamps for calculating event processing latency in an Apama application. You can compare the timestamps across processes on the same machine. The timestamps are not comparable between different machines.
-
Returns:
- A floating point (float) timestamp that represents the number of seconds since an unspecified epoch (a zero point).
getSystemTime
float static getSystemTime()
Returns the local time as a float of seconds since the UNIX epoch (UTC).
This value has the same format as the currentTime variable. However, the getSystemTime() function returns the actual local time whereas the currentTime variable contains the time that the event being processed was received by the correlator. The time returned by the getSystemTime() function is accurate to the millisecond except on Windows. On Windows, it returns a time that is accurate to within 10 or 16 milliseconds depending on the machine configuration and Windows version it is running on.
The Windows and UNIX versions of the Time Format plug-in are not guaranteed to return the same time all the time. This is because the underlying system libraries that the plug-in relies on have different interpretations of what constitutes local time in certain country locales, in particular during summer time. This discrepancy is caused by the fact that at the epoch, January 1st 1970, Great Britain was temporarily one hour ahead of UTC. Some UNIX system libraries, like those on Solaris, account for this, others, like that on Windows, do not.
-
Returns:
- The local time as a float of seconds since the UNIX epoch (UTC).
parseTime
float static parseTime(string format, string timeDate)
Parses the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting it as a date and time in the local time zone.
If the pattern and data contain a time zone specifier (eg zz or VV) then the time zone will be taken from the data and not the local time zone. In this case all the various parseTime* actions will return the same value.
The function returns the resulting value as a float of seconds since the UNIX epoch, or NaN if it cannot parse the specified string.
e.g. float secsSinceEpoc := timeMgr.parseTime("yyyy.MM.dd G 'at' HH:mm:ss", "1996.07.10 AD at 15:08:56");
-
Parameters:
-
format - String that specifies the format of the value in the timeDate parameter. For details about what you can specify here, see "Format specification for the TimeFormat functions" in "Developing Apama Applications."
-
timeDate - String that contains the time you want to parse.
-
Returns:
- The resulting value of seconds since the UNIX epoch.
parseTimeUTC
float static parseTimeUTC(string format, string timeDate)
Parses the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting the timeDate as a UTC date and time.
If the pattern and data contain a time zone specifier (eg zz or VV) then the time zone will be taken from the data and not UTC. In this case all the various parseTime* actions will return the same value.
The returned value is a float of seconds since the UNIX epoch, or NaN if it cannot parse the specified string.
e.g. float secsSinceEpoc := timeMgr.parseTimeUTC("yyyy.MM.dd G 'at' HH:mm:ss", "1996.07.10 AD at 15:08:56");
-
Parameters:
-
format - String that specifies the format of the value in the timeDate parameter. For details about what you can specify here, see "Format specification for the TimeFormat functions" in "Developing Apama Applications."
-
timeDate - String that contains the time you want to parse.
-
Returns:
- The resulting value of seconds since the UNIX epoch.
parseTimeWithTimeZone
float static parseTimeWithTimeZone(string format, string timeDate, string tzName)
Parses the value contained by the timeDate parameter according to the format you specify in the format parameter, interpreting it as a date and time in the named time zone specified by the tzName parameter.
If the pattern and data contain a time zone specifier (eg zz or VV) then the time zone will be taken from the data and not the specified time zone. In this case all the various parseTime* actions will return the same value.
The function returns the resulting value as a float of seconds since the UNIX epoch, or NaN if it cannot parse the specified string.
e.g. float secsSinceEpoc := timeMgr.parseTimeWithTimeZone("yyyy.MM.dd G 'at' HH:mm:ss", "1996.07.10 AD at 15:08:56", "Europe/London");
-
Parameters:
-
format - String that specifies the format of the value in the timeDate parameter. For details about what you can specify here, see "Format specification for the TimeFormat functions" in "Developing Apama Applications."
-
timeDate - String that contains the time you want to parse.
-
tzName - String that specifies the name of a time zone.
-
Returns:
- The resulting value of seconds since the UNIX epoch.