Class Times

java.lang.Object
uk.ac.starlink.ttools.func.Times

public class Times extends Object
Functions for conversion of time values between various forms. The forms used are
Modified Julian Date (MJD)

A continuous measure in days since midnight at the start of 17 November 1858. Based on UTC.

Julian Day (JD)

MJD plus a fixed offset of 2400000.5. The number of days since the notional creation of the universe, midday on 1 Jan 4713 BC.

ISO 8601

A string representation of the form yyyy-mm-ddThh:mm:ss.s, where the T is a literal character (a space character may be used instead). Based on UTC.

Julian Epoch

A continuous measure based on a Julian year of exactly 365.25 days. For approximate purposes this resembles the fractional number of years AD represented by the date. Sometimes (but not here) represented by prefixing a 'J'; J2000.0 is defined as 2000 January 1.5 in the TT timescale.

Besselian Epoch

A continuous measure based on a tropical year of about 365.2422 days. For approximate purposes this resembles the fractional number of years AD represented by the date. Sometimes (but not here) represented by prefixing a 'B'.

Decimal Year

Fractional number of years AD represented by the date. 2000.0, or equivalently 1999.99recurring, is midnight at the start of the first of January 2000. Because of leap years, the size of a unit depends on what year it is in.

Therefore midday on the 25th of October 2004 is 2004-10-25T12:00:00 in ISO 8601 format, 53303.5 as an MJD value, 2004.81588 as a Julian Epoch and 2004.81726 as a Besselian Epoch.

Currently this implementation cannot be relied upon to better than a millisecond.

Since:
2 Jun 2005
Author:
Mark Taylor (Starlink)
See Also:
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final double
    JD value for MJD = 0 (=2400000.5).
  • Method Summary

    Modifier and Type
    Method
    Description
    static double
    besselianToMjd(double besselianEpoch)
    Converts Besselian Epoch to Modified Julian Date.
    static double
    dateToMjd(int year, int month, int day)
    Converts a calendar date to Modified Julian Date.
    static double
    dateToMjd(int year, int month, int day, int hour, int min, double sec)
    Converts a calendar date and time to Modified Julian Date.
    static double
    decYearToMjd(double decYear)
    Converts a Decimal Year to a Modified Julian Date.
    static double
    decYearToUnixSec(double decYear)
    Converts a Decimal Year to seconds since 1970-01-01.
    static String
    formatMjd(double mjd, String format)
    Converts a Modified Julian Date value to a date using a customisable date format.
    static double
    isoToMjd(String isoDate)
    Converts an ISO8601 date string to Modified Julian Date.
    static double
    Converts an ISO8601 date string to seconds since 1970-01-01.
    static double
    jdToMjd(double jd)
    Converts a Julian Day to Modified Julian Date.
    static double
    jdToUnixSec(double jd)
    Converts a Julian day to seconds since 1970-01-01.
    static double
    julianToMjd(double julianEpoch)
    Converts a Julian Epoch to Modified Julian Date.
    static double
    mjdToBesselian(double mjd)
    Converts Modified Julian Date to Besselian Epoch.
    static String
    mjdToDate(double mjd)
    Converts a Modified Julian Date value to an ISO 8601-format date string.
    static double
    mjdToDecYear(double mjd)
    Converts a Modified Julian Date to Decimal Year.
    static String
    mjdToIso(double mjd)
    Converts a Modified Julian Date value to an ISO 8601-format date-time string.
    static double
    mjdToJd(double mjd)
    Converts a Modified Julian Date to Julian Day.
    static double
    mjdToJulian(double mjd)
    Converts a Modified Julian Date to Julian Epoch.
    static String
    mjdToTime(double mjd)
    Converts a Modified Julian Date value to an ISO 8601-format time-only string.
    static long
    mjdToUnixMillis(double mjd)
    Converts from modified Julian date to milliseconds since the Unix epoch (1970-01-01T00:00:00).
    static double
    mjdToUnixSec(double mjd)
    Converts a Modified Julian Date to seconds since 1970-01-01.
    static double
    unixMillisToMjd(long unixMillis)
    Converts from milliseconds since the Unix epoch (1970-01-01T00:00:00) to a modified Julian date value

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • MJD_OFFSET

      public static final double MJD_OFFSET
      JD value for MJD = 0 (=2400000.5).
      See Also:
  • Method Details

    • isoToMjd

      public static double isoToMjd(String isoDate)
      Converts an ISO8601 date string to Modified Julian Date. The basic format of the isoDate argument is yyyy-mm-ddThh:mm:ss.s, though some deviations from this form are permitted:
      • The 'T' which separates date from time can be replaced by a space
      • The seconds, minutes and/or hours can be omitted
      • The decimal part of the seconds can be any length, and is optional
      • A 'Z' (which indicates UTC) may be appended to the time
      Some legal examples are therefore: "1994-12-21T14:18:23.2", "1968-01-14", and "2112-05-25 16:45Z".
      Parameters:
      isoDate - date in ISO 8601 format
      Returns:
      modified Julian date corresponding to isoDate
      Examples:
      isoToMjd("2004-10-25T18:00:00") = 53303.75, isoToMjd("1970-01-01") = 40587.0
    • dateToMjd

      public static double dateToMjd(int year, int month, int day, int hour, int min, double sec)
      Converts a calendar date and time to Modified Julian Date.
      Parameters:
      year - year AD
      month - index of month; January is 1, December is 12
      day - day of month (the first day is 1)
      hour - hour (0-23)
      min - minute (0-59)
      sec - second (0<=sec<60)
      Returns:
      modified Julian date corresponding to arguments
      Examples:
      dateToMjd(1999, 12, 31, 23, 59, 59.) = 51543.99998
    • dateToMjd

      public static double dateToMjd(int year, int month, int day)
      Converts a calendar date to Modified Julian Date.
      Parameters:
      year - year AD
      month - index of month; January is 1, December is 12
      day - day of month (the first day is 1)
      Returns:
      modified Julian date corresponding to 00:00:00 of the date specified by the arguments
      Examples:
      dateToMjd(1999, 12, 31) = 51543.0
    • decYearToMjd

      public static double decYearToMjd(double decYear)
      Converts a Decimal Year to a Modified Julian Date.
      Parameters:
      decYear - decimal year
      Returns:
      modified Julian Date
      Examples:
      decYearToMjd(2000.0) = 51544.0
    • isoToUnixSec

      public static double isoToUnixSec(String isoDate)
      Converts an ISO8601 date string to seconds since 1970-01-01. The basic format of the isoDate argument is yyyy-mm-ddThh:mm:ss.s, though some deviations from this form are permitted:
      • The 'T' which separates date from time can be replaced by a space
      • The seconds, minutes and/or hours can be omitted
      • The decimal part of the seconds can be any length, and is optional
      • A 'Z' (which indicates UTC) may be appended to the time
      Some legal examples are therefore: "1994-12-21T14:18:23.2", "1968-01-14", and "2112-05-25 16:45Z".
      Parameters:
      isoDate - date in ISO 8601 format
      Returns:
      seconds since the Unix epoch
      Examples:
      isoToUnixSec("2004-10-25T18:00:00") = 1098727200, isoToMjd("1970-01-01") = 0
    • decYearToUnixSec

      public static double decYearToUnixSec(double decYear)
      Converts a Decimal Year to seconds since 1970-01-01.
      Parameters:
      decYear - decimal year
      Returns:
      seconds since the Unix epoch
      Examples:
      decYearToUnixSec(2000.0) = 946684800, decYearToUnixSec(1970) = 0
    • mjdToUnixSec

      public static double mjdToUnixSec(double mjd)
      Converts a Modified Julian Date to seconds since 1970-01-01.
      Parameters:
      mjd - modified Julian date
      Returns:
      seconds since the Unix epoch
    • jdToUnixSec

      public static double jdToUnixSec(double jd)
      Converts a Julian day to seconds since 1970-01-01.
      Parameters:
      jd - Julian day
      Returns:
      seconds since the Unix epoch
    • mjdToIso

      public static String mjdToIso(double mjd)
      Converts a Modified Julian Date value to an ISO 8601-format date-time string. The output format is yyyy-mm-ddThh:mm:ss. If the result predates the Common Era, the string "(BCE)" is prepended.
      Parameters:
      mjd - modified Julian date
      Returns:
      ISO 8601 format date corresponding to mjd
      Examples:
      mjdToIso(53551.72917) = "2005-06-30T17:30:00"
    • mjdToDate

      public static String mjdToDate(double mjd)
      Converts a Modified Julian Date value to an ISO 8601-format date string. The output format is yyyy-mm-dd. If the result predates the Common Era, the string "(BCE)" is prepended.
      Parameters:
      mjd - modified Julian date
      Returns:
      ISO 8601 format date corresponding to mjd
      Examples:
      mjdToDate(53551.72917) = "2005-06-30"
    • mjdToTime

      public static String mjdToTime(double mjd)
      Converts a Modified Julian Date value to an ISO 8601-format time-only string. The output format is hh:mm:ss.
      Parameters:
      mjd - modified Julian date
      Returns:
      ISO 8601 format time corresponding to mjd
      Examples:
      mjdToTime(53551.72917) = "17:30:00"
    • mjdToDecYear

      public static double mjdToDecYear(double mjd)
      Converts a Modified Julian Date to Decimal Year.
      Parameters:
      mjd - modified Julian Date
      Returns:
      decimal year
      Examples:
      mjdToDecYear(0.0) = 1858.87671
    • formatMjd

      public static String formatMjd(double mjd, String format)
      Converts a Modified Julian Date value to a date using a customisable date format. The format is as defined by the java.text.SimpleDateFormat class. The default output corresponds to the string "yyyy-MM-dd'T'HH:mm:ss"

      Note that the output from certain formatting characters (such as MMM for month, EEE for day of week) is dependent on your locale (system language settings). The output time zone however always corresponds to UTC.

      Parameters:
      mjd - modified Julian date
      format - formatting patttern
      Returns:
      custom formatted time corresponding to mjd
      See Also:
      Examples:
      formatMjd(50000.3, "EEE dd, MMM, yy") = "Tue 10 Oct, 95", formatMjd(50000.1234, "'time 'H:mm:ss.SSS") = "time 2:57:41.760"
    • jdToMjd

      public static double jdToMjd(double jd)
      Converts a Julian Day to Modified Julian Date. The calculation is simply jd-2400000.5.
      Parameters:
      jd - Julian day number
      Returns:
      MJD value
    • mjdToJd

      public static double mjdToJd(double mjd)
      Converts a Modified Julian Date to Julian Day. The calculation is simply jd+2400000.5.
      Parameters:
      mjd - MJD value
      Returns:
      Julian day number
    • mjdToJulian

      public static double mjdToJulian(double mjd)
      Converts a Modified Julian Date to Julian Epoch. For approximate purposes, the result of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 2000.5 is approximately 1 July 2000.
      Parameters:
      mjd - modified Julian date
      Returns:
      Julian epoch
      Examples:
      mjdToJulian(0.0) = 1858.87885
    • julianToMjd

      public static double julianToMjd(double julianEpoch)
      Converts a Julian Epoch to Modified Julian Date. For approximate purposes, the argument of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 2000.5 is approximately 1 July 2000.
      Parameters:
      julianEpoch - Julian epoch
      Returns:
      modified Julian date
      Examples:
      julianToMjd(2000.0) = 51544.5
    • mjdToBesselian

      public static double mjdToBesselian(double mjd)
      Converts Modified Julian Date to Besselian Epoch. For approximate purposes, the result of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 1950.5 is approximately 1 July 1950.
      Parameters:
      mjd - modified Julian date
      Returns:
      Besselian epoch
      Examples:
      mjdToBesselian(0.0) = 1858.87711
    • besselianToMjd

      public static double besselianToMjd(double besselianEpoch)
      Converts Besselian Epoch to Modified Julian Date. For approximate purposes, the argument of this routine consists of an integral part which gives the year AD and a fractional part which represents the distance through that year, so that for instance 1950.5 is approximately 1 July 1950.
      Parameters:
      besselianEpoch - Besselian epoch
      Returns:
      modified Julian date
      Examples:
      besselianToMjd(1950.0) = 33281.92346
    • unixMillisToMjd

      public static double unixMillisToMjd(long unixMillis)
      Converts from milliseconds since the Unix epoch (1970-01-01T00:00:00) to a modified Julian date value
      Parameters:
      unixMillis - milliseconds since the Unix epoch
      Returns:
      modified Julian date
    • mjdToUnixMillis

      public static long mjdToUnixMillis(double mjd)
      Converts from modified Julian date to milliseconds since the Unix epoch (1970-01-01T00:00:00).
      Parameters:
      mjd - modified Julian date
      Returns:
      milliseconds since the Unix epoch