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

century|year|quarter|month|week|day

Description

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.

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

Remarks

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.

Examples

        . 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