Using the TimeFormat Event Library

Internally, the correlator expresses time as seconds since the Unix epoch (1 Jan 1970, midnight UTC) - this is the form of currentTime and is convenient for performing arithmetic, such as differences between times. For more information on this variable, see currentTime.

To convert from string form to float form, use a parseTime method. To convert from float form to string form, use a format method. Both take a format String, which is a string which describes the string form of the time. For more information, see Format specification for the TimeFormat functions.

The parseTime method is available on the TimeFormat event directly. Or you can pre-compile a pattern and then perform parsing using the compiled pattern. A CompiledPattern object is obtained from the TimeFormat event using one of the compilePattern methods (depending on which time zone the pattern should use by default). The CompiledPattern object can be stored in a monitor variable, as an instance of an event or in a local variable and used by listeners. Re-using a CompiledPattern is more efficient than calling one of the TimeFormat.parseTime methods as the format String only needs to be read and compiled once. Calling parse on the TimeFormat event is equivalent to passing the same format String to generate a CompiledPattern and calling parse on that event. It is also possible to create multiple CompiledPattern events if your application needs to use several different formats for time.

For example, the following will behave the same:

There are also functions to obtain the current system time. It depends on whether your purpose is to measure the time intervals between two events on the same machine (getMicroTime()), or to identify when an event occurred in human terms or across machines (getSystemTime() or currentTime).

getSystemTime() provides an absolute time. Its purpose is to give an indication of the wall clock time rather than measuring time intervals. You would see a jump in the values if someone changed the time (for example, manually in the operating system or to synchronize with an NTP server). These jumps would be annoying if you were trying to measure latency of some operation. Whereas, if you use getMicroTime(), you would not see any effect from such a change to the operating system time.

getMicroTime() provides a high precision time, which is suitable for high precision relative times. The absolute value of getMicroTime() depends on the host operating system. Its main purpose is for measuring small durations of time. Unless you need such high precision, it is probably better to use currentTime or getSystemTime() instead.

The following table gives a brief overview of the different time functions:

	getMicroTime()	getSystemTime()	currentTime
Epoch	Undefined / determined by the operating system	Unix epoch (midnight 1 January 1970 UTC)	Unix epoch (midnight 1 January 1970 UTC)
Affected by the host operating system's automatic adjustment for daylight savings	No	No	No
Affected by a change to the host operating system's time zone	No	No	No
Affected by a manual change to the host operating system's time	No	Yes	Yes
Affected by the host operating system's automatic time synchronization	No	Yes	Yes
Represents a unique point in time	No	Yes, except for leap seconds	Yes, except for leap seconds
Precision	Microseconds	Milliseconds	Dependent on the correlator clock rate *
Remains constant while processing a single event	No	No	Yes
Use for date/time formatting	No	Yes	Yes

* See the documentation for the --frequency correlator command-line option (in Starting the correlator) and the timerFrequency YAML configuration option (in YAML configuration file for the correlator).

Patterns with textual elements operate by default in English, but will instead both produce output and expect input in another language if that has been set in the environment. For example, under Linux, if the correlator is running with the LC_ALL environment variable set to "fr_FR", the format "EEEE dd MMMM yyyy G" produces and expects "jeudi 01 janvier 1970 ap. J.-C." for time 0.0.

When you use the TimeFormat event library you can use the TZ environment variable to select a particular locale to be used by the event library. Specify the value in either of the following formats:

For example: TZ=Europe/London. The alternative shortened format will not work correctly. For example, TZ=GB will not be recognized. If you specify something like this, Coordinated Universal Time (UTC) is used instead.