Working with dates and times
This page discusses various aspects of working with dates and times
in IDL. It then gives a brief description of the available routines
and several examples.
Quick Index:
Time units
A rather large number of routines fall into this category.
Both dates and times are commonly specified using a mix of units
instead of a single unit. Dates use years, months, and days,
with years and months each containing a variable number of days.
Times use hours, minutes, and seconds, and are simpler since the
size of the units do not vary. Dates and times may be mixed as,
for example, in the output of systime().
Date systems
Dealing with dates is further complicated because several systems are
in use. The most human readable uses year, month, and day in some order.
Other systems are day number of the year (dn), and Julian Day (jd)
(these are not the same). Software should be flexible enough to allow
dates using year, month, and day to have any order for these components.
One valid constraint is to require that the month be specified by name,
using at least three letters. Routines described below that deal with
date as a string make this requirement. Other routines allow the
year, month, and day to be specified as separate numeric values.
Routines are provided to work with weekdays.
Routine naming conventions
Some notes on routine naming conventions might be useful.
These routines were not designed from scratch as a set. That
would certainly have been desirable, but they were written as needed,
and the style hopefully improved over time. Still, certain patterns have
emerged. For example, a number of routines convert from one date
system to another. The names often reflect this by being in the
form: input2output. Often this type of routine comes in pairs where
one routine is the inverse of the other; sometimes there are one or more
closely relate variants. An example is the routine date2ymd which
converts a date from something like '8 Oct, 1994' to the numeric
values of 1994, 10, 8. The inverse routine is ymd2date.
Date strings
In the following routines, the term date refers to a form that
gives only the day but not a time on that day. Dates may be given
in several forms such as year, month, day in numeric values; year
and day of year; Julian Day as a long integer; or a date string.
The format of a date string is flexible except that the month must
be month name. Dashes, commas, periods, or slashes are allowed.
Some examples:
23 sep, 1985
sep 23 1985
1985 Sep 23
23/SEP/85
23-SEP-1985
85-SEP-23
23 September, 1985.
Date/Time strings
The term date/time string refers to a string containing both a date
and time. For example: Fri May 27 17:11:00 1994 is a date/time string.
The components may be in any order. The day of the week may be
included but is not used (it is redundant anyway). Date/time strings
are handled correctly as dates by the routines that deal only with date
strings. If time is not given it is assumed to be 0:00:00. In most
cases the full 4-digit year is required (not just the 2-digit year).
Time strings
The term time only refers to just hours, minutes, and seconds.
This may be in one of several forms such as a string hh:mm:ss;
the numeric values h, m, s; the number of seconds after midnight
as a number; or in general, the number of seconds after some known
starting point. Time only, as in the form hh:mm:ss, does not
completely specify by itself an actual point in time, but a time
interval. In practice the starting point is often known.
Complete time
The term complete time refers to a time system that specifies a
single definite point in time. Several example forms are date/time
strings; Julian Days which include the fractional part of the day;
and Julian Seconds, a new form discussed below. Julian Days as used
in this library are long integers so are dates and not complete times.
Calendar functions
A number of routines are related to calendar type functions such as
finding the number of days in a certain month, or finding the day of
the week.
One line descriptions
As a guide to the routines in this section the one line descriptions
are given below. An indication is given on what type of routine
each is: (f) means function, and (p) means procedure. Each routine
has built-in help. It may be displayed using the following IDL commands
(xxx is routine name):
For procedures: xxx, /help
For functions: help,xxx(/help)
Date only
ymd2jd (f) = From Year, Month, and Day compute Julian Day number.
jd2ymd (p) = Find year, month, day from julian day number.
date2ymd (p) = Date text string to the numbers year, month, day.
ymd2date (f) = Convert from year, month, day numbers to date string.
jd2date (f) = Convert a Julian Day number to a date string.
jd2str (p) = Find year, month, day strings from julian day number.
ydn2date (f) = Convert year and day of the year to a date string.
ydn2md (p) = Convert from year and day number of year to month and day of month.ymd2dn (f) = Convert from year, month, day to day number of year.
xdate (p) = Widget based date selection tool.
The most used routines here are probably ymd2jd and jd2ymd. Some examples:
print, ymd2jd(1994,6,22) gives 2449526.
jd2ymd, 2449526,y,m,d
print,y,m,d gives 1994 6 22
Complete time
dt_tm_tojs (f) = Convert a date/time string to "Julian Seconds".
dt_tm_fromjs (f) = Convert "Julian Seconds" to a date/time string.
ymds2js (f) = Convert to year, month, day, second to "Julian Seconds".
js2ymds (p) = Convert from "Julian Second" to year, month, day, second.
js2jd (f) convert from "Julian Seconds" to Julian Day number.
jd2js (f) convert from Julian Day number to "Julian Seconds".
dt_tm_mak (f) = Set up a time and date string from reference JD and offset.
dt_tm_brk (p) = Break a date and time string into separate date and time.
dt_tm_chk (f) = Check date & time string that both parts exist & are valid.
dt_tm_dif (f) = Find time interval in seconds between two date/time strings.
dt_tm_inc (p) = Increment a date/time by a given number of seconds.
The most used routines here are probably dt_tm_tojs and dt_tm_fromjs. Some
simple examples:
js = dt_tm_tojs('8:39 22 Jun, 1994')
print,js gives -1.7441046e+08
print,dt_tm_fromjs(js) gives 1994 Jun 22 08:39:00 Wed
The date returned by dt_tm_fromjs in the example is in the default format.
Extensive time formatting is supported and will be discussed in the
time series page.
Time only
secstr (f) = Convert a time string to seconds after midnight.
strsec (f) = Convert seconds after midnight to a time string.
sechms (p) = Seconds after midnight to h, m, s, numbers and strings.
gmt_offsec (f) = Return offset in seconds from local time to GMT (UT).
lmst (f) = Give local mean sidereal time.
Calendar related routines
monthdays (f) = Given a year and month returns number of days in that month.
monthnames (f) = Returns a string array of month names.
nthweekday (f) = Julian Day of N'th weekday of month (like 2nd tues).
weekday (f) = Compute weekday given year, month, day.
Time series support
jsplot (p) = Make a time series plot with time in Julian Seconds.
izoom (p) = zoom an image and display with labeled axes (use /js keyword).
cyph (p) = Construct a cycle/phase array from time series data.
veri (p) = Interactive vertical line on screen or plot (use /js keyword).
crossi (p) = Interactive cross-hair cursor on screen or plot (use /js keyword).
timeaxis (p) = Plot a time axis.
Time series support is discussed in greater detail in the
time series page.
It would be valuable to look at the built-in help and try some of
these routines so you will be familiar with them when a need arises.
IDL main page.