% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/stamp.r
\name{stamp}
\alias{stamp}
\alias{stamp_date}
\alias{stamp_time}
\title{Format dates and times based on human-friendly templates}
\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)
}
\arguments{
\item{x}{a character vector of templates.}

\item{orders}{orders are sequences of formatting characters which might be
used for disambiguation. For example "ymd hms", "aym" etc. See
\code{\link[=guess_formats]{guess_formats()}} for a list of available formats.}

\item{locale}{locale in which \code{x} is encoded. On Linux-like systems use
\code{locale -a} in the terminal to list available locales.}

\item{quiet}{whether to output informative messages.}

\item{exact}{logical. If \code{TRUE}, the \code{orders} parameter is interpreted as an
exact \code{\link[base:strptime]{base::strptime()}} format and no format guessing is performed.}
}
\value{
a function to be applied on a vector of dates
}
\description{
Stamps are just like \code{\link[=format]{format()}}, but based on human-friendly
templates like "Recorded at 10 am, September 2002" or "Meeting, Sunday May
1, 2000, at 10:20 pm".
}
\details{
\code{stamp()} is a stamping function date-time templates mainly, though it
correctly handles all date and time formats as long as they are
unambiguous. \code{stamp_date()}, and \code{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 \code{\link{stamp_date}} and
\code{\link{stamp_time}}. The core function \code{stamp()} prioritizes longer date-time
formats.

If \code{x} is a vector of values \pkg{lubridate} will choose the format which
"fits" \code{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 \code{orders}
argument.
}
\examples{
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"))
}
\seealso{
\code{\link[=guess_formats]{guess_formats()}}, \code{\link[=parse_date_time]{parse_date_time()}}, \code{\link[=strptime]{strptime()}}
}
