"POSIXlt"
and "POSIXct"
representing calendar
dates and times.
"format"(x, format = "", tz = "", usetz = FALSE, ...)
"format"(x, format = "", usetz = FALSE, ...)
"as.character"(x, ...)
strftime(x, format = "", tz = "", usetz = FALSE, ...)
strptime(x, format, tz = "")
strptime
, an object which can be converted to
"POSIXlt"
for strftime
.as.POSIXlt
), but
""
is the current time zone, and "GMT"
is UTC.
Invalid values are most commonly treated as UTC, on some platforms with
a warning.format
methods is
"%Y-%m-%d %H:%M:%S"
if any element 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."%Z"
.-45
and -045
. Years after 9999 and before -999 are normally printed with five or
more characters. Some platforms support modifiers from POSIX 2008 (and others). On
Linux the format "%04Y"
assures a minimum of four characters
and zero-padding. The internal code (as used on Windows and by
default on OS X) uses zero-padding by default, and formats
%_4Y
and %_Y
can be used for space padding and no
padding."POSIXct"
, but cause
difficulties as they often computed incorrectly. They conventionally have the opposite sign from time-zone
specifications (see Sys.timezone
): positive values are
East of the meridian. Although there have been time zones with
offsets like 00:09:21 (Paris in 1900), and 00:44:30 (Liberia until
1972), offsets are usually treated as whole numbers of minutes, and
are most often seen in RFC 822 email headers in forms like
-0800
(e.g., used on the Pacific coast of the US in winter). Format %z
can be used for input or output: it is a character
string, conventionally plus or minus followed by two digits for
hours and two for minutes: the standards say that an empty string
should be output if the offset is unknown, but some systems use the
offsets for the time zone in use for the current year.format
and as.character
methods and strftime
convert objects from the classes "POSIXlt"
and
"POSIXct"
to character vectors. strptime
converts character vectors to class "POSIXlt"
:
its input x
is first converted by as.character
.
Each input string is processed as far as necessary for the format
specified: any trailing characters are ignored.
strftime
is a wrapper for format.POSIXlt
, and it and
format.POSIXct
first convert to class "POSIXlt"
by
calling as.POSIXlt
(so they also work for class
"Date"
). 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 of the longer of these
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
, via the setting of the
LC_TIME
locale category. The current locale of
the descriptions might mean the locale in use at the start of the R
session or when these functions are first used.
The details of the formats are platform-specific, but the following are
likely to be widely available: most are defined by the POSIX standard.
A conversion specification is introduced by %
, usually
followed by a single letter or O
or E
and then a single
letter. Any character in the format string not part of a conversion
specification is interpreted literally (and %%
gives
%
). Widely implemented conversion specifications include
%a
%A
%b
%B
%c
"%a %b %e %H:%M:%S %Y"
on input.
%C
%d
%D
%m/%d/%y
: the C99
standard says it should be that exact format (but not all OSes
comply).
%e
%F
%g
%V
). (Accepted but ignored on input.)
%G
%V
) as a decimal
number. (Accepted but ignored on input.)
%h
%b
.
%H
%I
%j
%m
%M
%n
%p
%I
and not with %H
. An
empty string in some locales (and the behaviour is undefined if
used for input in such a locale). Some platforms accept %P
for output, which uses a lower-case
version: others will output P
.
%r
%R
%H:%M
.
%S
%t
%T
%H:%M:%S
.
%u
% see https://en.wikipedia.org/wiki/Week_number#Week_number
%U
%V
%w
%W
%x
"%y/%m/%d"
on input.
%X
"%H:%M:%S"
on input.
%y
%Y
0:9999
are accepted.
%z
-0800
is 8 hours behind UTC. Values up to
+1400
are accepted as from R 3.1.1: previous versions only
accepted up to +1200
. (Standard only for output.)%Z
Where leading zeros are shown they will be used on output but are
optional on input. Names are matched case-insensitively on input:
whether they are capitalized on output depends on the platform and the
locale. Note that abbreviated names are platform-specific (although
the standards specify that in the C locale they must be the
first three letters of the capitalized English name: this convention
is widely used in English-language locales but for example the French
month abbreviations are not the same on any two of Linux, OS X, Solaris
and Windows). Knowing what the abbreviations are is essential
if you wish to use %a
, %b
or %h
as part of an
input format: see the examples for how to check.
When %z
or %Z
is used for output with an
object with an assigned time zone an attempt is made to use the values
for that time zone --- but it is not guaranteed to succeed.
Not in the standards and less widely implemented are
%k
%l
%s
%+
%c
, often
"%a %b %e %H:%M:%S %Z %Y"
. May depend on the locale.
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. These are accepted for input, but with
the standard interpretation.
Specific to R is %OSn
, which for output gives the seconds
truncated 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 =
0
). Further, for strptime
%OS
will input seconds
including fractional seconds. Note that %S
does not read
fractional parts on output. =>
The behaviour of other conversion specifications (and even if other
character sequences commencing with %
are conversion
specifications) is system-specific. Some systems document that the
use of multi-byte characters in format
is unsupported: UTF-8
locales are unlikely to cause a problem.
The POSIX 1003.1 standard, which is in some respects stricter than ISO 8601.
Your system's help page on strftime
to see how to specify their
formats. (On some systems, including Windows, strftime
is
replaced by more comprehensive internal code.)