Integer based date class
IDateTime.RdClasses (IDate and ITime) with integer storage
for fast sorting and grouping.
IDate inherits from the base class Date; the main
difference is that the latter uses double storage, allowing e.g. for
fractional dates at the cost of storage & sorting inefficiency.
Using IDate, if sub-day granularity is needed, use a second
ITime column. IDateTime() facilitates building such
paired columns.
Lastly, there are date-time helpers for extracting parts of dates as
integers, for example the year (year()), month
(month()), or day in the month (mday()); see Usage and Examples.
Usage
as.IDate(x, ...)
# Default S3 method
as.IDate(x, ..., tz = attr(x, "tzone", exact=TRUE))
# S3 method for class 'Date'
as.IDate(x, ...)
# S3 method for class 'IDate'
as.Date(x, ...)
# S3 method for class 'IDate'
as.POSIXct(x, tz = "UTC", time = 0, ...)
# S3 method for class 'IDate'
round(x, digits = c("weeks", "months", "quarters","years"), ...)
as.ITime(x, ...)
# Default S3 method
as.ITime(x, ...)
# S3 method for class 'POSIXlt'
as.ITime(x, ms = 'truncate', ...)
# S3 method for class 'ITime'
round(x, digits = c("hours", "minutes"), ...)
# S3 method for class 'ITime'
trunc(x, units = c("hours", "minutes"), ...)
# S3 method for class 'ITime'
as.POSIXct(x, tz = "UTC", date = Sys.Date(), ...)
# S3 method for class 'ITime'
as.character(x, ...)
# S3 method for class 'ITime'
format(x, ...)
IDateTime(x, ...)
# Default S3 method
IDateTime(x, ...)
second(x)
minute(x)
hour(x)
yday(x)
wday(x)
mday(x)
week(x)
isoweek(x)
isoyear(x)
month(x)
quarter(x)
year(x)
yearmon(x)
yearqtr(x)Arguments
- x
an object
- ...
arguments to be passed to or from other methods. For
as.IDate.default, arguments are passed toas.Date. Foras.ITime.default, arguments are passed toas.POSIXlt.- tz
time zone (see
strptime).- date
date object convertible with
as.IDate.- time
time-of-day object convertible with
as.ITime.- digits
really
units; one of the units listed for rounding. May be abbreviated. Nameddigitsfor consistency with the S3 generic.- units
one of the units listed for truncating. May be abbreviated.
- ms
For
as.ITimemethods, what should be done with sub-second fractions of input? Valid values are'truncate'(floor),'nearest'(round), and'ceil'(ceiling). See Details.
Details
IDate is a date class derived from Date. It has the same
internal representation as the Date class, except the storage
mode is integer. IDate is a relatively simple wrapper, and it
should work in almost all situations as a replacement for
Date. The main limitations of integer storage are (1) fractional
dates are not supported (use IDateTime() instead) and (2) the
range of supported dates is bounded by .Machine$integer.max
dates away from January 1, 1970 (a rather impractical limitation as
these dates are roughly 6 million years in the future/past, but
consider this your caveat).
Functions that use Date objects generally work for
IDate objects. This package provides specific methods for
IDate objects for mean, cut, seq, c,
rep, and split to return an IDate object.
ITime is a time-of-day class stored as the integer number of
seconds in the day. as.ITime does not allow days longer than 24
hours. Because ITime is stored in seconds, you can add it to a
POSIXct object, but you should not add it to a Date
object.
For as.ITime, note that the string "24:00:00" is parsed as "00:00:00".
This is because the conversion uses as.POSIXct, which treats "24:00:00" as midnight of the next day.
This differs from ISO 8601 (which allows "24:00:00" to represent end-of-day), but aligns with POSIX standards.
To represent end-of-day intervals, use "23:59:59" or arithmetic (e.g., as.ITime("23:59:59") + 1L).
We also provide S3 methods to convert to and from Date and POSIXct.
ITime is time zone-agnostic. When converting ITime and
IDate to POSIXct with as.POSIXct, a time zone may be specified.
Inputs like '2018-05-15 12:34:56.789' are ambiguous from the perspective of an ITime object – the method of coercion of the 789 milliseconds is controlled by the ms argument to relevant methods. The default behavior (ms = 'truncate') is to use as.integer, which has the effect of truncating anything after the decimal. Alternatives are to round to the nearest integer (ms = 'nearest') or to round up (ms = 'ceil').
In as.POSIXct methods for ITime and IDate, the
second argument is required to be tz based on the generic
template, but to make converting easier, the second argument is
interpreted as a date instead of a time zone if it is of type
IDate or ITime. Therefore, you can use either of the
following: as.POSIXct(time, date) or as.POSIXct(date,
time).
IDateTime takes a date-time input and returns a data table with
columns date and time.
Using integer storage allows dates and/or times to be used as data table
keys. With positive integers with a range less than 100,000, grouping
and sorting is fast because radix sorting can be used (see
sort.list).
Several convenience functions like hour and quarter are
provided to group or extract by hour, month, and other date-time
intervals. as.POSIXlt is also useful. For example,
as.POSIXlt(x)$mon is the integer month. The R base convenience
functions weekdays, months, and quarters can also
be used, but these return character values, so they must be converted to
factors for use with data.table. isoweek is ISO 8601-consistent.
The round method for IDate's is useful for grouping and plotting.
It can round to weeks, months, quarters, and years. Similarly, the round
and trunc methods for ITime's are useful for grouping and plotting.
They can round or truncate to hours and minutes.
Note for ITime's with 30 seconds, rounding is inconsistent due to rounding off a 5.
See 'Details' in round for more information.
Functions like week() and isoweek() provide week numbering functionality.
week() computes completed or fractional weeks within the year,
while isoweek() calculates week numbers according to ISO 8601 standards,
which specify that the first week of the year is the one containing the first Thursday.
This convention ensures that week boundaries align consistently with year boundaries,
accounting for both year transitions and varying day counts per week.
Similarly, isoyear() returns the ISO 8601 year corresponding to the ISO week.
Value
For as.IDate, a class of IDate and Date with the
date stored as the number of days since some origin.
For as.ITime, a class of ITime
stored as the number of seconds in the day.
For IDateTime, a data table with columns idate and
itime in IDate and ITime format.
second, minute, hour, yday, wday,
mday, week, isoweek, isoyear, month, quarter,
and year return integer values
for second, minute, hour, day of year, day of week,
day of month, week, month, quarter, and year, respectively.
yearmon and yearqtr return double values representing
respectively year + (month-1) / 12 and year + (quarter-1) / 4.
second, minute, hour are taken directly from
the POSIXlt representation.
All other values are computed from the underlying integer representation
and comparable with the values of their POSIXlt representation
of x, with the notable difference that while yday, wday,
and mon are all 0-based, here they are 1-based.
References
G. Grothendieck and T. Petzoldt, “Date and Time Classes in R”, R News, vol. 4, no. 1, June 2004.
H. Wickham, https://gist.github.com/hadley/10238.
ISO 8601, https://www.iso.org/iso/home/standards/iso8601.htm
Examples
# create IDate:
(d <- as.IDate("2001-01-01"))
#> [1] "2001-01-01"
# S4 coercion also works
identical(as.IDate("2001-01-01"), methods::as("2001-01-01", "IDate"))
#> [1] TRUE
# create ITime:
(t <- as.ITime("10:45"))
#> [1] "10:45:00"
# S4 coercion also works
identical(as.ITime("10:45"), methods::as("10:45", "ITime"))
#> [1] TRUE
(t <- as.ITime("10:45:04"))
#> [1] "10:45:04"
(t <- as.ITime("10:45:04", format = "%H:%M:%S"))
#> [1] "10:45:04"
# "24:00:00" is parsed as "00:00:00"
as.ITime("24:00:00")
#> [1] "00:00:00"
# Workaround for end-of-day: add 1 second to "23:59:59"
as.ITime("23:59:59") + 1L
#> [1] "24:00:00"
as.POSIXct("2001-01-01") + as.ITime("10:45")
#> [1] "2001-01-01 10:45:00 UTC"
datetime <- seq(as.POSIXct("2001-01-01"), as.POSIXct("2001-01-03"), by = "5 hour")
(af <- data.table(IDateTime(datetime), a = rep(1:2, 5), key = c("a", "idate", "itime")))
#> Key: <a, idate, itime>
#> idate itime a
#> <IDat> <ITime> <int>
#> 1: 2001-01-01 00:00:00 1
#> 2: 2001-01-01 10:00:00 1
#> 3: 2001-01-01 20:00:00 1
#> 4: 2001-01-02 06:00:00 1
#> 5: 2001-01-02 16:00:00 1
#> 6: 2001-01-01 05:00:00 2
#> 7: 2001-01-01 15:00:00 2
#> 8: 2001-01-02 01:00:00 2
#> 9: 2001-01-02 11:00:00 2
#> 10: 2001-01-02 21:00:00 2
af[, mean(a), by = "itime"]
#> itime V1
#> <ITime> <num>
#> 1: 00:00:00 1
#> 2: 10:00:00 1
#> 3: 20:00:00 1
#> 4: 06:00:00 1
#> 5: 16:00:00 1
#> 6: 05:00:00 2
#> 7: 15:00:00 2
#> 8: 01:00:00 2
#> 9: 11:00:00 2
#> 10: 21:00:00 2
af[, mean(a), by = list(hour = hour(itime))]
#> hour V1
#> <int> <num>
#> 1: 0 1
#> 2: 10 1
#> 3: 20 1
#> 4: 6 1
#> 5: 16 1
#> 6: 5 2
#> 7: 15 2
#> 8: 1 2
#> 9: 11 2
#> 10: 21 2
af[, mean(a), by = list(wday = factor(weekdays(idate)))]
#> wday V1
#> <fctr> <num>
#> 1: Monday 1.4
#> 2: Tuesday 1.6
af[, mean(a), by = list(wday = wday(idate))]
#> wday V1
#> <int> <num>
#> 1: 2 1.4
#> 2: 3 1.6
as.POSIXct(af$idate)
#> [1] "2001-01-01 UTC" "2001-01-01 UTC" "2001-01-01 UTC" "2001-01-02 UTC"
#> [5] "2001-01-02 UTC" "2001-01-01 UTC" "2001-01-01 UTC" "2001-01-02 UTC"
#> [9] "2001-01-02 UTC" "2001-01-02 UTC"
as.POSIXct(af$idate, time = af$itime)
#> [1] "2001-01-01 00:00:00 UTC" "2001-01-01 10:00:00 UTC"
#> [3] "2001-01-01 20:00:00 UTC" "2001-01-02 06:00:00 UTC"
#> [5] "2001-01-02 16:00:00 UTC" "2001-01-01 05:00:00 UTC"
#> [7] "2001-01-01 15:00:00 UTC" "2001-01-02 01:00:00 UTC"
#> [9] "2001-01-02 11:00:00 UTC" "2001-01-02 21:00:00 UTC"
as.POSIXct(af$idate, af$itime)
#> [1] "2001-01-01 00:00:00 UTC" "2001-01-01 10:00:00 UTC"
#> [3] "2001-01-01 20:00:00 UTC" "2001-01-02 06:00:00 UTC"
#> [5] "2001-01-02 16:00:00 UTC" "2001-01-01 05:00:00 UTC"
#> [7] "2001-01-01 15:00:00 UTC" "2001-01-02 01:00:00 UTC"
#> [9] "2001-01-02 11:00:00 UTC" "2001-01-02 21:00:00 UTC"
as.POSIXct(af$idate, time = af$itime, tz = "GMT")
#> [1] "2001-01-01 00:00:00 GMT" "2001-01-01 10:00:00 GMT"
#> [3] "2001-01-01 20:00:00 GMT" "2001-01-02 06:00:00 GMT"
#> [5] "2001-01-02 16:00:00 GMT" "2001-01-01 05:00:00 GMT"
#> [7] "2001-01-01 15:00:00 GMT" "2001-01-02 01:00:00 GMT"
#> [9] "2001-01-02 11:00:00 GMT" "2001-01-02 21:00:00 GMT"
as.POSIXct(af$itime, af$idate)
#> [1] "2001-01-01 00:00:00 UTC" "2001-01-01 10:00:00 UTC"
#> [3] "2001-01-01 20:00:00 UTC" "2001-01-02 06:00:00 UTC"
#> [5] "2001-01-02 16:00:00 UTC" "2001-01-01 05:00:00 UTC"
#> [7] "2001-01-01 15:00:00 UTC" "2001-01-02 01:00:00 UTC"
#> [9] "2001-01-02 11:00:00 UTC" "2001-01-02 21:00:00 UTC"
as.POSIXct(af$itime) # uses today's date
#> [1] "2025-10-29 00:00:00 UTC" "2025-10-29 10:00:00 UTC"
#> [3] "2025-10-29 20:00:00 UTC" "2025-10-29 06:00:00 UTC"
#> [5] "2025-10-29 16:00:00 UTC" "2025-10-29 05:00:00 UTC"
#> [7] "2025-10-29 15:00:00 UTC" "2025-10-29 01:00:00 UTC"
#> [9] "2025-10-29 11:00:00 UTC" "2025-10-29 21:00:00 UTC"
(seqdates <- seq(as.IDate("2001-01-01"), as.IDate("2001-08-03"), by = "3 weeks"))
#> [1] "2001-01-01" "2001-01-22" "2001-02-12" "2001-03-05" "2001-03-26"
#> [6] "2001-04-16" "2001-05-07" "2001-05-28" "2001-06-18" "2001-07-09"
#> [11] "2001-07-30"
round(seqdates, "months")
#> [1] "2001-01-01" "2001-01-01" "2001-02-01" "2001-03-01" "2001-03-01"
#> [6] "2001-04-01" "2001-05-01" "2001-05-01" "2001-06-01" "2001-07-01"
#> [11] "2001-07-01"
(seqtimes <- seq(as.ITime("07:00"), as.ITime("08:00"), by = 20))
#> [1] "07:00:00" "07:00:20" "07:00:40" "07:01:00" "07:01:20" "07:01:40"
#> [7] "07:02:00" "07:02:20" "07:02:40" "07:03:00" "07:03:20" "07:03:40"
#> [13] "07:04:00" "07:04:20" "07:04:40" "07:05:00" "07:05:20" "07:05:40"
#> [19] "07:06:00" "07:06:20" "07:06:40" "07:07:00" "07:07:20" "07:07:40"
#> [25] "07:08:00" "07:08:20" "07:08:40" "07:09:00" "07:09:20" "07:09:40"
#> [31] "07:10:00" "07:10:20" "07:10:40" "07:11:00" "07:11:20" "07:11:40"
#> [37] "07:12:00" "07:12:20" "07:12:40" "07:13:00" "07:13:20" "07:13:40"
#> [43] "07:14:00" "07:14:20" "07:14:40" "07:15:00" "07:15:20" "07:15:40"
#> [49] "07:16:00" "07:16:20" "07:16:40" "07:17:00" "07:17:20" "07:17:40"
#> [55] "07:18:00" "07:18:20" "07:18:40" "07:19:00" "07:19:20" "07:19:40"
#> [61] "07:20:00" "07:20:20" "07:20:40" "07:21:00" "07:21:20" "07:21:40"
#> [67] "07:22:00" "07:22:20" "07:22:40" "07:23:00" "07:23:20" "07:23:40"
#> [73] "07:24:00" "07:24:20" "07:24:40" "07:25:00" "07:25:20" "07:25:40"
#> [79] "07:26:00" "07:26:20" "07:26:40" "07:27:00" "07:27:20" "07:27:40"
#> [85] "07:28:00" "07:28:20" "07:28:40" "07:29:00" "07:29:20" "07:29:40"
#> [91] "07:30:00" "07:30:20" "07:30:40" "07:31:00" "07:31:20" "07:31:40"
#> [97] "07:32:00" "07:32:20" "07:32:40" "07:33:00" "07:33:20" "07:33:40"
#> [103] "07:34:00" "07:34:20" "07:34:40" "07:35:00" "07:35:20" "07:35:40"
#> [109] "07:36:00" "07:36:20" "07:36:40" "07:37:00" "07:37:20" "07:37:40"
#> [115] "07:38:00" "07:38:20" "07:38:40" "07:39:00" "07:39:20" "07:39:40"
#> [121] "07:40:00" "07:40:20" "07:40:40" "07:41:00" "07:41:20" "07:41:40"
#> [127] "07:42:00" "07:42:20" "07:42:40" "07:43:00" "07:43:20" "07:43:40"
#> [133] "07:44:00" "07:44:20" "07:44:40" "07:45:00" "07:45:20" "07:45:40"
#> [139] "07:46:00" "07:46:20" "07:46:40" "07:47:00" "07:47:20" "07:47:40"
#> [145] "07:48:00" "07:48:20" "07:48:40" "07:49:00" "07:49:20" "07:49:40"
#> [151] "07:50:00" "07:50:20" "07:50:40" "07:51:00" "07:51:20" "07:51:40"
#> [157] "07:52:00" "07:52:20" "07:52:40" "07:53:00" "07:53:20" "07:53:40"
#> [163] "07:54:00" "07:54:20" "07:54:40" "07:55:00" "07:55:20" "07:55:40"
#> [169] "07:56:00" "07:56:20" "07:56:40" "07:57:00" "07:57:20" "07:57:40"
#> [175] "07:58:00" "07:58:20" "07:58:40" "07:59:00" "07:59:20" "07:59:40"
#> [181] "08:00:00"
round(seqtimes, "hours")
#> [1] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [7] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [13] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [19] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [25] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [31] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [37] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [43] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [49] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [55] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [61] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [67] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [73] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [79] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [85] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [91] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [97] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [103] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [109] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [115] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [121] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [127] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [133] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [139] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [145] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [151] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [157] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [163] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [169] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [175] "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00" "08:00:00"
#> [181] "08:00:00"
trunc(seqtimes, "hours")
#> [1] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [7] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [13] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [19] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [25] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [31] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [37] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [43] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [49] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [55] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [61] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [67] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [73] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [79] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [85] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [91] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [97] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [103] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [109] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [115] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [121] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [127] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [133] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [139] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [145] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [151] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [157] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [163] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [169] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [175] "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00" "07:00:00"
#> [181] "08:00:00"
# Examples for isoyear() and isoweek()
d1 = as.IDate("2019-12-30")
year(d1)
#> [1] 2019
isoweek(d1)
#> [1] 1
isoyear(d1)
#> [1] 2020
d2 = as.IDate("2016-01-01")
year(d2)
#> [1] 2016
isoweek(d2)
#> [1] 53
isoyear(d2)
#> [1] 2015