Type: | Package |
Title: | Date/Time Classes Based on Jalali Calendar |
Version: | 0.2.1 |
Description: | Implements S3 classes for storing dates and date-times based on the Jalali calendar. The main design goal of 'shide' is consistency with base R's 'Date' and 'POSIXct'. It provide features such as: date-time parsing, formatting and arithmetic. |
License: | MIT + file LICENSE |
URL: | https://github.com/mmollayi/shide |
BugReports: | https://github.com/mmollayi/shide/issues |
Encoding: | UTF-8 |
RoxygenNote: | 7.3.1 |
LinkingTo: | cpp11, tzdb |
Depends: | R (≥ 4.3.0) |
Imports: | cli, methods, rlang, tzdb, vctrs |
Suggests: | covr, lubridate, pillar, testthat (≥ 3.0.0) |
Config/testthat/edition: | 3 |
NeedsCompilation: | yes |
Packaged: | 2024-07-19 12:27:56 UTC; mohsen |
Author: | Mohsen Mollayi [aut, cre, cph] |
Maintainer: | Mohsen Mollayi <mmollayi@gmail.com> |
Repository: | CRAN |
Date/Publication: | 2024-07-19 12:50:04 UTC |
shide: Date/Time Classes Based on Jalali Calendar
Description
Implements S3 classes for storing dates and date-times based on the Jalali calendar. The main design goal of 'shide' is consistency with base R's 'Date' and 'POSIXct'. It provide features such as: date-time parsing, formatting and arithmetic.
Author(s)
Maintainer: Mohsen Mollayi mmollayi@gmail.com [copyright holder]
See Also
Useful links:
Cast an object to a jdate
object
Description
A generic function that converts other date/time classes to jdate
.
Usage
as_jdate(x, ...)
Arguments
x |
A vector of |
... |
These dots are for future extensions and must be empty. |
Details
Unlike R's as.Date.POSIXct()
method, as_jdate
does not expose a time zone argument
and uses time zone attribute of input datetime object for conversion.
Value
A vector of jdate
objects with the same length as x.
Examples
as_jdate(as.Date("2023-12-12"))
as_jdate(jdatetime("1402-09-21 13:14:00", tzone = "Asia/Tehran"))
as_jdate(as.POSIXct("2023-12-12 13:14:00", tz = "Asia/Tehran"))
Cast an object to a jdatetime
object
Description
A generic function that converts other date/time classes to jdatetime
.
Usage
as_jdatetime(x, tzone, ...)
Arguments
x |
a vector of |
tzone |
A time zone name. |
... |
These dots are for future extensions and must be empty. |
Details
If tzone
is missing (default), time zone attribute of input object is used for conversion.
If the input object does not have time zone attribute (e.g. jdate
), and no value is supplied
for tzone
, local time zone is assumed for conversion.
Value
A vector of jdatetime
objects with the same length as x.
Examples
## The time will be set to midnight when converting from `jdate` or `Date`
as_jdatetime(jdate_now())
as_jdatetime(Sys.Date())
## We can change time zone of a `jdatetime` to a new time zone
as_jdatetime(jdatetime_now(tzone = "Iran"), tzone = "Asia/Tokyo")
Check an object for its class
Description
-
is_jdate()
checks whether an object is of classjdate
. -
is_jdatetime()
checks whether an object is of classjdatetime
.
Usage
is_jdate(x)
is_jdatetime(x)
Arguments
x |
An object to test. |
Value
TRUE
or FALSE
.
Examples
is_jdate(jdate_now() + 1) # TRUE
is_jdatetime(jdatetime_now() + as.difftime(2, units = "hours")) # TRUE
Jalali calendar dates
Description
jdate
is an S3 class for representing the Jalali calendar dates. It can be constructed
from character and numeric vectors.
Usage
jdate(x, ...)
## S3 method for class 'numeric'
jdate(x, ...)
## S3 method for class 'character'
jdate(x, format = NULL, ...)
Arguments
x |
A vector of numeric or character objects. |
... |
Arguments passed on to further methods. |
format |
Format argument for character method. |
Details
jdate
is stored internaly as a double vector and doesn't have any attributes.
Its value represents the count of days since the Unix epoch (a negative value
if it represents a date prior to the epoch). This implementation coincides
with the implementation of Date
class.
Value
A vector of jdate
objects.
Examples
jdate("1402-09-20")
jdate("1402/09/20", format = "%Y/%m/%d")
## Will replace invalid date format with NA
jdate("1402/09/20", format = "%Y-%m-%d")
## Invalid dates will be replaced with NA
jdate("1402-12-30")
## Jalali date corresponding to "1970-01-01"
jdate(0)
Construct Jalali date-time objects from individual components
Description
-
jdate_make()
creates ajdate
object from individual components. -
jdatetime_make()
creates ajdatetime
object from individual components.
Usage
jdate_make(year, month = 1L, day = 1L, ...)
jdatetime_make(
year,
month = 1L,
day = 1L,
hour = 0L,
minute = 0L,
second = 0L,
tzone = "",
...,
ambiguous = NULL
)
Arguments
year |
Numeric year. |
month |
Numeric month. |
day |
Numeric day. |
... |
These dots are for future extensions and must be empty. |
hour |
Numeric hour. |
minute |
Numeric minute. |
second |
Numeric second. |
tzone |
A time zone name. Default value represents local time zone. |
ambiguous |
Resolve ambiguous times that occur during a repeated interval (when the clock is adjusted backwards during the transition from DST to standard time). Possible values are:
If |
Details
Numeric components are recycled to their common size using tidyverse recycling rules.
Value
-
jdate_make()
A vector of jdate object. -
jdatetime_make()
A vector of jdatetime object.
Examples
## At least 'year' must be supplied
jdate_make(year = 1401)
## Components are recycled
jdatetime_make(year = 1399:1400, month = 12, day = c(30, 29), hour = 12, tzone = "UTC")
## resolve ambiguous time by choosing the later time instant
jdatetime_make(1401, 6, 30, 23, 0, 0, tzone = "Asia/Tehran", ambiguous = "latest")
Current Jalali date and datetime
Description
System representation of the current time as jdate and jdatetime.
Usage
jdate_now(tzone = "")
jdatetime_now(tzone = "")
Arguments
tzone |
Time zone to get the current time for. |
Value
-
jdate_now()
A jdate object. -
jdatetime_now()
A jdatetime object.
Examples
# Current Jalali date in the local time zone
jdate_now()
# Current Jalali date in a specified time zone
jdate_now("Asia/Tokyo")
# may be true or false
jdate_now("Asia/Tehran") == jdate_now("Asia/Tokyo")
# Current Jalali datetime in the local time zone
jdatetime_now()
Date-time based on the Jalali calendar
Description
jdatetime
is an S3 class for representing date-times with the Jalali calendar dates.
It can be constructed from character and numeric vectors.
Usage
jdatetime(x, tzone = "", ...)
## S3 method for class 'character'
jdatetime(x, tzone = "", format = NULL, ..., ambiguous = NULL)
Arguments
x |
A vector of numeric or character objects. |
tzone |
A time zone name. Default value represents local time zone. |
... |
Arguments passed on to further methods. |
format |
Format argument for character method. |
ambiguous |
Resolve ambiguous times that occur during a repeated interval (when the clock is adjusted backwards during the transition from DST to standard time). Possible values are:
If |
Details
jdatetime
is stored internally as a double vector and has a single
attribute: the timezone (tzone). Its value represents the count of seconds
since the Unix epoch (a negative value if it represents an instant prior to the epoch).
This implementation coincides with that of POSIXct
class, except that POSIXct
may not have tzone
attribute. But for jdatetime
, tzone
is not optional.
Value
A vector of jdatetime
objects.
Examples
## default time zone and format
jdatetime("1402-09-20 18:57:09")
jdatetime("1402/09/20 18:57:09", tzone = "UTC", format = "%Y/%m/%d %H:%M:%S")
## Will replace invalid format with NA
jdatetime("1402/09/20 18:57:09", format = "%Y-%m-%d %H:%M:%S")
## nonexistent time will be replaced with NA
jdatetime("1401-01-02 00:30:00", tzone = "Asia/Tehran")
## ambiguous time will be replaced with NA
jdatetime("1401-06-30 23:30:00", tzone = "Asia/Tehran", ambiguous = "NA")
## ambiguous time will resolve by choosing the later time instant
jdatetime("1401-06-30 23:30:00", tzone = "Asia/Tehran", ambiguous = "latest")
## Jalali date-time in Iran time zone, corresponding to Unix epoch
jdatetime(0, "Iran")
Generate regular sequences of Jalali dates
Description
The method for seq for objects of class jdate
.
Usage
## S3 method for class 'jdate'
seq(from, to, by, length.out = NULL, along.with = NULL, ...)
Arguments
from |
starting date. Required. |
to |
end date. Optional. |
by |
increment of the sequence. Optional. See ‘Details’. |
length.out |
integer, optional. Desired length of the sequence. |
along.with |
take the length from the length of this argument. |
... |
arguments passed to or from other methods. |
Details
by
can be specified in several ways:
A number, taken to be in days.
A object of class difftime.
A character string, containing one of "day", "week", "month", "quarter" or "year". This can optionally be preceded by a (positive or negative) integer and a space, or followed by "s".
Value
A vector of jdate
objects.
Comparison with seq.Date()
The source code of seq.jdate()
is a modified version of the code used in base::seq.Date()
.
But a few behaviors of the latter are changed:
In base R, invalid dates resolve by overflowing according to the number of days that the date is invalid by. But
seq.jdate()
resolves invalid dates by rolling forward to the first day of the next month.If usage of
to
andlength.out
results in a fractional sequence betweenfrom
andto
, base R keeps the fraction in the underlying data of the outputDate
object. But sincejdate
is built upon whole numbers, the fractional part is dropped in the output.
These differences are illustrated in the examples.
See Also
Examples
# by days
seq(jdate("1402-01-01"), jdate("1402-01-10"), 1)
# by 2 weeks
seq(jdate("1402-01-01"), jdate("1402-04-01"), "2 weeks")
# first days of years
seq(jdate("1390-01-01"), jdate("1399-01-01"), "years")
# by month
seq(jdate("1400-01-01"), by = "month", length.out = 12)
# quarters
seq(jdate("1400-01-01"), jdate("1403-01-01"), by = "quarter")
# fractional dates are allowed in `seq.Date()`, but not in `seq.jdate()`
unclass(seq(as.Date(0), as.Date(3), length.out = 3))
unclass(seq(jdate(0), jdate(2), length.out = 3))
# resloving strategy for invalid dates is different in 'seq.jdate()' compared to 'seq.Date()'
seq(as.Date("2021-01-31"), by = "months", length.out = 2)
seq(jdate("1402-06-31"), by = "6 months", length.out = 2)
Get/set the days components of Jalali date-time objects
Description
-
sh_day()
andsh_day<-()
retrieves and replaces the day of the month respectively. -
mday()
andmday<-()
are aliases forday()
andday<-()
. -
sh_wday()
retrieves the day of the week. -
sh_qday()
retrieves the day of the quarter. -
sh_yday()
retrieves the day of the year.
Usage
sh_day(x)
sh_mday(x)
sh_wday(x)
sh_qday(x)
sh_yday(x)
## S3 method for class 'jdate'
sh_day(x)
## S3 method for class 'jdatetime'
sh_day(x)
## S3 method for class 'jdate'
sh_wday(x)
## S3 method for class 'jdatetime'
sh_wday(x)
## S3 method for class 'jdate'
sh_qday(x)
## S3 method for class 'jdatetime'
sh_qday(x)
## S3 method for class 'jdate'
sh_yday(x)
## S3 method for class 'jdatetime'
sh_yday(x)
sh_day(x) <- value
sh_mday(x) <- value
## S3 replacement method for class 'jdate'
sh_day(x) <- value
## S3 replacement method for class 'jdatetime'
sh_day(x) <- value
Arguments
x |
A vector of |
value |
A numeric vector. |
Details
For assignment, x
and value
are recycled to their common size using
tidyverse recycling rules.
Value
The days component of x as an integer.
Examples
x <- jdate("1402-12-14")
sh_day(x)
sh_mday(x)
sh_qday(x)
sh_wday(x)
sh_yday(x)
sh_mday(x) <- 12:13
Get/set the time components of jdatetime
objects
Description
Get/set the time components of jdatetime
objects
Usage
sh_hour(x)
sh_minute(x)
sh_second(x)
## S3 method for class 'jdatetime'
sh_hour(x)
## S3 method for class 'jdatetime'
sh_minute(x)
## S3 method for class 'jdatetime'
sh_second(x)
sh_hour(x) <- value
sh_minute(x) <- value
sh_second(x) <- value
## S3 replacement method for class 'jdatetime'
sh_hour(x) <- value
## S3 replacement method for class 'jdatetime'
sh_minute(x) <- value
## S3 replacement method for class 'jdatetime'
sh_second(x) <- value
Arguments
x |
A vector of |
value |
A numeric vector. |
Details
For assignment, x
and value
are recycled to their common size using
tidyverse recycling rules.
Value
An integer vector representing the hour, minute or second component of x, depending on the function being called.
Examples
x <- jdatetime("1402-12-14 19:13:31")
sh_second(x)
sh_hour(x) <- 17:18
Get/set the month component of Jalali date-time objects
Description
Get/set the month component of Jalali date-time objects
Usage
sh_month(x)
## S3 method for class 'jdate'
sh_month(x)
## S3 method for class 'jdatetime'
sh_month(x)
sh_month(x) <- value
## S3 replacement method for class 'jdate'
sh_month(x) <- value
## S3 replacement method for class 'jdatetime'
sh_month(x) <- value
Arguments
x |
A vector of |
value |
A numeric vector. |
Details
For assignment, x
and value
are recycled to their common size using
tidyverse recycling rules.
Value
The month component of x as an integer.
Examples
x <- jdate("1402-12-14")
sh_month(x)
sh_month(x) <- 10:11
Get the quarter of Jalali date-time objects
Description
Get the quarter of Jalali date-time objects
Usage
sh_quarter(x)
Arguments
x |
A vector of |
Value
An integer vector of 1
to 4
.
Examples
x <- jdate("1402-12-14")
sh_quarter(x)
Round Jalali dates to a specific unit of time
Description
-
sh_floor()
takes ajdate
object and rounds it down to the previous unit of time. -
sh_ceiling()
takes ajdate
object and rounds it up to the next unit of time. -
sh_round()
takes ajdate
object and and rounds it up or down, depending on what is closer. For dates which are exactly halfway between two consecutive units, the convention is to round up.
Usage
sh_round(x, unit = NULL, ...)
sh_floor(x, unit = NULL, ...)
sh_ceiling(x, unit = NULL, ...)
Arguments
x |
A vector of |
unit |
A scalar character, containing a date unit or a multiple of a unit.
Valid date units are |
... |
These dots are for future extensions and must be empty. |
Value
A vector of jdate
objects with the same length as x.
See Also
Examples
x <- jdate("1402-12-15")
sh_floor(x, "year")
sh_floor(x, "2 months")
sh_ceiling(x, "year")
sh_round(x, "year")
sh_round(x, "week") == sh_floor(x, "week")
sh_round(x + 1, "week") == sh_ceiling(x, "week")
Get the time zone component of jdatetime
objects
Description
Get the time zone component of jdatetime
objects
Usage
sh_tzone(x)
## S3 method for class 'jdatetime'
sh_tzone(x)
Arguments
x |
A vector of |
Details
This function is only valid for jdatetime
objects. jdate
objects do not have time zone attribute.
Value
A character vector of length 1. An empty string represents the current local time zone.
Examples
x <- jdatetime("1402-12-14 19:13:31", tzone = "Iran")
sh_tzone(x)
Get/set the year component of Jalali date-time objects
Description
Get/set the year component of Jalali date-time objects
Usage
sh_year(x)
## S3 method for class 'jdate'
sh_year(x)
## S3 method for class 'jdatetime'
sh_year(x)
sh_year(x) <- value
## S3 replacement method for class 'jdate'
sh_year(x) <- value
## S3 replacement method for class 'jdatetime'
sh_year(x) <- value
Arguments
x |
A vector of |
value |
A numeric vector. |
Details
For assignment, x
and value
are recycled to their common size using
tidyverse recycling rules.
Value
The year component of x as an integer.
Examples
x <- jdate("1402-12-14")
sh_year(x)
sh_year(x) <- 1400:1401
Determine if a Jalali year is a leap year
Description
Check if an instant is in a leap year according to the Jalali calendar.
Usage
sh_year_is_leap(x)
Arguments
x |
A |
Value
TRUE
if in a leap year or FALSE
otherwise.
Examples
sh_year_is_leap(jdatetime("1399-01-01 00:00:00"))
x <- seq(jdate("1400-01-01"), by = "years", length.out = 10)
names(x) <- sh_year(x)
sh_year_is_leap(x)
Arithmetic operations for jdate
and jdatetime
Description
Arithmetic operations for jdate
and jdatetime
Usage
## S3 method for class 'jdate'
vec_arith(op, x, y, ...)
## S3 method for class 'jdatetime'
vec_arith(op, x, y, ...)
Arguments
op |
An arithmetic operator as a string. |
x , y |
A pair of vectors. |
... |
These dots are for future extensions and must be empty. |
Details
Supported operations:
Difference between two
jdate
objects results adifftime
object withunits = "days"
.Difference between two
jdatetime
objects results adifftime
object withunits = "seconds"
.A numeric vector can be added to or subtracted from a
jdate
orjdatetime
.A
difftime
vector can be added to or subtracted from ajdate
only if it has resolution bigger than "days".A
difftime
vector can be added to or subtracted from ajdatetime
.A
jdate
object can be subtracted from ajdatetime
and vice versa.
Value
The binary operator result of x
and y
. See
details for more information on operator behaviors.
Examples
jdatetime_now() - jdate_now()
jdate_now() - as.difftime(1, units ="weeks" ) - as.difftime(1, units = "days")
Coercion
Description
Double dispatch methods to support vctrs::vec_ptype2()
.
Usage
## S3 method for class 'jdate'
vec_ptype2(x, y, ..., x_arg = "", y_arg = "")
## S3 method for class 'jdatetime'
vec_ptype2(x, y, ..., x_arg = "", y_arg = "")
Arguments
x , y |
Vector types. |
... |
These dots are for future extensions and must be empty. |
x_arg , y_arg |
Argument names for |
Details
Coercion rules for jdate
and jdatetime
:
Combining a
jdate
andjdatetime
yields ajdatetime
.When combining two
jdatetime
objects, the timezone is taken from the first non-local timezone.
Value
An object prototype if x and y can be safely coerced to the same prototype;
otherwise it returns an error. See details for more information on
coercion hierarchy for jdate
and jdatetime
.
Examples
# jdate and jdatetime are compatible
c(jdate(), jdatetime(), jdatetime(tzone = "UTC"))
# jdate and Date are incompatible
try(c(jdate(), as.Date(NULL)))
Mathematical operations for jdate
and jdatetime
Description
Math and Summary group of functions for jdate
and jdatetime
objects.
Only methods for is.finite()
and is.infinite()
are provided and other functions from
the groups, such as mean()
, median()
and summary()
are not implemented.
Usage
## S3 method for class 'jdate'
vec_math(.fn, .x, ...)
## S3 method for class 'jdatetime'
vec_math(.fn, .x, ...)
Arguments
.fn |
A mathematical function from the base package, as a string. |
.x |
A vector of |
... |
Additional arguments passed to .fn. |
Details
vctrs
implementation of Date
and POSIXct
does not include methods for
is.finite()
and is.infinite()
. But these method are implemented in shide
so that jdate
and jdatetime
vectors could be used as ggplot
scales.
Value
For is.finite()
and is.infinite()
, a logical vector of the same length as x.
Using all the other math and summary group generics will signal an error.
Examples
# Unlike a `Date` vector, `mean()` is not defined for a `jdate` vector
try(mean(c(jdate_now(), jdate_now() + 2)))
Cast an object to a jdate
object
Description
Cast an object to a jdate
object
Usage
## S3 method for class 'jdate'
vec_cast(x, to, ...)
Arguments
x |
Vectors to cast. |
to |
Type to cast to. If |
... |
For |
Value
A vector of jdate
objects.
See Also
as_jdate is a convenience function that makes use of the casts that
are defined for vec_cast.jdate()
methods.
Cast an object to a jdatetime
object
Description
Cast an object to a jdatetime
object
Usage
## S3 method for class 'jdatetime'
vec_cast(x, to, ...)
Arguments
x |
Vectors to cast. |
to |
Type to cast to. If |
... |
For |
Value
A vector of jdatetime
objects.
See Also
as_jdatetime is a convenience function that makes use of the casts that
are defined for vec_cast.jdatetime()
methods.