format: Conversion between Objects of `tind` Class and Character Vectors

Description

format method converts objects of tind class to character vectors given format and locale information. strptind function accepts character vector with time indices and parses to create object of tind class.

Usage

# S3 method for tind
format(x, format, locale = NULL, ...)
strptind(x, format, locale = NULL, type = NULL, tz = NULL)

Value

strptime returns an object of tind class, format

returns a character vector.

Arguments

x: an object to be converted, a character vector for strptind, an object of tind class for format.
format: a character string or character vector determining string format(s) (see Details).
locale: a character value determining locale to be used for %a, %A, %b, %B, and %p specifiers (month names, weekday names, and AM/PM indicators) or NULL (default, interpreted as the current system locale), see calendar-names for information on locale settings.
...: (ignored) further arguments passed to or from other methods.
type: (optional) a character value determining time index type.
tz: (optional) a character value determining the time zone (the default NULL is interpreted as the system time zone). See tzone documentation for information on time zones.

Details

Names of accepted format specifiers except for %q are conformant with those used by format.Date, format.Date and strptime. Accepted specifiers are listed below:

%a: Abbreviated weekday name.
%A: Weekday name.
%b: Abbreviated month name.
%B: Month name.
%d: Day of month (01--31).
%e: Day of month (1--31) with a leading space for a single-digit number.
%D: American/C99 date representation %m/%d/%y.
%F: ISO 8601 date %Y-%m-%d.
%g: The last two digits of the week-based year.
%G: The week-based year.
%H: Hour (00--23).
%I: Hour, 12-hour clock (1--12).
%p: AM/PM indicator.
%j: Day of year (001--366).
%m: Month (01--12).
%M: Minute (00--59).
%n: Newline.
%OS[n]: Second with n (0--6) decimal places.
%OS: Second with up to 6 decimal places (automatically detected precision during parsing).
%q: (Not supported by base R.) Quarter (1--4).
%R: Same as %H:%M.
%S: Second (00--59), leap seconds are not accepted on input.
%t: Tab or whitespace.
%T: Same as %H:%M:%S.
%u: Weekday (1--7) with Monday as the first day in a week (ISO 8601).
%V: Week (01--53) as defined in ISO 8601.
%y: 2-digit year (00--99), values 00--68 are prefixed by 20 and 69--99 by 19.
%Y: 4-digit year (0--9999), 0 is allowed by ISO 8601.
%z: Signed offset in hours and minutes from UTC, accepted input formats are +-HHMM, +-HH, +-HH:MM, and letter Z for UTC.
%Z: Time zone abbreviation (also supported on input).

On very rare occasions (the need to use formats unsupported by strptind) users will have to call strptime and then as.tind method or perform some regex preprocessing before calling strptind.

type argument is optional as strptind automatically determines index type from components. However, it can be set as a safeguard against format misspecifications.

Examples

Run this code

## years
# four-digit year
(ti <- strptind(as.character(1998:2002), "%Y"))
format(ti, "%Y")
# two-digit year
(ti <- strptind(c("98", "99", "00", "01", "02"), "%y"))
format(ti, "%y")
# mixture of four-digit and two-digit years
strptind(c("1998", "1999", "00", "01", "02"), c("%Y", "%y"))

## quarters
(ti <- strptind(c("2020Q1", "2020Q2", "2020Q3", "2020Q4"), "%YQ%q"))
format(ti, "%YQ%q")
format(ti, "%Yq%q")
format(ti, "%Y.%q")

## months
(ti <- strptind(c("2020-03", "2020-06", "2020-09", "2020-12"), "%Y-%m"))
format(ti, "%Y-%m")
(ti <- strptind(c("03/20", "06/20", "09/20", "12/20"), "%m/%y"))
format(ti, "%m/%y")
format(ti, "%b '%y")

## weeks
(ti <- strptind(c("2020-W01", "2020-W05", "2020-W09", "2020-W13"), "%G-W%V"))
format(ti, "%G-W%V")
format(ti, "%G, week: %V")
strptind(c("2020, week: 13"), "%G, week: %V")

## dates
# ISO format
(ti <- strptind(c("2025-03-19", "2025-06-18", "2025-09-17", "2025-12-17"), "%F"))
format(ti, "%F")
strptind(c("2025-03-19", "2025-06-18", "2025-09-17", "2025-12-17"), "%Y-%m-%d")
format(ti, "%Y-%m-%d")
# US format
strptind(c("03/19/25", "06/18/25", "09/17/25", "12/17/25"), "%D")
format(ti, "%D")
strptind(c("03/19/25", "06/18/25", "09/17/25", "12/17/25"), "%m/%d/%y")
format(ti, "%m/%d/%y")
# European format
strptind(c("19.03.2025", "18.06.2025", "17.09.2025", "17.12.2025"), "%d.%m.%Y")
format(ti, "%d.%m.%Y")
# mixed formats
strptind(c("03/19/25", "06/18/25", "17.09.2025", "17.12.2025"),
         c("%m/%d/%y", "%d.%m.%Y"))
strptind(c("03/19/25", "06/18/25", "2025-09-17", "2025-12-17"),
         c("%D", "%F"))

## time of day
(ti <- strptind("13:03:34.534", "%H:%M:%OS"))
format(ti, "%H:%M:%OS3")
format(ti, "%H:%M:%OS2")
format(ti, "%H:%M:%OS1")
strptind("13:03:34", "%H:%M:%S")
format(ti, "%H:%M:%S")
strptind("13:03", "%H:%M")
format(ti, "%H:%M")
strptind("13", "%H")
format(ti, "%H")
strptind("01:03:44 pm", "%I:%M:%S %p")
format(ti, "%I:%M:%S %p")
strptind("1:03:44 pm", "%I:%M:%S %p")
strptind(c("1am", "1pm"), "%I%p")

## date-time
(ti <- strptind("2025-02-01 13:03:34.534", "%F %H:%M:%OS"))
format(ti, "%F %H:%M:%S")
format(ti, "%F %H:%M:%OS2")
format(ti, "%F %H:%M:%S%z")
format(ti, "%F %H:%M:%OS2 %Z")
strptind("02/01/25 01:03:34pm", "%D %I:%M:%OS%p")