strptime                package:base                R Documentation

Date-time Conversion Functions to and from Character

Description:

     Functions to convert between character representations and objects
     of classes `"POSIXlt"' and `"POSIXct"' representing calendar dates
     and times.

Usage:

     format.POSIXct(x, format = "", tz = "", usetz = FALSE, ...)
     format.POSIXlt(x, format = "", usetz = FALSE, ...)

     as.character(x, ...)

     strftime(x, format="%Y-%m-%d %X", usetz = FALSE, ...)
     strptime(x, format)

     ISOdatetime(year, month, day, hour, min, sec, tz = "")
     ISOdate(year, month, day, hour = 12, min = 0, sec = 0, tz = "GMT")

Arguments:

       x: An object to be converted.

      tz: A timezone specification to be used for the conversion.
          System-specific, but `""' is the current time zone, and
          `"GMT"' is UTC.

  format: A character vector. The default is `"%Y-%m-%d %H:%M:%S"' if
          any component has a time component which is not midnight, and
          `"%Y-%m-%d"' otherwise.

     ...: Further arguments to be passed from or to other methods.

   usetz: logical.  Should the timezone be appended to the output? This
          is used in printing time, and as a workaround for problems
          with using `"%Z"' on most Linux systems.

year, month, day: numerical values to specify a day.

hour, min, sec: numerical values for a time within a day.

Details:

     `strftime' is an alias for `format.POSIXlt', and `format.POSIXct'
     first converts to class `"POSIXct"' by calling `as.POSIXct'. Note
     that only that conversion depends on the time zone.

     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 AM/PM indicator (if used) and the separators
     in formats such as `%x' and `%X'.

     The details of the formats are system-specific, but the following
     are defined by the POSIX standard for `strftime' and are likely to
     be widely available.  Any character in the format string other
     than the `%' escapes is interpreted literally (and `%%' gives
     `%').

     `%a' Abbreviated weekday name.

     `%A' Full weekday name.

     `%b' Abbreviated month name.

     `%B' Full month name.

     `%c' Date and time, locale-specific.

     `%d' Day of the month as decimal number (01-31).

     `%H' Hours as decimal number (00-23).

     `%I' Hours as decimal number (01-12).

     `%j' Day of year as decimal number (001-366).

     `%m' Month as decimal number (01-12).

     `%M' Minute as decimal number (00-59).

     `%p' AM/PM indicator in the locale.  Used in conjuction with `%I'
          and not with `%H'.

     `%S' Second as decimal number (00-61), allowing for up to two
          leap-seconds.

     `%U' Week of the year as decimal number (00-53) using the first
          Sunday as day 1 of week 1.

     `%w' Weekday as decimal number (0-6, Sunday is 0).

     `%W' Week of the year as decimal number (00-53) using the first
          Monday as day 1 of week 1.

     `%x' Date, locale-specific.

     `%X' Time, locale-specific.

     `%y' Year without century (00-99). If you use this on input, which
          century you get is system-specific.  So don't!  Often values
          up to 69 are prefixed by 20 and 70-99 by 19.

     `%Y' Year with century.

     `%Z' (output only.) Time zone as a character string (empty if not
          available).  Note: do not use this on Linux unless the `TZ'
          environment variable is set.

     Where leading zeros are shown they will be used on output but are
     optional on input.

     `ISOdatetime' and `ISOdate' are convenience wrappers for
     `strptime', that differ only in their defaults.

Value:

     The `format' methods and `strftime' return character vectors
     representing the time.

     `strptime' turns character representations into an object of class
     `"POSIXlt"'.

     `ISOdatetime' and `ISOdate' return an object of class `"POSIXct"'.

Note:

     The default formats follow the rules of the ISO 8601 international
     standard which expresses a day as `"2001-02-03"' and a time as
     `"14:01:02"' using leading zeroes as here.  The ISO form uses no
     space to separate dates and times.

     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 unspecified seconds, minutes or hours are zero,
     and a missing year, month or day is the current one.

     If the timezone specified is invalid on your system, what happens
     is system-specific but it will probably be ignored.

     OS facilities will probably not print years before 1CE (aka 1AD)
     correctly.

References:

     International Organization for Standardization (1988, 1997, ...)
     ISO 8601. Data elements and interchange formats - Information
     interchange - Representation of dates and times. The 1997 version
     is available on-line at <URL:
     ftp://ftp.qsl.net/pub/g1smd/8601v03.pdf>

See Also:

     DateTimeClasses for details of the date-time classes; `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 date()
     format(Sys.time(), "%a %b %d %X %Y")
     ## we would include the timezone as in
     ## format(Sys.time(), "%a %b %d %X %Y %Z")
     ## but this crashes some Linux systems

     ## 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 <- strptime(x, "%d%b%Y")
     ## Sys.setlocale("LC_TIME", lct)
     z

     ## read in date/time info in format `m/d/y h:m:s'
     dates <- c("02/27/92", "02/27/92", "01/14/92",
                "02/28/92", "02/01/92")
     times <- c("23:03:20", "22:29:56", "01:03:30",
                "18:21:03", "16:56:26")
     x <- paste(dates, times)
     z <- strptime(x, "%m/%d/%y %H:%M:%S")
     z

