DT_SUBTRACT Function

Decrements the values in a date/time variable by a specified amount.

Usage

result = DT_SUBTRACT(dt_var)

Input Parameters

dt_var — The original date/time variable or array of variables.

Returned Value

result — A date/time variable decremented by the specified amount.

Keywords

Compress — If present and nonzero, excludes predefined weekends and holidays from the result. The default is no compression (0).

Day — Specifies an offset value in days.

Hour — Specifies an offset value in hours.

Minute — Specifies an offset value in minutes.

Month — Specifies an offset value in months.

Second — Specifies an offset value in seconds.

Year — Specifies an offset value in years.

Note: Only one keyword can be specified at a time. You cannot, for example, specify both years and months in a single DT_SUBTRACT call. But if you need to subtract, for example, one day and one hour, you can simply subtract 25 hours.

Discussion

The DT_SUBTRACT function returns a date/time variable containing one or more dates/times that have been offset by the specified amount.

The keywords specify how the dates and/or times are decremented (subtracted from). If no keyword is specified, the default decrement is one day.

Only positive whole numbers (including zero) can be used with the keywords to specify a decrement. Therefore, the smallest unit that can be subtracted from dt_var is one second.

Example 1

; Create a date/time variable.
dtvar = VAR_TO_DT(2002, 03, 17, 09, 30, 54)
; Create a new date/time variable by subtracting
; 4 years from dtvar.
dtvar1 = DT_SUBTRACT(dtvar, Year=4)
; Display the new date/time variable.
PRINT, dtvar1
; PV-WAVE prints:
; { 1998  3  17  9  30  54.0000  89669.396  0}

Example 2

This example shows how to add one day to a date/time variable containing two date/time values.

; Convert two date strings to a date/time variable.
dtarray = STR_TO_DT(['17-03-2002', '8-04-2003'], Date_Fmt=2)
; The date/time variable dtarray contains two dates.
DT_PRINT, dtarray
; PV-WAVE prints:
; 03/17/2002
; 04/08/2003
; Create a new date/time variable dtarray1 that contains two 
; dates with one day subtracted from each date.
dtarray1 = DT_SUBTRACT(dtarray, /Day)
DT_PRINT, dtarray1
; PV-WAVE prints:
; 03/16/2002
; 04/07/2003

Example 3

This example shows the effect of using the Compress keyword with DT_SUBTRACT. Assume that you have defined Christmas (December 25, 1992) to be a holiday with the procedure CREATE_HOLIDAYS.

; Begin with a date variable containing December 26, 2002.
x = VAR_TO_DT(2002, 12, 26)
; Create a list of holidays
holidays = STR_TO_DT(['12-25-2002', '1-1-2002'], date_fmt=1)
CREATE_HOLIDAYS, holidays
; Subtract one day from the variable.
y = DT_SUBTRACT(x, /Day, /Compress)
DT_PRINT, y
; PV-WAVE prints: 12/24/2002

The result is December 24. Normally, the result would be 12/25/92, but because December 25 is defined as a holiday, the Compress keyword causes the 25th to be skipped.