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

## 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")

Arguments

Details

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.

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

There are also %O[dHImMSUVwWy] which may emit numbers in an alternative local-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.

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

Value

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

Note

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.

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 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 %Z")

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