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

century|year|quarter|month|week|day

Description

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.

Options

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.

Remarks

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.

Examples

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

Author

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