Package org.eclipse.tracecompass.tmf.core.timestamp

Class TmfTimestampFormat

java.lang.Object

java.text.Format

java.text.DateFormat

java.text.SimpleDateFormat

org.eclipse.tracecompass.tmf.core.timestamp.TmfTimestampFormat

All Implemented Interfaces:

Serializable, Cloneable

public class TmfTimestampFormat
extends SimpleDateFormat

A formatting and parsing facility that can handle timestamps that span the epoch with a precision down to the nanosecond. It can be understood as an extension of SimpleDateFormat that supports seconds since the epoch (Jan 1, 1970, 00:00:00 GMT), additional sub-second patterns and optional delimiters.

The timestamp representation is broken down into a number of optional components that can be assembled into a fairly simple way.

Date and Time Patterns

All date and time pattern letters defined in SimpleDateFormat are supported with the following exceptions:

Format	Description	Value Range	Example
T	The seconds since the epoch	0-9223372036	1332170682
Td	The deciseconds since the epoch	0-92233720368	13321706825
Tc	The centiseconds since the epoch	0-922337203685	133217068253
Tm	The milliseconds since the epoch	0-9223372036854	1332170682539
Tu	The microseconds since the epoch	0-9223372036854775	1332170682539677
Tn	The nanoseconds since the epoch	0-9223372036854775807	1332170682539677389
S	Millisecond	N/A	Not supported
W	Week in month	N/A	Not supported

Note: When parsing, if "T" is used, no other Date and Time pattern letter will be interpreted and the entire pre-delimiter input string will be parsed as a number. Also, "T" should be used for time intervals.

Note: The decimal separator between the Date and Time pattern and the Sub-Seconds pattern is mandatory (if there is a fractional part) and must be one of the sub-second delimiters. Date and Time pattern letters are not interpreted after the decimal separator.

Sub-Seconds Patterns

Format	Description	Value Range	Example
S	Fraction of second (or unit of second)	0-999999999	123456789
C	Microseconds in ms	0-999	456
N	Nanoseconds in µs	0-999	789

Note: The fraction of second pattern can be split, in which case parsing and formatting continues at the next digit. Digits beyond the total number of pattern letters are ignored when parsing and truncated when formatting.

Note: When parsing, "S", "C" and "N" are interchangeable and are all handled as fraction of second ("S"). The use of "C" and "N" is discouraged but is supported for backward compatibility.

The recognized sub-second delimiters are:

• Space (" ")
• Period (".")
• Comma (",")
• Dash ("-")
• Underline ("_")
• Colon (":")
• Semicolon (";")
• Slash ("/")
• Single-quote ("''")
• Double-quote (""")

Note: When parsing, sub-second delimiters are optional if unquoted. However, an extra delimiter or any other unexpected character in the input string ends the parsing of digits. All other quoted or unquoted characters in the sub-second pattern are matched against the input string.

Examples

The following examples show how timestamp patterns are interpreted in the U.S. locale. The given timestamp is 1332170682539677389L, the number of nanoseconds since 1970/01/01.

Date and Time Pattern	Result
"yyyy-MM-dd HH:mm:ss.SSS.SSS.SSS"	2012-03-19 11:24:42.539.677.389
"yyyy-MM-dd HH:mm:ss.SSS.SSS"	2012-03-19 11:24:42.539.677
"yyyy-D HH:mm:ss.SSS.SSS"	2012-79 11:24:42.539.677
"ss,SSSS"	42,5397
"T.SSS SSS SSS"	1332170682.539 677 389
"T"	1332170682
"Tm.SSSSSS"	1332170682539.677389
"Tn"	1332170682539677389

Author:

Francois Chouinard

See Also:

• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class java.text.DateFormat

DateFormat.Field

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_INTERVAL_PATTERN	The default interval pattern
static final String	DEFAULT_TIME_PATTERN	The default timestamp pattern

Fields inherited from class java.text.DateFormat

AM_PM_FIELD, DATE_FIELD, DAY_OF_WEEK_FIELD, DAY_OF_WEEK_IN_MONTH_FIELD, DAY_OF_YEAR_FIELD, DEFAULT, ERA_FIELD, FULL, HOUR_OF_DAY0_FIELD, HOUR_OF_DAY1_FIELD, HOUR0_FIELD, HOUR1_FIELD, LONG, MEDIUM, MILLISECOND_FIELD, MINUTE_FIELD, MONTH_FIELD, SECOND_FIELD, SHORT, TIMEZONE_FIELD, WEEK_OF_MONTH_FIELD, WEEK_OF_YEAR_FIELD, YEAR_FIELD

Constructor Summary

Constructors

Constructor	Description
TmfTimestampFormat()	The default constructor (uses the default pattern)
TmfTimestampFormat(@NonNull String pattern)	The normal constructor
TmfTimestampFormat(@NonNull String pattern, TimeZone timeZone)	The full constructor
TmfTimestampFormat(@NonNull String pattern, TimeZone timeZone, Locale locale)	The fuller constructor
TmfTimestampFormat(TmfTimestampFormat other)	The copy constructor

Method Summary

Modifier and Type	Method	Description
void	applyPattern(String pattern)
String	format(long value)	Format the timestamp according to its pattern.
static TmfTimestampFormat	getDefaulIntervalFormat()
static TmfTimestampFormat	getDefaulTimeFormat()
long	parseValue(String source)	Parse a string according to the format pattern
long	parseValue(String source, long ref)	Parse a string according to the format pattern
@NonNull String	toPattern()
static void	updateDefaultFormats()	Update the default time and default interval formats

Methods inherited from class java.text.SimpleDateFormat

applyLocalizedPattern, clone, equals, format, formatToCharacterIterator, get2DigitYearStart, getDateFormatSymbols, hashCode, parse, set2DigitYearStart, setDateFormatSymbols, toLocalizedPattern

Methods inherited from class java.text.DateFormat

format, format, getAvailableLocales, getCalendar, getDateInstance, getDateInstance, getDateInstance, getDateTimeInstance, getDateTimeInstance, getDateTimeInstance, getInstance, getNumberFormat, getTimeInstance, getTimeInstance, getTimeInstance, getTimeZone, isLenient, parse, parseObject, setCalendar, setLenient, setNumberFormat, setTimeZone

Methods inherited from class java.text.Format

format, parseObject

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Field Details

DEFAULT_TIME_PATTERN

public static final String DEFAULT_TIME_PATTERN

The default timestamp pattern

See Also:

• Constant Field Values

DEFAULT_INTERVAL_PATTERN

public static final String DEFAULT_INTERVAL_PATTERN

The default interval pattern

See Also:

• Constant Field Values

Constructor Details

TmfTimestampFormat

public TmfTimestampFormat()

The default constructor (uses the default pattern)

TmfTimestampFormat

public TmfTimestampFormat(@NonNull String pattern)

The normal constructor

Parameters:

pattern - the format pattern

TmfTimestampFormat

public TmfTimestampFormat(@NonNull String pattern,
 TimeZone timeZone)

The full constructor

Parameters:

pattern - the format pattern

timeZone - the time zone

TmfTimestampFormat

public TmfTimestampFormat(@NonNull String pattern,
 TimeZone timeZone,
 Locale locale)

The fuller constructor

Parameters:

pattern - the format pattern

timeZone - the time zone

locale - the locale

TmfTimestampFormat

public TmfTimestampFormat(TmfTimestampFormat other)

The copy constructor

Parameters:

other - the other format pattern

Method Details

updateDefaultFormats

public static void updateDefaultFormats()

Update the default time and default interval formats

getDefaulTimeFormat

public static TmfTimestampFormat getDefaulTimeFormat()

Returns:

the default time format pattern

getDefaulIntervalFormat

public static TmfTimestampFormat getDefaulIntervalFormat()

Returns:

the default interval format pattern

applyPattern

public void applyPattern(String pattern)

Overrides:

applyPattern in class SimpleDateFormat

toPattern

public @NonNull String toPattern()

Overrides:

toPattern in class SimpleDateFormat

format

public String format(long value)

Format the timestamp according to its pattern.

Parameters:

value - the timestamp value to format (in ns)

Returns:

the formatted timestamp

parseValue

public long parseValue(String source,
 long ref)
                throws ParseException

Parse a string according to the format pattern

Parameters:

source - the source string

ref - the reference (base) time (in ns)

Returns:

the parsed value (in ns)

Throws:

ParseException - if the string has an invalid format

parseValue

public long parseValue(String source)
                throws ParseException

Parse a string according to the format pattern

Parameters:

source - the source string

Returns:

the parsed value (in ns)

Throws:

ParseException - if the string has an invalid format