DT_SUBTRACT Function

Reference Guide > D Routines > 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.