grates (version 1.4.3)

isoweek_class: ISO Week class

Description

<grates_isoweek> objects are used to represent ISO week dates as defined in ISO 8601. To expand further, it is easiest to quote from the related wikipedia entry:

"ISO weeks start with Monday and end on Sunday. Each week's year is the Gregorian year in which the Thursday falls. The first week of the year, hence, always contains 4 January. ISO week year numbering therefore usually deviates by 1 from the Gregorian for some days close to 1 January."

Internally, <grates_isoweek> objects are stored as the number of weeks (starting at 0) from the first Monday prior to the Unix Epoch (1970-01-01). That is, the number of seven day periods from 1969-12-29.

Usage

isoweek(year = integer(), week = integer())
as_isoweek(x, ...)
# S3 method for default
as_isoweek(x, ...)
# S3 method for Date
as_isoweek(x, ...)
# S3 method for POSIXt
as_isoweek(x, ...)
# S3 method for character
as_isoweek(x, format, tryFormats = c("%Y-%m-%d", "%Y/%m/%d"), ...)
# S3 method for factor
as_isoweek(x, format, tryFormats = c("%Y-%m-%d", "%Y/%m/%d"), ...)
new_isoweek(x = integer())
is_isoweek(xx)

Value

A <grates_isoweek> object.

Arguments

year

[integer]

Vector representing the year associated with week.

double vectors will be converted via as.integer(floor(x)).

week

[integer]

Vector representing the week associated with `year.

double vectors will be converted via as.integer(floor(x)).

x, xx

R objects.

...

Other values passed to as.Date().

format

[character]

Passed to as.Date() unless format = "yearweek" in which case input is assumed to be in the form "YYYY-Wxx".

If not specified, it will try tryFormats one by one on the first non-NA element, and give an error if none works. Otherwise, the processing is via strptime() whose help page describes available conversion specifications.

tryFormats

[character]

Format strings to try if format is not specified.

Details

isoweek() is a constructor for <grates_isoweek> objects. It takes a vector of year and vector of week values as inputs. Length 1 inputs will be recycled to the length of the other input and double vectors will again be converted to integer via as.integer(floor(x)).

as_isoweek() is a generic for conversion to <grates_isoweek>.

• Date, POSIXct, and POSIXlt are converted with the timezone respected.

• Character objects are first coerced to date via as.Date() unless format = "yearweek" in which case input is assumed to be in the form "YYYY-Wxx" and parsed accordingly.

new_isoweek() is a minimal constructor for <grates_isoweek> objects aimed at developers. It takes, as input, the number of isoweeks since the Monday prior to the Unix Epoch that you wish to represent. double vectors will be converted to integer via as.integer(floor(x)).

References

Wikipedia contributors. (2025, January 15). ISO week date. In Wikipedia, The Free Encyclopedia. Retrieved 09:19, March 6, 2025, from https://en.wikipedia.org/w/index.php?title=ISO_week_date&oldid=1269568343

See Also

The yearweek and epiweek classes.

Examples

# date coercion
as_isoweek(Sys.Date())

# POSIXt coercion
as_isoweek(as.POSIXct("2019-03-04 01:01:01", tz = "America/New_York"))

# character coercion assumes date input by default
as_isoweek("2019-05-03")

# character coercion can handle YYYY-Www format too
as_isoweek("2019-W12", format = "yearweek")

# construction
isoweek(year = 2000, week = 3)

# direct construction
stopifnot(
    identical(
        new_isoweek(0:1),
        as_isoweek("1969-12-29") + 0:1
    )
)