= SPSS Datetime Functions =

SPSS supports these '''datetime functions''' in the global scope.

<<TableOfContents>>

----



== Date ==

The '''`DATE`''' function returns a date value.

{{{
numeric DATEVAR (date10)
compute DATEVAR = date.mdy(1, 2, 3000)

* Given TIMESTAMPVAR like "dd/mm/yyyy hh:mm:ss".
numeric DATETIMEVAR (datetime20).
compute DATETIMEVAR = date.mdy(
  number(char.substr(TIMESTAMPVAR,1,2), f2),
  number(char.substr(TIMESTAMPVAR,4,2), f2),
  number(char.substr(TIMESTAMPVAR,7,4), f4)
) + time.hms(
  number(char.substr(TIMESTAMPVAR,12,2), f2),
  number(char.substr(TIMESTAMPVAR,15,2), f2),
  number(char.substr(TIMESTAMPVAR,18,2), f2)
).
}}}

Valid subtypes of the `DATE` function include...

 * `date.mdy(month, day, year)` (shown above)
 * `date.dmy(day, month, year)`
 * `date.moyr(month, year)`
 * `date.qyr(quarter, year)` where `quarter` is between 1 and 4
 * `date.wkyr(week, year)` where `week` is between 1 and 53
 * `date.yrday(year, daynum)` where `daynum` is between 1 and 366

These range checks are common to all of the above:

 * `year` must be greater than 1582
 * `month` must be between 1 and 13
 * `day` must be between 0 and 31

Note that a date format must separately be applied to a created variable.

Note that if a range check is failed for ''any'' argument, a missing value is returned.

Note that if a `day` value is invalid for a particular month (eg. 29 through 31 for February in non-leap years) the returned value is shifted across months.

{{{
compute example = date.mdy(1,0,2022).
formats example (ADATE10).
execute.
list all.
* 12/31/2021.

compute example = date.mdy(2,29,2022).
execute.
list all.
* 03/01/2022.

compute example = date.mdy(2,30,2022).
execute.
list all.
* 03/02/2022.
}}}

Furthermore note that a `month` value of 13 is equivalent to January in the following year.

Note that for ''any'' `year` value, `date.wkyr(1, year)` will return January 1 of that year.

----



== Datediff ==


The '''`DATEDIFF`''' function subtracts a date or time from another, returning an integer in terms of the specified unit.

{{{
num_days = datediff(date1,date2,"days")
}}}

Valid units include:

 * `"years"`
 * `"quarters"`
 * `"months"`
 * `"weeks"`
 * `"days"`
 * `"hours"`
 * `"minutes"`
 * `"seconds"`

Note that the returned value is floored using the specified unit.

----



== Datesum ==

The '''`DATESUM`''' function adds some number of units to a date or time, returning a new date or time.

{{{
month_ago = datesum(date1,-1,"months")
}}}

Reference the above list for valid values of the third argument.

----



== Time ==

The '''`TIME`''' function returns a time value.

{{{
compute two_thirty = time.hms(2, 30, 0)
}}}

Valid subtypes of the `DATE` function include...

 * `time.hms(hours, minutes, seconds)` (shown above) where `seconds` is allowed to be a decimal
 * `time.hms(hours, minutes)` where `minutes` is allowed to be a decimal
 * `time.hms(hours)` where `hours` is allowed to be a decimal
 * `time.days(days)`

Note that a time format must separately be applied to a created variable.

Note that `minutes` '''must be less than 60''' if `hours` is non-zero. `time.hms(0, 90)` valid, but `time.hms(1, 90)` is not. Similarly, `seconds` '''must be less than 60''' if `minutes` '''''or''''' `hours` are non-zero.

----



== Xdate ==

The '''`XDATE`''' function extracts a component of a date or time value.

||'''Function''' ||'''Returns'''              ||
||`xdate.year`   ||Year                       ||
||`xdate.month`  ||Month (1 to 12)            ||
||`xdate.mday`   ||Day of the month (1 to 31) ||
||`xdate.wkday`  ||Day of the week (1 to 7)   ||
||`xdate.jday`   ||Day of the year (1 to 366) ||
||`xdate.hour`   ||Hours                      ||
||`xdate.minute` ||Minutes                    ||
||`xdate.second` ||Seconds                    ||



----
CategoryRicottone