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
`static String` `DEFAULT_INTERVAL_PATTERN` The default interval pattern
`static 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 and Description
`TmfTimestampFormat()` The default constructor (uses the default pattern)
`TmfTimestampFormat(String pattern)` The normal constructor
`TmfTimestampFormat(String pattern, TimeZone timeZone)` The full constructor
`TmfTimestampFormat(String pattern, TimeZone timeZone, Locale locale)` The fuller constructor
`TmfTimestampFormat(TmfTimestampFormat other)` The copy constructor

### Method Summary

All Methods Static Methods Instance Methods Concrete Methods
`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
`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 Detail

#### 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 Detail

#### TmfTimestampFormat

    public TmfTimestampFormat()

The default constructor (uses the default pattern)

#### TmfTimestampFormat

    public TmfTimestampFormat(String pattern)

The normal constructor

Parameters:
  `pattern` - the format pattern

#### TmfTimestampFormat

    public TmfTimestampFormat(String pattern,
                              TimeZone timeZone)

The full constructor

Parameters:
  `pattern` - the format pattern
  `timeZone` - the time zone

#### TmfTimestampFormat

    public TmfTimestampFormat(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 Detail

#### 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 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