stamp: Format dates and times based on human-friendly templates

Description

Stamps are just like format(), but based on human-friendly templates like "Recorded at 10 am, September 2002" or "Meeting, Sunday May 1, 2000, at 10:20 pm".

Usage

stamp(
  x,
  orders = lubridate_formats,
  locale = Sys.getlocale("LC_TIME"),
  quiet = FALSE,
  exact = FALSE
)
stamp_date(x, locale = Sys.getlocale("LC_TIME"), quiet = FALSE)
stamp_time(x, locale = Sys.getlocale("LC_TIME"), quiet = FALSE)

Value

a function to be applied on a vector of dates

Arguments

x: a character vector of templates.
orders: orders are sequences of formatting characters which might be used for disambiguation. For example "ymd hms", "aym" etc. See guess_formats() for a list of available formats.
locale: locale in which x is encoded. On Linux-like systems use locale -a in the terminal to list available locales.
quiet: whether to output informative messages.
exact: logical. If TRUE, the orders parameter is interpreted as an exact base::strptime() format and no format guessing is performed.

Details

stamp() is a stamping function date-time templates mainly, though it correctly handles all date and time formats as long as they are unambiguous. stamp_date(), and stamp_time() are the specialized stamps for dates and times (MHS). These function might be useful when the input template is unambiguous and matches both a time and a date format.

Lubridate tries hard to guess the formats, but often a given format can be interpreted in multiple ways. One way to deal with such cases is to provide unambiguous formats like 22/05/81 instead of 10/05/81 for d/m/y format. Another way is to use a more specialized stamp_date and stamp_time. The core function stamp() prioritizes longer date-time formats.

If x is a vector of values lubridate will choose the format which "fits" x the best. Note that longer formats are preferred. If you have "22:23:00 PM" then "HMSp" format will be given priority to shorter "HMS" order which also fits the supplied string.

Finally, you can give desired format order directly as orders argument.

Examples

Run this code

D <- ymd("2010-04-05") - days(1:5)
stamp("March 1, 1999")(D)
sf <- stamp("Created on Sunday, Jan 1, 1999 3:34 pm")
sf(D)
stamp("Jan 01")(D)
stamp("Sunday, May 1, 2000", locale = "C")(D)
stamp("Sun Aug 5")(D) #=> "Sun Aug 04" "Sat Aug 04" "Fri Aug 04" "Thu Aug 04" "Wed Aug 03"
stamp("12/31/99")(D)              #=> "06/09/11"
stamp("Sunday, May 1, 2000 22:10", locale = "C")(D)
stamp("2013-01-01T06:00:00Z")(D)
stamp("2013-01-01T00:00:00-06")(D)
stamp("2013-01-01T00:00:00-08:00")(force_tz(D, "America/Chicago"))