formatDT: Converts date or datetime strings into alternate formats
In Smisc: Sego Miscellaneous

Description Usage Arguments Details Value Author(s) Examples

Can be used to convert date-time character vectors into other types of date-time formats. It is designed to automatically find the appropriate date and time informats without the user having to specify them.

1 2	formatDT(dt, date.outformat = NULL, time.outformat = NULL, posix = TRUE, weekday = FALSE)

`dt`	A character vector of date values or datetime values
`date.outformat`	A character string requesting the date format to be returned. The following date outformats are supported: "mm/dd/yyyy", "mm-dd-yyyy", "yyyy-mm-dd", "yyyymmdd", "ddmonyyyy", and "dd-mon-yyyy". If `date.outformat = NULL`, then "mm/dd/yyyy" is used.
`time.outformat`	A character string requesting the time format to be returned. The following time outformats are supported: "hh:mm:sspm", "hh:mm:ss pm", "hh:mm:ss", "hh:mmpm", "hh:mm pm", and "hh:mm". If `time.outformat = NULL`, then "hh:mm:ss pm" is used.
`posix`	`= TRUE` returns date and datetime vectors of class POSIXct that can be used for time calculations.
`weekday`	`= TRUE` returns a character vector denoting the day of the week.

If the input vector contains times, formatDT assumes that the dates and times are separated by at least one space. The date format and the time format of the input vector must be the same for all cells in the vector. The input format is determined by the first non-missing entry of the dt vector. Missing values (NA or "") are carried through to the output vectors without error.

In chosing the informat, formatDT first checks if the datetime string has a format of "dd/mm/yyyy hh:mm:ss pm". If so, it moves directly to the datetime conversions. Otherwise, it searches through the date and time informats listed below for a suitable match.

Acceptable date informats for dt: mm/dd/yyyy, mm-dd-yyyy, yyyy-mm-dd, yyyymmdd, ddmonyyyy, dd-mon-yyyy

Acceptable time informats for dt: hh:mm:sspm, hh:mm:ss pm, hh:mm:ss (24 hour time), hh:mmpm, hh:mm pm, hh:mm (24 hour time), hhmm (24 hour time), hhmmss (24 hour time)

A list with these components:

`date`	A character vector of the form requested by `date.outformat`.
`time`	A character vector of the form requested by `time.outformat` or an empty character vector of the form "" if the time is not present in the input vector `dt`.
`dt`	A character vector containing the combined datetime using the requested formats. If time is not present in the input vector `dt`, then simply the date is returned.
`date.posix`	A vector of class "POSIXt POSIXct" containing the date. This is only returned if `posix = TRUE`.
`dt.posix`	A vector of class "POSIXt POSIXct" containing the datetime. This is only returned if `posix = TRUE` and time values are present in the argument `dt`.
`weekday`	A character vector indicating the days of the week. This is only returned if `weekday = TRUE`.

Landon Sego

# Demonstrates conversion of different datetime informats
formatDT("03/12/2004 04:31:17pm", posix = FALSE)
formatDT("12Mar2004 04:31pm", posix = FALSE)
formatDT("2004-3-12 16:31:17", posix = FALSE)
formatDT("7-5-1998 22:13")

# Specifying different types of outformats
formatDT("03/12/2004", date.outformat = "dd-mon-yyyy", posix = FALSE)
formatDT("17-Sep-1782 12:31am", date.outformat = "yyyy-mm-dd",
         time.outformat = "hh:mm", posix = FALSE)

# Processing datetime vectors
formatDT(c("03/12/2004 04:31pm","03/12/2005 04:32:18pm"), posix = FALSE)
formatDT(c("03/12/2004 04:31:17pm","03/12/2005 04:32:18pm"))
formatDT(c("03/12/2004 04:31:17pm","03/12/2005 04:32:18pm"), weekday = TRUE)

# An incorrect date (will produce an error)
try(formatDT("29-Feb-2001"))

# An incorrect time will also produce an error
try(formatDT("28-Feb-2001 00:00:00 AM"))
formatDT("28-Feb-2001 12:00:00 AM")

# Illustrate the handling of missing values
formatDT(c(NA,"","2010-10-23 3:47PM"), weekday = TRUE)

$date
[1] "03/12/2004"

$time
[1] "04:31:17 PM"

$dt
[1] "03/12/2004 04:31:17 PM"

$date
[1] "03/12/2004"

$time
[1] "04:31:00 PM"

$dt
[1] "03/12/2004 04:31:00 PM"

$date
[1] "03/12/2004"

$time
[1] "04:31:17 PM"

$dt
[1] "03/12/2004 04:31:17 PM"

$date
[1] "07/05/1998"

$time
[1] "10:13:00 PM"

$dt
[1] "07/05/1998 10:13:00 PM"

$dt.posix
[1] "1998-07-05 22:13:00 UTC"

$date.posix
[1] "1998-07-05 UTC"

$date
[1] "12-Mar-2004"

$time
[1] ""

$dt
[1] "12-Mar-2004"

$date
[1] "1782-09-17"

$time
[1] "00:31"

$dt
[1] "1782-09-17 00:31"

$date
[1] "03/12/2004" "03/12/2005"

$time
[1] "04:31:00 PM" "04:32:18 PM"

$dt
[1] "03/12/2004 04:31:00 PM" "03/12/2005 04:32:18 PM"

$date
[1] "03/12/2004" "03/12/2005"

$time
[1] "04:31:17 PM" "04:32:18 PM"

$dt
[1] "03/12/2004 04:31:17 PM" "03/12/2005 04:32:18 PM"

$dt.posix
[1] "2004-03-12 16:31:17 UTC" "2005-03-12 16:32:18 UTC"

$date.posix
[1] "2004-03-12 UTC" "2005-03-12 UTC"

$date
[1] "03/12/2004" "03/12/2005"

$time
[1] "04:31:17 PM" "04:32:18 PM"

$dt
[1] "03/12/2004 04:31:17 PM" "03/12/2005 04:32:18 PM"

$dt.posix
[1] "2004-03-12 16:31:17 UTC" "2005-03-12 16:32:18 UTC"

$date.posix
[1] "2004-03-12 UTC" "2005-03-12 UTC"

$weekday
[1] "Friday"   "Saturday"

Error in formatDT("29-Feb-2001") : 
  The first non-missing date 29-Feb-2001 is incorrect or has an invalid format.

Error in formatDT("28-Feb-2001 00:00:00 AM") : 
  The first non-missing time 00:00:00 AM is incorrect or has an invalid format.

$date
[1] "02/28/2001"

$time
[1] "12:00:00 AM"

$dt
[1] "02/28/2001 12:00:00 AM"

$dt.posix
[1] "2001-02-28 UTC"

$date.posix
[1] "2001-02-28 UTC"

$date
[1] NA           ""           "10/23/2010"

$time
[1] NA            ""            "03:47:00 PM"

$dt
[1] NA                       ""                       "10/23/2010 03:47:00 PM"

$dt.posix
[1] NA                        NA                       
[3] "2010-10-23 15:47:00 UTC"

$date.posix
[1] NA               NA               "2010-10-23 UTC"

$weekday
[1] NA         ""         "Saturday"