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