help for datelist                                                (Roger Newson)

Creating lists of numeric dates

datelist , 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



datelist 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, datelist can also return, in r(strlist), a list of the same dates in string format.


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 [U] 16.3.3 Date functions.

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 string argument passed to the date function for decoding the string dates first and last; see [U] 16.3.3 Date functions. 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 [U] 16.3.3 Date functions. 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 datelist 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.


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


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

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

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

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

Also see

Manual: [U] 16.3.3 Date functions, [U] 14.1.8 numlist, [P] numlist. On-line: help for functions, nlist, numlist