uk.ac.starlink.table

## Class TimeMapper

- java.lang.Object
- - uk.ac.starlink.table.TimeMapper

- All Implemented Interfaces:
    DomainMapper

      public abstract class TimeMapper
      extends java.lang.Object
      implements DomainMapper

  DomainMapper for mapping values to epochs in a common time scale.
  Since:
    12 Aug 2013

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static TimeMapper` | `DECIMAL_YEAR` Mapper for numeric values in decimal year (since 0 AD).
    `static TimeMapper` | `ISO_8601` Mapper for ISO-8601 strings.
    `static TimeMapper` | `JD` Mapper for numeric values in Julian Day.
    `static TimeMapper` | `MJD` Mapper for numeric values in Modified Julian Date.
    `static TimeMapper` | `UNIX_SECONDS` Mapper for numeric values (already) in unix seconds.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `TimeMapper(java.lang.Class<?> sourceClass, java.lang.String sourceName, java.lang.String sourceDescription)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Class<?>` | `getSourceClass()` Returns the type of values from which this mapper instance can convert.
    `java.lang.String` | `getSourceDescription()` Returns a description of the type of source values which this mapper can convert from.
    `java.lang.String` | `getSourceName()` Returns a short name for the type of source values which this mapper can convert from.
    `TimeDomain` | `getTargetDomain()` Returns `TimeDomain.INSTANCE`.
    `static TimeMapper[]` | `getTimeMappers()` Returns a selection of time mapper instances.
    `double` | `toJd(java.lang.Object sourceValue)` Maps a source value to Julian Day.
    `java.lang.String` | `toString()`
    `abstract double` | `toUnixSeconds(java.lang.Object sourceValue)` Maps a source value to time in seconds since the Unix epoch (1970-01-01T00:00:00).

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### DECIMAL_YEAR

          public static final TimeMapper DECIMAL_YEAR

      Mapper for numeric values in decimal year (since 0 AD).

    - #### MJD

          public static final TimeMapper MJD

      Mapper for numeric values in Modified Julian Date.

    - #### JD

          public static final TimeMapper JD

      Mapper for numeric values in Julian Day.

    - #### UNIX_SECONDS

          public static final TimeMapper UNIX_SECONDS

      Mapper for numeric values (already) in unix seconds.

    - #### ISO_8601

          public static final TimeMapper ISO_8601

      Mapper for ISO-8601 strings.

  - ### Constructor Detail

    - #### TimeMapper

          protected TimeMapper(java.lang.Class<?> sourceClass,
                               java.lang.String sourceName,
                               java.lang.String sourceDescription)

      Constructor.
      Parameters:
        `sourceClass` - source class
        `sourceName` - source type name
        `sourceDescription` - source type description

  - ### Method Detail

    - #### getTargetDomain

          public TimeDomain getTargetDomain()

      Returns `TimeDomain.INSTANCE`.
      Specified by:
        `getTargetDomain` in interface `DomainMapper`
      Returns:
        domain identifier

    - #### getSourceClass

          public java.lang.Class<?> getSourceClass()

      Description copied from interface: `DomainMapper`
      Returns the type of values from which this mapper instance can convert. This should be as specific as possible to cover all the possible options, but in some cases that may mean it has simply to return `Object.class`.
      Specified by:
        `getSourceClass` in interface `DomainMapper`
      Returns:
        class of mappable source objects to which this mapper can be applied

    - #### getSourceName

          public java.lang.String getSourceName()

      Description copied from interface: `DomainMapper`
      Returns a short name for the type of source values which this mapper can convert from.
      Specified by:
        `getSourceName` in interface `DomainMapper`
      Returns:
        mapper source type name

    - #### getSourceDescription

          public java.lang.String getSourceDescription()

      Description copied from interface: `DomainMapper`
      Returns a description of the type of source values which this mapper can convert from.
      Specified by:
        `getSourceDescription` in interface `DomainMapper`
      Returns:
        mapper source type description

    - #### toUnixSeconds

          public abstract double toUnixSeconds(java.lang.Object sourceValue)

      Maps a source value to time in seconds since the Unix epoch (1970-01-01T00:00:00). The time scale is generally assumed to be UTC, though conversions may not always be performed, for instance for values in which the intended time scale is not obvious.

      A java (IEEE 754) double has 52+1 bits of precision, which I make 52*ln(2)/ln(10)=15.65 decimal places, and a year contains 3.15e7 seconds, which gives you the following precisions:

      - epoch +/- 1.7 months: 1 nanosecond precision
      - epoch +/- 140 years: 1 microsecond precision
      - epoch +/- 140 kyears: 1 millisecond precision
      - epoch +/- 140 Myears: 1 second precision
      That means around microsecond precision for values near the current epoch (unless this software proves more long lasting than I anticipate). It should be OK for most purposes.
      Parameters:
        `sourceValue` - value in source domain
      Returns:
        number of seconds since midnight 1 Jan 1970

    - #### toJd

          public double toJd(java.lang.Object sourceValue)

      Maps a source value to Julian Day.

      This simply calls `toUnixSeconds` and converts the result.

      Parameters:
        `sourceValue` - value in source domain
      Returns:
        number of days the Julian Epoch

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getTimeMappers

          public static TimeMapper[] getTimeMappers()

      Returns a selection of time mapper instances.