strptime                package:base                R Documentation

_D_a_t_e-_t_i_m_e _C_o_n_v_e_r_s_i_o_n _F_u_n_c_t_i_o_n_s _t_o _a_n_d _f_r_o_m _C_h_a_r_a_c_t_e_r

_D_e_s_c_r_i_p_t_i_o_n:

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

_U_s_a_g_e:

     ## S3 method for class 'POSIXct':
     format(x, format = "", tz = "", usetz = FALSE, ...)
     ## S3 method for class 'POSIXlt':
     format(x, format = "", usetz = FALSE, ...)

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

     strftime(x, format="", usetz = FALSE, ...)
     strptime(x, format, tz = "")

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

_A_r_g_u_m_e_n_t_s:

       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 string.  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.  If 'options("digits.secs")' is set,
          up to the specified number of digits will be printed for
          seconds.

     ...: 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 times, 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. Fractional
          seconds are allowed.

_D_e_t_a_i_l_s:

     'strftime' is an alias for 'format.POSIXlt', and 'format.POSIXct'
     first converts to class '"POSIXlt"' by calling 'as.POSIXlt'.  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 ISO C / POSIX standard for 'strftime' and are
     likely to be widely available.  Any character in the format string
     other than the '%' escape sequences is interpreted literally (and
     '%%' gives '%').

     '%_a' Abbreviated weekday name in the current locale.

     '%_A' Full weekday name in the current locale.

     '%_b' Abbreviated month name in the current locale.

     '%_B' Full month name in the current locale.

     '%_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 (but POSIX-compliant OSes will ignore 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 (or 68) are prefixed by 20 and 70-99 by 19.

     '%_Y' Year with century.

     '%_z' (output only.) Offset from Greenwich, so '-0800' is 8 hours
          west of Greenwich.

     '%_Z' (output only.) Time zone as a character string (empty if not
          available).

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

     Also defined in the current standards but less widely implemented
     (e.g. not for output on Windows) are

     '%_F' Equivalent to %Y-%m-%d (the ISO 8601 date format).

     '%_g' The last two digits of the week-based year (see '%V').

     '%_G' The week-based year (see '%V') as a decimal number.

     '%_u' Weekday as a decimal number (1-7, Monday is 1).

     '%_V' Week of the year as decimal number (00-53). If the week
          (starting on Monday) containing 1 January has four or more
          days in the new year, then it is considered week 1.
          Otherwise, it is the last week of the previous year, and the
          next week is week 1.

     Other format specifiers in common use include

     '%_D' Locale-specific date format such as '%m/%d/%y'.

     '%_k' The 24-hour clock time with single digits preceded by a
          blank.

     '%_l' The 12-hour clock time with single digits preceded by a
          blank.

     '%_n' Newline on output, arbitrary whitespace on input.

     '%_r' The 12-hour clock time (using the locale's AM or PM).

     '%_R' Equivalent to '%H:%M'.

     '%_t' Newline on output, arbitrary whitespace on input.

     '%_T' Equivalent to '%H:%M:%S'.

     For output there are also '%O[dHImMUVwWy]' which may emit numbers
     in an alternative locale-dependent format (e.g. roman numerals),
     and '%E[cCyYxX]' which can use an alternative 'era' (e.g. a
     different religious calendar).  Which of these are supported is
     OS-dependent.  Specific to R is '%OSn', which for output gives the
     seconds to '0 <= n <= 6' decimal places (and if '%OS' is not
     followed by a digit, it uses the setting of
     'getOption("digits.secs")', or if that is unset, 'n = 3').
     Further, for 'strptime' '%OS' will input seconds including
     fractional seconds.

     'ISOdatetime' and 'ISOdate' are convenience wrappers for
     'strptime', that differ only in their defaults and that 'ISOdate'
     sets a timezone.  (For dates without times is would be better to
     use the '"Date"' class.)

_V_a_l_u_e:

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

     'strptime' turns character representations into an object of class
     '"POSIXlt"'.  The timezone is used to set the 'isdst' component.

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

_N_o_t_e:

     The default formats follow the rules of the ISO 8601 international
     standard which expresses a day as '"2001-02-28"' 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 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.

     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.

     Remember that in most timezones some times do not occur and some
     occur twice because of transitions to/from summer time.  What
     happens in those cases is OS-specific.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     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.

_E_x_a_m_p_l_e_s:

     ## locale-specific version of date()
     format(Sys.time(), "%a %b %d %X %Y %Z")

     ## time to sub-second accuracy (if supported by the OS)
     format(Sys.time(), "%H:%M:%OS3")

     ## 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)
     strptime(x, "%m/%d/%y %H:%M:%S")

     ## time with fractional seconds
     z <- strptime("20/2/06 11:16:16.683", "%d/%m/%y %H:%M:%OS")
     z # prints without fractional seconds
     op <- options(digits.secs=3)
     z
     options(op)

