This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# general/misc/time

- DAY_TO_YEAR_DOY
  determines year and day of year given day since 0000 AD
- DOY_TO_MONTH_DATE
  Determines month and date given the year and day of year.
- TIME_DOUBLE
  A fast, vectorized routine that returns the number of seconds since 1970.
- TIME_DOUBLE_ORDINAL
  Wrapper around time_double that supports ordinal dates in the input string, e.g., YYYY-DOY instead of YYYY-MM-DD
- TIME_EPOCH
  Returns the EPOCH time required by CDF files.
- TIME_PARSE
  Parse a string or array of strings into double precision seconds since 1970
- TIME_PB5
  Returns the PB5 time required by CDF files.
- TIME_STRING
  Converts time to a date string.
- TIME_STRUCT
  A fast, vectorized routine that returns a time structure.
- TIME_ZONE_OFFSET

# Routine Descriptions

## DAY_TO_YEAR_DOY

[Next Routine] [List of Routines]

    NAME:
       day_to_year_doy
    PURPOSE:
       determines year and day of year given day since 0000 AD
    USAGE:
       day_to_year_doy,daynum,year,doy
    INPUT:
       daynum:   (long int)  day since 0 AD
    OUTPUT:
       year:     year         (0 <= year <= 14699 AD)
       doy:      day of year  (1 <= doy  <=  366)
    NOTES:
      This procedure is reasonably fast, it works on arrays and works from
      0 AD to 14699 AD

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  day_to_year_doy.pro
    VERSION:  1.2
    LAST MODIFICATION:  97/01/27

(See general/misc/time/day_to_year_doy.pro)

## DOY_TO_MONTH_DATE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:
      doy_to_month_date, year, doy, month, date
    NAME:
      doy_to_month_date
    PURPOSE:
     Determines month and date given the year and day of year.
     fast, vector oriented routine that returns the month and date given year and
     day of year (1<=doy<=366)

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  doy_to_month_date.pro
    VERSION:  1.2
    LAST MODIFICATION:  97/01/27

(See general/misc/time/doy_to_month_date.pro)

## TIME_DOUBLE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_double(time)
    NAME:
      time_double
    PURPOSE:
     A fast, vectorized routine that returns the number of seconds since 1970.
    INPUT:  input can be any of the following types:
      double(s)      seconds since 1970   (returns the input)
      string(s)      format:  YYYY-MM-DD/hh:mm:ss  see "time_string"
      structure(s)   format returned in "time_struct"
      long array     (MUST be 2 dimensional!)  PB5 time  (req. by CDF)

    OUTPUT:
      double, number of seconds since 1970  (UNIX time)
    KEYWORDS:
      EPOCH:  if set, it implies the input is double precision EPOCH or
              complex double precision EPOCH16 time.
      TT2000: if set, it implies that the input is a 64 bit signed integer,
              TT2000 time: leaped nanoseconds since J2000

      TFORMAT: Specify a custom format for string to double conversion:
          Format string such as "YYYY-MM-DD/hh:mm:ss" (Default)
              the following tokens are recognized:
                YYYY  - 4 digit year
                yy    - 2 digit year (00-69 assumed to be 2000-2069, 70-99 assumed to be 1970-1999)
                MM    - 2 digit month
                DD    - 2 digit date
                hh    - 2 digit hour
                mm    - 2 digit minute
                ss    - 2 digit seconds
                .fff   - fractional seconds (can be repeated, e.g. .f,.ff,.fff,.ffff, etc... are all acceptable codes)
                MTH   - 3 character month
                DOY   - 3 character Day of Year
                TDIFF - 5 character, +hhmm or -hhmm different from UTC (sign required)
             tformat is case sensitive!

    SEE ALSO:  "time_string", "time_struct", "time_epoch", "time_pb5","time_parse"

    NOTE:
      This routine works on vectors and is designed to be fast.
      Output will have the same dimensions as the input
      Out of range values are interpreted correctly.
      ie.  1994-13-1/12:61:00  will be treated as:  1995-1-1/13:01:00

    CREATED BY:    Davin Larson  Oct 1996

    $LastChangedBy: davin-mac $
    $LastChangedDate: 2015-11-04 21:35:03 -0800 (Wed, 04 Nov 2015) $
    $LastChangedRevision: 19252 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time/time_double.pro $

(See general/misc/time/time_double.pro)

## TIME_DOUBLE_ORDINAL

[Previous Routine] [Next Routine] [List of Routines]

     FUNCTION:
             time_double_ordinal

     INPUT:
             time must be input as a string

     PURPOSE:
             Wrapper around time_double that supports ordinal dates in the input string, e.g., YYYY-DOY instead of YYYY-MM-DD

    $LastChangedBy: egrimes $
    $LastChangedDate: 2018-03-09 13:56:38 -0800 (Fri, 09 Mar 2018) $
    $LastChangedRevision: 24861 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time/time_double_ordinal.pro $

(See general/misc/time/time_double_ordinal.pro)

## TIME_EPOCH

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      time_epoch
    PURPOSE:
      Returns the EPOCH time required by CDF files.
    USAGE:
      epoch = time_epoch(t)
     NOT TESTED!!!

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_epoch.pro
    VERSION:  1.1
    LAST MODIFICATION:  96/10/16

(See general/misc/time/time_epoch.pro)

## TIME_PARSE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_parse
    PURPOSE:
      Parse a string or array of strings into double precision seconds since 1970
        (a)using user provided format code
     or (b)using flexible formatting and no code

    INPUTS:
      s : the input string or array of strings

    KEYWORDS:
      tformat=tformat:  Format string such as "YYYY-MM-DD/hh:mm:ss" (Default)
                   the following tokens are recognized:
                        YYYY  - 4 digit year
                        yy    - 2 digit year (00-69 assumed to be 2000-2069, 70-99 assumed to be 1970-1999)
                        MM    - 2 digit month
                        DD    - 2 digit date
                        hh    - 2 digit hour
                        mm    - 2 digit minute
                        ss    - 2 digit seconds
                        .fff   - fractional seconds (can be repeated, e.g. .f,.ff,.fff,.ffff, etc... are all acceptable codes)
                        MTH   - 3 character month
                        DOY   - 3 character Day of Year
                        TDIFF - 5 character, +hhmm or -hhmm different from UTC (sign required)
                   tformat is case sensitive!

     tdiff=tdiff: Offset in hours.  Array or scalar acceptable.
                  If your input times are not UTC and offset
                  is not specified in the time string itself,
                  use this keyword.

     MMDDYYYY=MMDDYYYY: handle dates in month/day/year format flexibly if tformat not specified

    Examples:

    NOTES:
      #1 Some format combinations can conflict and may lead to unpredictable behavior. (e.g. "YYYY-MM-MTH")
      #2 Primarily intended as a helper routine for time_double and time_struct
      #3 letter codes are case insensitive.
      #4 Based heavily on str2time by Davin Larson.

    $LastChangedBy: davin-mac $
    $LastChangedDate: 2019-03-04 13:43:53 -0800 (Mon, 04 Mar 2019) $
    $LastChangedRevision: 26755 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time/time_parse.pro $

(See general/misc/time/time_parse.pro)

## TIME_PB5

[Previous Routine] [Next Routine] [List of Routines]

    NAME:
      time_pb5
    PURPOSE:
      Returns the PB5 time required by CDF files.
    USAGE:
      pb5 = time_pb5(t)
    OUTPUT:
      2 dimensional long integer array with dimensions:  (n,3)  Where n is the number
      of elements in t
    Not fully TESTED!!!!

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_pb5.pro
    VERSION:  1.3
    LAST MODIFICATION:  97/01/27

(See general/misc/time/time_pb5.pro)

## TIME_STRING

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_string(TIME)
    NAME:
      time_string
    PURPOSE:
      Converts time to a date string.
    INPUTs:
      TIME  input can be a scalar or array of any dimension of type:
      double(s)      seconds since 1970
      string(s)      format:  YYYY-MM-DD/hh:mm:ss
      structure(s)   format:  given in "time_struct"
      float(s)       not recommended, may result in loss of precision
      longs(s)
                     values outside normal range will be corrected.
    KEYWORDS:

      LOCAL_TIME ;      if set then local time is displayed.

      TFORMAT:   a format string such as:  "YYYY-MM-DD/hh:mm:ss.ff DOW TDIFF"
                   the following tokens are recognized:
                        YYYY  - 4 digit year
                        yy    - 2 digit year
                        MM    - 2 digit month
                        DD    - 2 digit date
                        hh    - 2 digit hour
                        mm    - 2 digit minute
                        ss    - 2 digit seconds
                        .fff   - fractional seconds
                        MTH   - 3 character month
                        DOW   - 3 character Day of week
                        DOY   - 3 character Day of Year
                        TDIFF - 5 character, hours different from UTC    (useful with LOCAL keyword)

            if TFORMAT is defined then the following keywords are ignored.

      FORMAT:         specifies output format.
        FORMAT=0:  YYYY-MM-DD/hh:mm:ss
        FORMAT=1:  YYYY Mon dd hhmm:ss
        FORMAT=2:  YYYYMMDD_hhmmss
        FORMAT=3:  YYYY MM dd hhmm:ss
        FORMAT=4:  YYYY-MM-DD/hh:mm:ss
        FORMAT=5:  YYYY/MM/DD hh:mm:ss
        FORMAT=6:  YYYYMMDDhhmmss
      SQL:            produces output format: "YYYY-MM-DD hh:mm:ss.sss"
                      (quotes included) which convenient for building SQL queries.
      PRECISION:      specifies precision
          -5:   Year only
          -4:   Year, month
          -3:   Year, month, date
          -2:   Year, month, date, hour
          -1:   Year, month, date, hour, minute
           0:   Year, month, date, hour, minute, sec
          >0:   fractional seconds
      AUTOPREC  If set PREC will automatically be set based on the array of times
      DELTAT:   (float) PREC set based on this precision.
      DATE_ONLY:   Same as PREC = -3
      MSEC:        Same as PREC = 3

    OUTPUT:
      string with the following format: YYYY-MM-DD/hh:mm:ss (Unless
      modified by keywords.)

    See Also:  "time_double"  , "time_struct" or "time_ticks"

    NOTE:
      This routine works on vectors and is designed to be fast.
      Output will have the same dimensions as the input.

      If you call this function using a float for time0, IDL transforms the float
      to an exp format, which may result in loss of precision. For example:
      time_string(1514851198.0D) = 2018-01-01/23:59:58 (Correct!)
      time_string(1514851198.0) = 2018-01-02/00:00 (Wrong!) float becomes 1.5148512e+009
      time_string(1514851198) = 2018-01-01/23:59:58 (Correct!)

    CREATED BY:    Davin Larson  Oct 1996
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2025-05-24 15:55:33 -0700 (Sat, 24 May 2025) $
     $LastChangedRevision: 33332 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time/time_string.pro $

(See general/misc/time/time_string.pro)

## TIME_STRUCT

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: time_struct(time)
    NAME:
      time_struct
    PURPOSE:
     A fast, vectorized routine that returns a time structure.
    INPUT:  input can be any of the following types:
      double(s)      seconds since 1970
      string(s)      format:  YYYY-MM-DD/hh:mm:ss
      structure(s)   similar to format below.

    OUTPUT:
      structure with the following format:
    ** Structure TIME_STRUCT, 11 tags, length=40:
       YEAR            INT           1970            ; year    (0-14699)
       MONTH           INT              1            ; month   (1-12)
       DATE            INT              1            ; date    (1-31)
       HOUR            INT              0            ; hours   (0-23)
       MIN             INT              0            ; minutes (0-59)
       SEC             INT              0            ; seconds (0-59)
       FSEC            DOUBLE           0.0000000    ; fractional seconds (0-.999999)
       DAYNUM          LONG            719162        ; days since 0 AD  (subject to change)
       DOY             INT              0            ; day of year (1-366)
       DOW             INT              3            ; day of week  (subject to change)
       SOD             DOUBLE           0.0000000    ; seconds of day
       DST        =    INT      = 0                  ; Daylight saving time flag
       TZONE      =    INT      = 0                  ; Timezone  (Pacific time is -8)
       TDIFF      =    INT      = 0                  ; Hours from UTC

    KEYWORDS:

      TFORMAT: Specify a custom format for string to struct conversion:
          Format string such as "YYYY-MM-DD/hh:mm:ss" (Default)
              the following tokens are recognized:
                YYYY  - 4 digit year
                yy    - 2 digit year (00-69 assumed to be 2000-2069, 70-99 assumed to be 1970-1999)
                MM    - 2 digit month
                DD    - 2 digit date
                hh    - 2 digit hour
                mm    - 2 digit minute
                ss    - 2 digit seconds
                .fff   - fractional seconds (can be repeated, e.g. .f,.ff,.fff,.ffff, etc... are all acceptable codes)
                MTH   - 3 character month
                DOY   - 3 character Day of Year
                TDIFF - 5 character, +hhmm or -hhmm different from UTC (sign required)
             tformat is case sensitive!

    See Also:  "time_double", "time_string", "time_epoch", "time_pb5", "time_zone_offset","time_parse"

    NOTE:
      This routine works on vectors and is designed to be fast.
      Output will have the same dimensions as the input

    CREATED BY:    Davin Larson  Oct 1996

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-10-17 12:47:15 -0700 (Wed, 17 Oct 2018) $
     $LastChangedRevision: 25991 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time/time_struct.pro $

(See general/misc/time/time_struct.pro)

## TIME_ZONE_OFFSET

[Previous Routine] [List of Routines]

    FUNCTION: time_zone_offset()
    PURPOSE:  Returns timezone offset in hours.  Will include any offset from daylight savings time

    Usage:
    IDL> print,time_zone_offset()
        -7

    IDL> file_touch,somefile,systime(1),/mtime,toffset=time_zone_offset()

     $LastChangedBy: pcruce $
     $LastChangedDate: 2014-02-06 17:49:56 -0800 (Thu, 06 Feb 2014) $
     $LastChangedRevision: 14190 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time/time_zone_offset.pro $

(See general/misc/time/time_zone_offset.pro)