Format dates and times based on human-friendly templates

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

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

stamp_date(x, locale = Sys.getlocale("LC_TIME"))

stamp_time(x, locale = Sys.getlocale("LC_TIME"))

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.

Value

a function to be applied on a vector of dates

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 it's best to figure our the formats, but often a given format can be interpreted in several ways. One way to deal with the situation is to provide unambiguous formats like 22/05/81 instead of 10/05/81 if you want d/m/y format. Another option is to use a more specialized stamp_date and stamp_time. The core function stamp() give priority to longer date-time formats.

Another option is to provide a vector of several values as x parameter. Then 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.

See also

guess_formats, parse_date_time, strptime

Examples

D <- ymd("2010-04-05") - days(1:5)
stamp("March 1, 1999")(D)
#> Multiple formats matched: "%B %d, %Y"(1), "March %m, %Y"(1)
#> Using: "%B %d, %Y"
#> [1] "April 04, 2010" "April 03, 2010" "April 02, 2010" "April 01, 2010"
#> [5] "March 31, 2010"
sf <- stamp("Created on Sunday, Jan 1, 1999 3:34 pm")
#> Multiple formats matched: "Created on %A, %b %d, %Y %I:%M %p"(1), "Created on Sunday, %b %d, %Y %I:%M %p"(1), "Created on %A, %b %d, %Y %H:%M %Op"(0), "Created on Sunday, %b %d, %Y %H:%M %Op"(0)
#> Using: "Created on %A, %b %d, %Y %I:%M %p"
sf(D)
#> [1] "Created on Sunday, Apr 04, 2010 12:00 AM"   
#> [2] "Created on Saturday, Apr 03, 2010 12:00 AM" 
#> [3] "Created on Friday, Apr 02, 2010 12:00 AM"   
#> [4] "Created on Thursday, Apr 01, 2010 12:00 AM" 
#> [5] "Created on Wednesday, Mar 31, 2010 12:00 AM"
stamp("Jan 01")(D)
#> Multiple formats matched: "%b %d"(1), "Jan %H"(1), "Jan %m"(1), "Jan %y"(1), "%b %y"(0)
#> Using: "%b %d"
#> [1] "Apr 04" "Apr 03" "Apr 02" "Apr 01" "Mar 31"
stamp("Sunday, May 1, 2000", locale = "en_US")(D)
#> Multiple formats matched: "%A, %b %d, %Y"(1), "Sunday, %b %d, %Y"(1), "Sunday, May %m, %Y"(1), "%A, May %m, %Y"(0)
#> Using: "%A, %b %d, %Y"
#> [1] "Sunday, Apr 04, 2010"    "Saturday, Apr 03, 2010" 
#> [3] "Friday, Apr 02, 2010"    "Thursday, Apr 01, 2010" 
#> [5] "Wednesday, Mar 31, 2010"
stamp("Sun Aug 5")(D) #=> "Sun Aug 04" "Sat Aug 04" "Fri Aug 04" "Thu Aug 04" "Wed Aug 03"
#> Multiple formats matched: "%a %b %d"(1), "%a Aug %H"(1), "Sun %b %d"(1), "Sun Aug %H"(1), "Sun Aug %m"(1), "%a Aug %m"(0)
#> Using: "%a %b %d"
#> [1] "Sun Apr 04" "Sat Apr 03" "Fri Apr 02" "Thu Apr 01" "Wed Mar 31"
stamp("12/31/99")(D)              #=> "06/09/11"
#> Using: "%m/%d/%y"
#> [1] "04/04/10" "04/03/10" "04/02/10" "04/01/10" "03/31/10"
stamp("Sunday, May 1, 2000 22:10", locale = "en_US")(D)
#> Multiple formats matched: "%A, %b %d, %Y %H:%M"(1), "%A, May %m, %Y %d:%H"(1), "Sunday, %b %d, %Y %H:%M"(1), "Sunday, May %m, %Y %d:%H"(1)
#> Using: "%A, %b %d, %Y %H:%M"
#> [1] "Sunday, Apr 04, 2010 00:00"    "Saturday, Apr 03, 2010 00:00" 
#> [3] "Friday, Apr 02, 2010 00:00"    "Thursday, Apr 01, 2010 00:00" 
#> [5] "Wednesday, Mar 31, 2010 00:00"
stamp("2013-01-01T06:00:00Z")(D)
#> Multiple formats matched: "%Y-%Om-%dT%H:%M:%S%Ou"(1), "%Y-%m-%dT%H:%M:%S%Ou"(1), "%Y-%Om-%dT%H:%M:%SZ"(1), "%Y-%d-%OmT%H:%M:%SZ"(1), "%Y-%m-%dT%H:%M:%SZ"(1), "%Y-%d-%mT%H:%M:%SZ"(1)
#> Using: "%Y-%Om-%dT%H:%M:%S%Ou"
#> [1] "2010-04-04T00:00:00Z" "2010-04-03T00:00:00Z" "2010-04-02T00:00:00Z"
#> [4] "2010-04-01T00:00:00Z" "2010-03-31T00:00:00Z"
stamp("2013-01-01T00:00:00-06")(D)
#> Multiple formats matched: "%Y-%Om-%dT%H:%M:%S%Oo"(1), "%Y-%m-%dT%H:%M:%S%Oo"(1)
#> Using: "%Y-%Om-%dT%H:%M:%S%Oo"
#> [1] "2010-04-04T00:00:00-24" "2010-04-03T00:00:00-24" "2010-04-02T00:00:00-24"
#> [4] "2010-04-01T00:00:00-24" "2010-03-31T00:00:00-24"
stamp("2013-01-01T00:00:00-08:00")(force_tz(D, "America/Chicago"))
#> Multiple formats matched: "%Y-%Om-%dT%H:%M:%S%OO"(1), "%Y-%m-%dT%H:%M:%S%OO"(1)
#> Using: "%Y-%Om-%dT%H:%M:%S%OO"
#> [1] "2010-04-03T00:00:00-24:00" "2010-04-02T00:00:00-24:00"
#> [3] "2010-04-01T00:00:00-24:00" "2010-03-31T00:00:00-24:00"
#> [5] "2010-03-30T00:00:00-24:00"