{smcl}
{.-}
help for {cmd:datelist} {right:(Roger Newson)}
{.-}

{title:Creating lists of numeric dates}

{p 8 27}
{cmd:datelist ,} {cmdab:f:irst}{cmd:(}{it:string_date1}{cmd:)} {cmdab:l:ast}{cmd:(}{it:string_date2}{cmd:)}
  [ {cmdab:u:nit}{cmd:(}{it:unit}{cmd:)} {cmdab:n:units}{cmd:(}{it:#}{cmd:)}
  {cmdab:s:2}{cmd:(}{it:string_argument}{cmd:)}
  {cmdab:y:cutoff}{cmd:(}{it:#}{cmd:)}
  {cmdab:fo:rmat}{cmd:(}{it:%format}{cmd:)} {cmdab:se:parator}{cmd:(}{it:separator_string}{cmd:)}
  ]

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

{p}
{cmd:century}|{cmd:year}|{cmd:quarter}|{cmd:month}|{cmd:week}|{cmd:day}

{title:Description}

{p}
{cmd:datelist} takes, as input, two string-format dates in {it:string_date1} and {it:string_date2}.
It returns, as output in {cmd: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, {cmd:datelist} can also return, in {cmd:r(strlist)}, a list of
the same dates in string format.

{title:Options}

{p 0 4}
{cmd:first(}{it:string_date1}}{cmd:)} is the first date in the list, given in string format,
eg {cmd:first(01Jan2000)}. The string format must be acceptable to the {cmd:date} function;
see {hi:[U] 16.3.3 Date functions}.

{p 0 4}
{cmd:last(}{it:string_date2}{cmd:)} 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 {cmd:last}.

{p 0 4}
{cmd:unit(}{it:unit}{cmd:)} is the unit in which the time between successive dates in the list
is to be measured. If {cmd:unit} is absent, then {cmd:year} is assumed.

{p 0 4}
{cmd:nunits(}{it:#}{cmd:} is the number of the units specified by {cmd:unit} between successive
dates in the list.

{p 0 4}
{cmd:s2(}{it:string_argument}{cmd:)} is the {it:s2} string argument passed to the {cmd:date}
function for decoding the string dates {cmd:first} and {cmd:last};
see {hi:[U] 16.3.3 Date functions}.
Its value should be a permutation of {hi:d}, {hi:m} and {hi:[##]y},
eg {hi:mdy} or {hi:dm20y}. {hi:##}, if specified, indicates a default century for two-digit
years. For instance, {hi:dm20y} interprets "08/06/55" as 8 June, 2055. If {hi:s2} is absent,
then it is set by default to {hi:dmy}.

{p 0 4}
{cmd:ycutoff(}{it:#}{cmd:)} is the {it:y} numeric argument passed to the {cmd:date} function
for decoding the string dates {cmd:first} and {cmd:last};
see {hi:[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 {hi:##} in the {cmd:s2} option, then dates with a two-digit
year are set to missing. This may cause {cmd:datelist} to fail.

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

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

{title:Remarks}

{p 0 0}
{cmd:datelist} performs a similar task to the {cmd:numlist} command; see help for {help 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.

{title:Examples}

{p 8 16}{inp:. datelist,fi(01Jan1901) la(01Jan2000)}{p_end}

{p 8 16}{inp:. datelist,fi(01/01/1999) la(11/01/2000) s2(mdy) unit(month) nunit(2)}{p_end}

{p 8 16}{inp:. datelist,fi(01Jan1990) la(01Oct2010) unit(quarter) format(%dDmCY)}{p_end}
{p 8 16}{inp:. return list}{p_end}

{p 8 16}{inp:. datelist,fi(01Jan1990) la(01Oct2010) unit(quarter) format(%dD_m_CY) sep(,)}{p_end}
{p 8 16}{inp:. return list}{p_end}

{title:Also see}

{p 0 21}
{bind: }Manual:  {hi:[U] 16.3.3 Date functions}, {hi:[U] 14.1.8 numlist}, {hi:[P] numlist}.
{p_end}
{p 0 21}
On-line:  help for {help functions}, {help nlist}, {help numlist}
{p_end}
