format.Date               package:base               R Documentation

Date Conversion Functions to and from Character

Description:

     Functions to convert between character representations and objects
     of class '"Date"' representing calendar dates.

Usage:

     as.Date(x, ...)
     ## S3 method for class 'character':
     as.Date(x, format = "", ...)
     ## S3 method for class 'numeric':
     as.Date(x, origin, ...)

     ## S3 method for class 'Date':
     format(x, ...)

     ## S3 method for class 'Date':
     as.character(x, ...)

Arguments:

       x: An object to be converted.

  format: A character string.  The default is '"%Y-%m-%d"'.  For
          details see 'strftime'.

  origin: a Date object, or something which can be coerced by
          'as.Date(origin, ...)' to such an object.

     ...: Further arguments to be passed from or to other methods,
          including 'format' for 'as.character' and 'as.Date' methods.

Details:

     The usual vector re-cycling rules are applied to 'x' and 'format'
     so the answer will be of length that of the longer of the vectors.

     Locale-specific conversions to and from character strings are used
     where appropriate and available.  This affects the names of the
     days and months.

     The 'as.Date' methods accept character strings, factors, logical
     'NA' and objects of classes '"POSIXlt"' and '"POSIXct"'.  (The
     last are converted to days by ignoring the time after midnight in
     the representation of the time in UTC.)  Also objects of class
     '"date"' (from package 'date' or 'survival') and '"dates"' (from
     package 'chron').  Character strings are processed as far as
     necessary for the format specified: any trailing characters are
     ignored.

     'as.Date' will accept numeric data (the number of days since an
     epoch), but _only_ if 'origin' is supplied.

     The 'format' and 'as.character' methods ignore any fractional part
     of the date.

Value:

     The 'format' and 'as.character' methods return a character vector
     representing the date.  'NA' dates are returned as
     'NA_character_'.

     The 'as.Date' methods return an object of class '"Date"'.

Note:

     The default formats follow the rules of the ISO 8601 international
     standard which expresses a day as '"2001-02-03"'.

     If the date string does not specify the date completely, the
     returned answer may be system-specific.  The most common behaviour
     is to assume that a missing year, month or day is the current one.
      If it specifies a date incorrectly, reliable implementations will
     give an error and the date is reported as 'NA'.  Unfortunately
     some common implementations (such as 'glibc') are unreliable and
     guess at the intended meaning.

     Years before 1CE (aka 1AD) will probably not be handled correctly.

References:

     International Organization for Standardization (2004, 1988, 1997,
     ...) _ISO 8601. Data elements and interchange formats -
     Information interchange - Representation of dates and times._ For
     links to versions available on-line see (at the time of writing)
     <URL: http://www.qsl.net/g1smd/isopdf.htm>; for information on the
     current official version, see <URL:
     http://www.iso.org/iso/en/prods-services/popstds/datesandtime.html>.

See Also:

     Date for details of the date class; 'locales' to query or set a
     locale.

     Your system's help pages on 'strftime' and 'strptime' to see how
     to specify their formats.

Examples:

     ## locale-specific version of the date
     format(Sys.Date(), "%a %b %d")

     ## read in date info in format 'ddmmmyyyy'
     ## This will give NA(s) in some locales; setting the C locale
     ## as in the commented lines will overcome this on most systems.
     ## lct <- Sys.getlocale("LC_TIME"); Sys.setlocale("LC_TIME", "C")
     x <- c("1jan1960", "2jan1960", "31mar1960", "30jul1960")
     z <- as.Date(x, "%d%b%Y")
     ## Sys.setlocale("LC_TIME", lct)
     z

     ## read in date/time info in format 'm/d/y'
     dates <- c("02/27/92", "02/27/92", "01/14/92", "02/28/92", "02/01/92")
     as.Date(dates, "%m/%d/%y")

     ## date given as number of days since 1900-01-01 (a date in 1989)
     as.Date(32768, origin="1900-01-01")

