= Stata Datetime Functions =

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

<<TableOfContents>>

----



== Functions Converting Integers ==



=== Dhms ===

Convert an date value (formatted as `%td) plus an hour, minute, and second into the number of milliseconds since the Stata epoch (`01jan1960 00:00:00.000`) ''ignoring'' leap seconds.

{{{
generate double datetime = dhms(dmy(day, month, year), hour, minute, second)
format date %tc
}}}

See also `Cdhms`, which creates returns a number that should instead be formatted as `%tC` because it does ''not'' ignore leap seconds.

----



=== Hms ===

Convert an hour, minute, and second into the number of milliseconds since midnight ''ignoring'' leap seconds.

{{{
generate double datetime = hms(hour, minute, second)
format date %tc
}}}

See also `Chms`, which creates returns a number that should instead be formatted as `%tC` because it does ''not'' ignore leap seconds.

----



=== Mdy ===

Convert a month, day, and year into the number of days since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate long date = mdy(month, day, year)
format date %td
}}}

----



=== Mdyhms ===

Convert a day, month, year, hour, minute, and second into the number of milliseconds since the Stata epoch (`01jan1960 00:00:00.000`) ''ignoring'' leap seconds.

{{{
generate double datetime = mdyhms(month, day, year, hour, minute, second)
format date %tc
}}}

See also `Cmdyhms`, which creates returns a number that should instead be formatted as `%tC` because it does ''not'' ignore leap seconds.

----



=== Y ===

Convert a year into the number of years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int year = y(year)
format year %ty
}}}

----



=== Yh ===

Convert a year and half year into the number of half years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int halfyears = yh(year, halfyear)
format halfyears %th
}}}

----



=== Ym ===

Convert a year and month into the number of months since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int months = y(year, month)
format months %tm
}}}

----



=== Yq ===

Convert a year and quarter into the number of years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int quarters = yq(year, quarter)
format quarters %tq
}}}

----



=== Yw ===

Convert a year and week into the number of weeks since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int weeks = yw(year, week)
format weeks %tw
}}}

----



== 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.

----



=== Clock ===

Convert a string date and time into the number of milliseconds since the Stata epoch (`01jan1960 00:00:00.000`).

There are two functions: '''`clock`''' and '''`Clock`'''.

To create a datetime that ''ignores'' leap seconds, try:

{{{
generate double datetime = clock(string, "YMDhms")
format datetime %tc 
}}}

To create a datetime that ''includes'' leap seconds since the epoch, try:

{{{
generate double datetime = Clock(string, "YMDhms")
format datetime %tC 
}}}

As noted above, the mask should be composed of: `"Y"`, `"M"`, `"D"`, `"h"`, `"m"`, and `"s"`.

----



=== Date ===

Convert a string date into the number of days since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate long date = date(string, "MDY")
format date %td
}}}

As noted above, the mask should be composed of: `"Y"`, `"M"`, and `"D"`. See above for details on masks.

----



=== HalfYearly ===

Convert a string date into the number of half years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int halfyear = halfyearly(string, "YH")
format halfyear %th
}}}

As noted above, the mask should be composed of: `"Y"` and `"H"`. See above for details on masks.

----



=== Monthly ===

Convert a string like `"2012m12"` into the number of months since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int month = monthly(string, "YM")
format month %tm
}}}

As noted above, the mask should be composed of: `"Y"` and `"M"`. See above for details on masks.

If a string is instead formatted like `"201212"` or `"2000-12"`, try:

{{{
generate int month = mofd(date(string, "YM"))
format month %tm
}}}

----



=== Quarterly ===

Convert a string like `"2012q4"` into the number of quarters since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int quarter = quarterly(string, "YQ")
format quarter %tq
}}}

As noted above, the mask should be composed of: `"Y"` and `"Q"`. See above for details on masks.

----



=== Weekly ===

Convert a string date into the number of weeks since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int week = weekly(string, "YW")
format week %tw
}}}

As noted above, the mask should be composed of: `"Y"` and `"W"`. See above for details on masks.

----



=== Yearly ===

Convert a string date into the number of years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int year = yearly(string, "Y")
format year %ty
}}}

As noted above, the mask should be composed of: `"Y"` and `"W"`. See above for details on masks.

----



== Datetime Functions ==

These functions should only be used on numeric variables with a [[Stata/DataFormats#Date_and_Datetime_Data|date or datetime format]].



=== COfC ===

Convert a datetime around the handling of leap seconds.

'''`Cofc`''' takes a datetime ''ignoring'' leap seconds since the Stata epoch (`01jan1960 00:00:00.000`) as input, and returns a datetime ''including'' them.

'''`cofC`''' does the reverse.

{{{
generate double datetime2 = cofC(datetime)
format datetime2 %tc

generate double datetime3 = Cofc(datetime)
format datetime3 %tC
}}}

----



=== COfD ===

Convert a date into a datetime.

There are two functions: '''`cofd`''' and '''`Cofd`'''. They return a numeric value that should be formatted as `%tc` or `%tC`, respectively.

{{{
generate double datetime = cofd(date)
format datetime %tc

generate double datetime2 = Cofd(date)
format datetime2 %tC
}}}

----



=== Day ===

Extract the day of the month number (1 to 31) from a date (i.e. `%td`-formatted value).

{{{
generate byte day = day(date)
}}}

----



=== DOfC ===

Convert a datetime into a date.

There are two functions: '''`dofc`''' and '''`dofC`'''. They take a numeric value as input, formatted as `%tc` or `%tC` respectively.

{{{
generate long date = dofc(datetime)
#or
generate long date = dofC(datetime)

format date %td
}}}

----



=== DOfH ===

Convert a half-year (i.e. a `%th`-formatted value) into a date.

{{{
generate long date = dofh(halfyear)
format date %td
}}}

----



=== DOfM ===

Convert a month (i.e. a `%tm`-formatted value) into a date.

{{{
generate long date = dofm(month)
format date %td
}}}

----



=== DOfQ ===

Convert a quarter (i.e. a `%tq`-formatted value) into a date.

{{{
generate long date = dofq(quarter)
format date %td
}}}

----



=== DOfW ===

Convert a week (i.e. a `%tw`-formatted value) into a date.

{{{
generate long date = dofw(week)
format date %td
}}}

----



=== DOfY ===

Convert a year (i.e. a `%ty`-formatted value) into a date.

{{{
generate long date = dofy(year)
format date %td
}}}

----



=== Dow ===

Extract the day of the week number (0 to 6; Sunday is 0) from a date (i.e. `%td`-formatted value).

{{{
generate byte day = dow(date)
}}}

----



=== Doy ===

Extract the day of the year number (1 to 366) from a date (i.e. `%td`-formatted value).

{{{
generate byte day = doy(date)
}}}

----



=== HalfYear ===

Extract the half year number (1 to 2) from a date (i.e. `%td`-formatted value).

{{{
generate byte halfyear = halfyear(date)
}}}

----



=== HOfD ===

Convert a date (i.e. a `%td`-formatted value) into the number of half years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int halfyears = hofd(date)
format halfyears %th
}}}

----



=== Hh ===

Extract the hours from a `%tc`-formatted datetime.

{{{
generate byte hours =hh(datetime)
}}}

----



=== HhC ===

Extract the hours from a `%tC`-formatted datetime.

{{{
generate byte hours =hhC(datetime)
}}}

----



=== Mm ===

Extract the minutes from a `%tc`-formatted datetime.

{{{
generate byte minutes = mm(datetime)
}}}

----



=== MmC ===

Extract the minutes from a `%tC`-formatted datetime.

{{{
generate byte minutes = mmC(datetime)
}}}

----



=== MOfD ===

Convert a date (i.e. a `%td`-formatted value) into the number of months since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int months = mofd(date)
format months %tm
}}}

----



=== Month ===

Extract the month number (1 to 12) from a date (i.e. `%td`-formatted value).

{{{
generate byte month = month(date)
}}}

----



=== QOfD ===

Convert a date (i.e. a `%td`-formatted value) into the number of quarters since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int quarters = qofd(date)
format quarters %tq
}}}

----



=== Quarter ===

Extract the quarter number (1 to 4) from a date (i.e. `%td`-formatted value).

{{{
generate byte quarter = quarter(date)
}}}

----




=== Ss ===

Extract the seconds from a `%tc`-formatted datetime.

{{{
generate byte seconds = ss(datetime)
}}}

----



=== SsC ===

Extract the seconds from a `%tC`-formatted datetime.

{{{
generate byte seconds = ssC(datetime)
}}}

----



=== Week ===

Extract the week number (1 to 52) from a date (i.e. `%td`-formatted value).

{{{
generate byte week = week(date)
}}}

----



=== WOfD ===

Convert a date (i.e. a `%td`-formatted value) into the number of weeks since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int weeks = wofd(date)
format weeks %tw
}}}

----



=== Year ===

Extract the year from a date (i.e. `%td`-formatted value).

{{{
generate byte year = year(date)
}}}

----



=== YOfD ===

Convert a date (i.e. a `%td`-formatted value) into the number of years since the Stata epoch (`01jan1960 00:00:00.000`).

{{{
generate int years = yofd(date)
format years %ty
}}}



----
CategoryRicottone