help for xdatelist                                               (Roger Newson)

Creating lists of numeric dates

xdatelist , first(string_date1) last(string_date2) [ unit(unit) nunits(#) s2(string_argument) ycutoff(#) format(%format) separator(separator_string) ]

where string_date1 and string_date2 are dates given in string format (as might appear in quotes in the first argument of the date() function), string_argument is a string (as might appear in quotes as the second argument to the date() function), and unit may be



xdatelist takes, as input, two string-format dates in string_date1 and string_date2. It returns, as output in r(numlist), a numeric list of dates, starting at the first date and increasing by steps of a specified size (measured in specified units) while remaining no greater than the second date. Optionally, xdatelist can also return, in r(strlist), a list of the same dates in string format. xdatelist is therefore an extended version of the datelist facility.


first(string_date1}) is the first date in the list, given in string format, eg first(01Jan2000). The string format must be acceptable to the date() function; see help for dates and times.

last(string_date2) is the latest date allowed in the list, given in string format. All numeric dates in the output list will be no greater than the numeric date implied by last().

unit(unit) is the unit in which the time between successive dates in the list is to be measured. If unit() is absent, then year is assumed.

nunits(#) is the number of the units specified by unit() between successive dates in the list.

s2(string_argument) is the s2 (or mask) string argument passed to the date() function for decoding the string dates first() and last(); see help for dates and times. Its value should be a permutation of D, M and [##]Y, eg "MDY" or "DM20Y". ##, if specified, indicates a default century for two-digit years. For instance, dm20y interprets "08/06/55" as 8 June, 2055. If s2() is absent, then it is set by default to "DMY".

ycutoff(#) is the y numeric argument passed to the date() function for decoding the string dates first() and last(); see help for dates and times. Its value should be an integer from 1000 to 9998 (but probably 2001 to 2099), specifying the handling of two-digit years. It denotes the largest year to be returned when a two-digit date is encountered. If it is absent, and there is no ## in the s2 option, then dates with a two-digit year are set to missing. This may cause xdatelist to fail.

format(%fmt) specifies that the list of dates in r(numlist) should also be created in string format, using the specified format, and the resulting list of string dates returned in the result r(strlist). If format() is not specified, then r(strlist) is not returned.

separator(separator_string) specifies a separator string used to separate the elements of the string-format date list in r(strlist). If format() is absent, then separator is ignored. If format() is present and separator() is absent, then the string dates in r(strlist) are separated by single spaces. The separator() option may be useful if the date format given by format() generates spaces between parts of a date.


xdatelist performs a similar task to the numlist command; see help for nlist. It is especially useful when the dates in a list are unequally spaced (in days), as happens when the dates are corresponding days of regularly-spaced months, quarters, years, or centuries. xdatelist was originally distributed via SSC under the name of datelist, but this name was adopted under Stata 8 to describe a numlist containing dates. The name xdatelist was then introduced for this program, because xdatelist provides an extended version of the official Stata datelist facility.


. xdatelist, fi(01Jan1901) la(01Jan2000)

. xdatelist, fi(01/01/1999) la(11/01/2000) s2(MDY) unit(month) nunit(2)

. xdatelist, fi(01Jan1990) la(01Oct2010) unit(quarter) format(%dDmCY) . return list

. xdatelist, fi(01Jan1990) la(01Oct2010) unit(quarter) format(%dD_m_CY) sep(,) . return list

Saved results

xdatelist saves the following results in r():

Macros r(numlist) list of numeric dates r(strlist) list of dates in string format

If format() is not specified, then r(strlist) is not returned.


Roger Newson, Imperial College London, UK. Email: r.newson@imperial.ac.uk

Also see

Manual: [R] Functions, [D] dates and times, [P] numlist. On-line: help for functions, dates and times, nlist, numlist, datelist