TmfTimestampFormat
Date: 2016-06-06

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 and Description
    --- | ---
    `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
    Modifier and Type | Method and 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
    `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