|
Size: 5664
Comment: Rewrite
|
← Revision 10 as of 2025-05-20 19:25:08 ⇥
Size: 8446
Comment: Date diff functions
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 52: | Line 52: |
| ||'''Function Name'''||'''Meaning''' ||'''Output Format'''|| ||`cofC(x)` ||Converts a `%tC`-formatted datetime ||`%tc` || ||`cofd(x)` ||Converts a date ||`%tc` || ||`Cofc(x)` ||Converts a `%tc`-formatted datetime ||`%tC` || ||`Cofd(x)` ||Converts a date ||`%tC` || ||`day(x)` ||Extracts the days component from a date ||n/a, in [1,31] || ||`dofc(x)` ||Converts a `%tc`-formatted datetime ||`%td` || ||`dofC(x)` ||Converts a `%tC`-formatted datetime ||`%td` || ||`dofh(x)` ||Converts a number of halfyears since the epoch ||`%td` || ||`dofm(x)` ||Converts a number of months since the epoch ||`%td` || ||`dofq(x)` ||Converts a number of quarters since the epoch ||`%td` || ||`dofw(x)` ||Converts a number of weeks since the epoch ||`%td` || ||`dofy(x)` ||Converts a number of years since the epoch ||`%td` || ||`dow(x)` ||Extracts the day of week from a date ||n/a, in [0,6] || ||`doy(x)` ||Extracts the day of year from a date ||n/a, in [1,366] || ||`halfyear(x)` ||Extracts the halfyear from a date ||n/a, in [1,2] || ||`hofd(x)` ||Converts a date ||`%th` || ||`hh(x)` ||Extracts the hours component from a `%tc`-formatted datetime ||n/a || ||`hhC(x)` ||Extracts the hours component from a `%tC`-formatted datetime ||n/a || ||`mm(x)` ||Extracts the minutes component from a `%tc`-formatted datetime||n/a || ||`mmC(x)` ||Extracts the minutes component from a `%tC`-formatted datetime||n/a || ||`month(x)` ||Extracts the months component from a date ||n/a, in [1,12] || ||`quarter(x)` ||Extracts the quarter from a date ||n/a, in [1,4] || ||`ss(x)` ||Extracts the seconds component from a `%tc`-formatted datetime||n/a || ||`ssC(x)` ||Extracts the seconds component from a `%tC`-formatted datetime||n/a || ||`week(x)` ||Extracts the week from a date ||n/a, in [1,52] || ||`year(x)` ||Extracts the years component from a date ||n/a || ||`mofd(x)` ||Converts a date ||`%tm` || ||`qofd(x)` ||Converts a date ||`%tq` || ||`wofd(x)` ||Converts a date ||`%tw` || ||`yofd(x)` ||Converts a date ||`%ty` || |
||'''Function Name''' ||'''Meaning''' ||'''Output Format'''|| ||`cofC(x)` ||Converts a `%tC`-formatted datetime ||`%tc` || ||`cofd(x)` ||Converts a date ||`%tc` || ||`Cofc(x)` ||Converts a `%tc`-formatted datetime ||`%tC` || ||`Cofd(x)` ||Converts a date ||`%tC` || ||`day(x)` ||Extracts the days component from a date ||n/a, in [1,31] || ||`dayssincedow(x,n)` ||Days between reference date and last weekday `n` ||n/a, in [1,7] || ||`dayssinceweekday(x,n)`||Days between reference date and last weekday `n` ||n/a, in [1,7] || ||`daysuntildow(x,n)` ||Days between reference date and next weekday `n` ||n/a, in [1,7] || ||`daysuntilweekday(x,n)`||Days between reference date and next weekday `n` ||n/a, in [1,7] || ||`dofc(x)` ||Converts a `%tc`-formatted datetime ||`%td` || ||`dofC(x)` ||Converts a `%tC`-formatted datetime ||`%td` || ||`dofh(x)` ||Converts a number of halfyears since the epoch ||`%td` || ||`dofm(x)` ||Converts a number of months since the epoch ||`%td` || ||`dofq(x)` ||Converts a number of quarters since the epoch ||`%td` || ||`dofw(x)` ||Converts a number of weeks since the epoch ||`%td` || ||`dofy(x)` ||Converts a number of years since the epoch ||`%td` || ||`dow(x)` ||Extracts the day of week from a date ||n/a, in [0,6] || ||`doy(x)` ||Extracts the day of year from a date ||n/a, in [1,366] || ||`halfyear(x)` ||Extracts the halfyear from a date ||n/a, in [1,2] || ||`hofd(x)` ||Converts a date ||`%th` || ||`hh(x)` ||Extracts the hours component from a `%tc`-formatted datetime ||n/a || ||`hhC(x)` ||Extracts the hours component from a `%tC`-formatted datetime ||n/a || ||`mm(x)` ||Extracts the minutes component from a `%tc`-formatted datetime||n/a || ||`mmC(x)` ||Extracts the minutes component from a `%tC`-formatted datetime||n/a || ||`month(x)` ||Extracts the months component from a date ||n/a, in [1,12] || ||`quarter(x)` ||Extracts the quarter from a date ||n/a, in [1,4] || ||`ss(x)` ||Extracts the seconds component from a `%tc`-formatted datetime||n/a || ||`ssC(x)` ||Extracts the seconds component from a `%tC`-formatted datetime||n/a || ||`week(x)` ||Extracts the week from a date ||n/a, in [1,52] || ||`year(x)` ||Extracts the years component from a date ||n/a || ||`mofd(x)` ||Converts a date ||`%tm` || ||`qofd(x)` ||Converts a date ||`%tq` || ||`wofd(x)` ||Converts a date ||`%tw` || ||`yofd(x)` ||Converts a date ||`%ty` || Note that weekdays are encoded such that 0 is Sunday and 6 is Saturday. This is used for both argument values (e.g., `dayssincedow`) and return values (e.g., `dow`). ---- == Difference Functions == The following functions calculate the difference between two dates, or two datetimes, in a variable unit. ||'''Function Name''' ||'''Meaning''' || ||`age(dob,d)` ||Integer age calculated from `dob` and reference date || ||`age_frac(dob,d)` ||Decimal age calculated from `dob` and reference date || ||`Clockdiff(a,b,u)` ||Integer difference between two datetimes, assuming `%tC` format|| ||`Clockdiff_frac(a,b,u)`||Decimal difference between two datetimes, assuming `%tC` format|| ||`clockdiff(a,b,u)` ||Integer difference between two datetimes, assuming `%tc` format|| ||`clockdiff_frac(a,b,u)`||Decimal difference between two datetimes, assuming `%tc` format|| ||`datediff(a,b,u)` ||Integer difference between two dates || ||`datediff_frac(a,b,u)` ||Decimal difference between two dates || Most of the above functions require a (case-insensitive) unit `u` argument, specifying what the return value should be encoded as. This then also determines ''whether'' there is a fractional element that can be returned by the `_frac` version of the function. * For date differences (e.g., `datediff`), `u` can be: * `"day"` or `"d"` for days * `"month"`, `"mon"`, or `"m"` for months * `"year"` or `"y"` for years * For datetime differences (e.g., `clockdiff`), `u` can be: * `"day"` or `"d"` for days * `"hour"` or `"h"` for hours * `"minute"`, `"min"`, or `"m"` for minutes * `"second"`, `"sec"`, or `"s"` for seconds * `"millisecond"` or `"ms"` for milliseconds Additionally, the functions operating on dates (e.g., `datediff`) can take an (case-insensitive) optional argument, specifying what date should be considered the anniversary for February 29th outside of leap years. This argument can be: * `"1mar"`, `"01mar"`, `"mar1"`, or `"mar01"` (the default) * `"28feb"` or `"feb28"` |
Stata Datetime Functions
Stata supports these datetime functions (i.e., numeric function designed for date and datetime formatted values) in the global scope.
Contents
Functions Converting Integers
See Numeric Functions.
Functions Converting a String
These functions convert a string into a numeric value that represents a date or time. Masks instruct how a date or time as represented in string data. A datetime format still must be separately applied to the numeric value.
As an example, the mask of "DMY" can parse all of:
"21nov2006"
"21 November 2006"
"21-11-2006"
"21112006"
Spaces are ignored in a mask; "DMY" is equivalent to "D M Y".
The mask "DMY" cannot parse a string with a two-digit year. A two-digit prefix can be applied to "Y" in the mask, such as "DM19Y". If a string has a two-digit year, such a mask will cause the year to be interpreted as being within the 1900s. If a string has a four-digit year, the mask will not mutate the value.
Function Name |
Meaning |
Output Format |
Example |
clock(s,m) |
Parse a datetime |
%tc |
clock(s,"YMDhms") |
Clock(s,m) |
Parse a datetime |
%tC |
Clock(s,"YMDhms") |
date(s,m) |
Parse a date |
%td |
date(s,"MDY") |
halfyearly(s,m) |
Parse a halfyear |
%th |
halfyearly(s,"YH") |
monthly(s,m) |
Parse a month |
%tm |
monthly(s,"YM") |
quarterly(s,m) |
Parse a quarter |
%tq |
quarterly(s,"YQ") |
weekly(s,m) |
Parse a week |
%tw |
weekly(s,"YW") |
yearly(s,m) |
Parse a year |
%ty |
yearly(s,"Y") |
Datetime Functions
These functions are intended for use on date and datetime formatted values.
Function Name |
Meaning |
Output Format |
cofC(x) |
Converts a %tC-formatted datetime |
%tc |
cofd(x) |
Converts a date |
%tc |
Cofc(x) |
Converts a %tc-formatted datetime |
%tC |
Cofd(x) |
Converts a date |
%tC |
day(x) |
Extracts the days component from a date |
n/a, in [1,31] |
dayssincedow(x,n) |
Days between reference date and last weekday n |
n/a, in [1,7] |
dayssinceweekday(x,n) |
Days between reference date and last weekday n |
n/a, in [1,7] |
daysuntildow(x,n) |
Days between reference date and next weekday n |
n/a, in [1,7] |
daysuntilweekday(x,n) |
Days between reference date and next weekday n |
n/a, in [1,7] |
dofc(x) |
Converts a %tc-formatted datetime |
%td |
dofC(x) |
Converts a %tC-formatted datetime |
%td |
dofh(x) |
Converts a number of halfyears since the epoch |
%td |
dofm(x) |
Converts a number of months since the epoch |
%td |
dofq(x) |
Converts a number of quarters since the epoch |
%td |
dofw(x) |
Converts a number of weeks since the epoch |
%td |
dofy(x) |
Converts a number of years since the epoch |
%td |
dow(x) |
Extracts the day of week from a date |
n/a, in [0,6] |
doy(x) |
Extracts the day of year from a date |
n/a, in [1,366] |
halfyear(x) |
Extracts the halfyear from a date |
n/a, in [1,2] |
hofd(x) |
Converts a date |
%th |
hh(x) |
Extracts the hours component from a %tc-formatted datetime |
n/a |
hhC(x) |
Extracts the hours component from a %tC-formatted datetime |
n/a |
mm(x) |
Extracts the minutes component from a %tc-formatted datetime |
n/a |
mmC(x) |
Extracts the minutes component from a %tC-formatted datetime |
n/a |
month(x) |
Extracts the months component from a date |
n/a, in [1,12] |
quarter(x) |
Extracts the quarter from a date |
n/a, in [1,4] |
ss(x) |
Extracts the seconds component from a %tc-formatted datetime |
n/a |
ssC(x) |
Extracts the seconds component from a %tC-formatted datetime |
n/a |
week(x) |
Extracts the week from a date |
n/a, in [1,52] |
year(x) |
Extracts the years component from a date |
n/a |
mofd(x) |
Converts a date |
%tm |
qofd(x) |
Converts a date |
%tq |
wofd(x) |
Converts a date |
%tw |
yofd(x) |
Converts a date |
%ty |
Note that weekdays are encoded such that 0 is Sunday and 6 is Saturday. This is used for both argument values (e.g., dayssincedow) and return values (e.g., dow).
Difference Functions
The following functions calculate the difference between two dates, or two datetimes, in a variable unit.
Function Name |
Meaning |
age(dob,d) |
Integer age calculated from dob and reference date |
age_frac(dob,d) |
Decimal age calculated from dob and reference date |
Clockdiff(a,b,u) |
Integer difference between two datetimes, assuming %tC format |
Clockdiff_frac(a,b,u) |
Decimal difference between two datetimes, assuming %tC format |
clockdiff(a,b,u) |
Integer difference between two datetimes, assuming %tc format |
clockdiff_frac(a,b,u) |
Decimal difference between two datetimes, assuming %tc format |
datediff(a,b,u) |
Integer difference between two dates |
datediff_frac(a,b,u) |
Decimal difference between two dates |
Most of the above functions require a (case-insensitive) unit u argument, specifying what the return value should be encoded as. This then also determines whether there is a fractional element that can be returned by the _frac version of the function.
For date differences (e.g., datediff), u can be:
"day" or "d" for days
"month", "mon", or "m" for months
"year" or "y" for years
For datetime differences (e.g., clockdiff), u can be:
"day" or "d" for days
"hour" or "h" for hours
"minute", "min", or "m" for minutes
"second", "sec", or "s" for seconds
"millisecond" or "ms" for milliseconds
Additionally, the functions operating on dates (e.g., datediff) can take an (case-insensitive) optional argument, specifying what date should be considered the anniversary for February 29th outside of leap years. This argument can be:
"1mar", "01mar", "mar1", or "mar01" (the default)
"28feb" or "feb28"