| Title: | Handling Jalali Date (Persian / Solar Hijri) |
|---|---|
| Description: | Jalali calendar, or solar Hijri, is calendar of Iran and Afghanistan (<https://en.wikipedia.org/wiki/Solar_Hijri_calendar>). This package is designed to working with Jalali date. For this purpose, It defines JalaliDate class that is similar to Date class. |
| Authors: | Hosein Rabiee [aut, cre, cph]
|
| Maintainer: | Hosein Rabiee <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.0 |
| Built: | 2025-03-11 05:01:12 UTC |
| Source: | https://github.com/cran/RJalaliDate |
Perform arithmetic operations
## S3 method for class 'JalaliDate' x - y## S3 method for class 'JalaliDate' x - y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x * y## S3 method for class 'JalaliDate' x * y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x / y## S3 method for class 'JalaliDate' x / y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x %*% y## S3 method for class 'JalaliDate' x %*% y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x %/% y## S3 method for class 'JalaliDate' x %/% y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x %% y## S3 method for class 'JalaliDate' x %% y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x ^ y## S3 method for class 'JalaliDate' x ^ y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
Perform arithmetic operations
## S3 method for class 'JalaliDate' x + y## S3 method for class 'JalaliDate' x + y
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
convert JalaliDate to character, Date, or list
## S3 method for class 'JalaliDate' as.character( x, format = "A", separator = jdate_options("DEFAULT_SEPARATOR"), ... ) ## S3 method for class 'JalaliDate' as.Date(x, ...) ## S3 method for class 'JalaliDate' as.list(x, ...)## S3 method for class 'JalaliDate' as.character( x, format = "A", separator = jdate_options("DEFAULT_SEPARATOR"), ... ) ## S3 method for class 'JalaliDate' as.Date(x, ...) ## S3 method for class 'JalaliDate' as.list(x, ...)
x |
JalaliDate object |
format |
character. One of c("A", "B", "C") elements:
|
separator |
character. One of VALID_SEPARATORS (see jdopt_get_options) that converts Jalali date elements to character |
... |
|
character, Date, or list
as.character(JalaliDate(1), separator= "+", VALID_SEPARATORS = c("+"))as.character(JalaliDate(1), separator= "+", VALID_SEPARATORS = c("+"))
change the Jalali date character separators. For invalid inputs, returns input without change
change_date_separator(date_char, new_separator, ...)change_date_separator(date_char, new_separator, ...)
date_char |
Jalali date (character) |
new_separator |
character (valid separator) |
... |
passing options ("MIN_YEAR" and/or "MAX_YEAR") to override package options (jdopt_get_options) |
Jalali date character
change_date_separator(c("1350/01/02", "14021220", "1402/1/40"), "+", VALID_SEPARATORS=c("+")) # [1] "1350+01+02" "1402+12+20" "1402/1/40"change_date_separator(c("1350/01/02", "14021220", "1402/1/40"), "+", VALID_SEPARATORS=c("+")) # [1] "1350+01+02" "1402+12+20" "1402/1/40"
calculate distance of two JalaliDate, that is, subtracts values of two JalaliDate and return
diffdate(x, y)diffdate(x, y)
x |
JalaliDate object |
y |
JalaliDate object |
double
x <- JalaliDate(c(1, 2)) y <- JalaliDate(c(10, 12, 13, 20, 50)) diffdate(x,y) # [1] -9 -10 NA NA NA # Warning message: # In diff.JalaliDate(x, y) : The length of two vectors aren't equal!x <- JalaliDate(c(1, 2)) y <- JalaliDate(c(10, 12, 13, 20, 50)) diffdate(x,y) # [1] -9 -10 NA NA NA # Warning message: # In diff.JalaliDate(x, y) : The length of two vectors aren't equal!
check if a Gregorian year is leap year
is_gregorian_leap_year(year)is_gregorian_leap_year(year)
year |
double |
logical
is_gregorian_leap_year(c(2000, 2001, 2002)) # [1] TRUE FALSE FALSEis_gregorian_leap_year(c(2000, 2001, 2002)) # [1] TRUE FALSE FALSE
check if a Jalali year is leap year
is_jalali_leap_year(year)is_jalali_leap_year(year)
year |
double |
for details of calculation see https://learn.microsoft.com/en-us/dotnet/fundamentals/runtime-libraries/system-globalization-persiancalendar
logical
is_jalali_leap_year(c(1402, 1403, 1404)) # [1] FALSE TRUE FALSEis_jalali_leap_year(c(1402, 1403, 1404)) # [1] FALSE TRUE FALSE
check validation of Jalali date elements and returns results
is_valid_date_elements(year, month, day, ...)is_valid_date_elements(year, month, day, ...)
year |
double |
month |
double |
day |
double |
... |
passing options ("MIN_YEAR" and/or "MAX_YEAR") to override package options (jdopt_get_options) |
type of message are:
"y": year is not valid
"m": month is not valid
"d1": day must be between 0 to 31
"d2": in the last 6 months of the year, the day should not be more than 30
"d3": in leap years, the day should not be 30
list of validation result and related message
is_valid_date_elements(c(1402, 1000), c(12, 13), c(10, 11), MIN_YEAR=100) # $result # [1] TRUE FALSE # # $message # [1] "" "m"is_valid_date_elements(c(1402, 1000), c(12, 13), c(10, 11), MIN_YEAR=100) # $result # [1] TRUE FALSE # # $message # [1] "" "m"
check validation of Jalali date in form of character and returns results
is_valid_jalali_date_char(date_char, return_all_assessment_data = TRUE, ...)is_valid_jalali_date_char(date_char, return_all_assessment_data = TRUE, ...)
date_char |
character |
return_all_assessment_data |
logical , if it is FALSE only return validation result (logical vector) |
... |
passing options ("MIN_YEAR" and/or "MAX_YEAR") to override package options (jdopt_get_options) |
list or logical, based on second argument
is_valid_jalali_date_char("1402/10/15", FALSE) # [1] TRUEis_valid_jalali_date_char("1402/10/15", FALSE) # [1] TRUE
Checks whether a separator can be among the set of valid separators
is_valid_separator(separator)is_valid_separator(separator)
separator |
character |
list of validation result and related message
is_valid_separator("+") # $result # [1] TRUE # # $message # [1] "" is_valid_separator("+/") # $result # [1] FALSE # # $message # [1] "The number of character of the separator must be 0 or 1!"is_valid_separator("+") # $result # [1] TRUE # # $message # [1] "" is_valid_separator("+/") # $result # [1] FALSE # # $message # [1] "The number of character of the separator must be 0 or 1!"
create a data.frame consists start and end days of a year weeks
jalali_year_weeks(year, ...)jalali_year_weeks(year, ...)
year |
double |
... |
passing options ("MIN_YEAR" and/or "MAX_YEAR") to override package options (jdopt_get_options) |
data.frame
jalali_year_weeks(1402) # week f l #1 1 1402/01/01 1402/01/04 #2 2 1402/01/05 1402/01/11 #.............................. #52 52 1402/12/19 1402/12/25 #53 53 1402/12/26 1402/12/29jalali_year_weeks(1402) # week f l #1 1 1402/01/01 1402/01/04 #2 2 1402/01/05 1402/01/11 #.............................. #52 52 1402/12/19 1402/12/25 #53 53 1402/12/26 1402/12/29
Creates an instance of JalaliDate object by S3 system.
JalaliDate(x, ...)JalaliDate(x, ...)
x |
object (double, integer, Date, character, list) list' argument could be named like JalaliDate(list(y=1375, m=1, d=2)) |
... |
... argument is used to pass options that overrides current options (see examples). |
JalaliDate object is designed as 'base::Date' to handle Jalali (solar Hijri) date that is calendar of Iran and Afghanistan. Like Date, the JalaliDate information is stored in the form of a 'double' and is converted to another data type when necessary using the corresponding algorithm. The base day (value = 0) is "1375/01/01". Calculation of leap year is like Microsoft .Net method (33 years cycles). If the argument value is not valid at the time of conversion, it will be replaced with NA and a message will be sent in this regard (see examples).
JalaliDate object
JalaliDate(c(1, NA_real_, 2)) # [1] "1375/01/02" NA "1375/01/03" JalaliDate(as.Date("2024-01-01")) # [1] "1402/10/11" JalaliDate(1.5) # [1] "1375/01/02" JalaliDate(c("1375/01/01", NA)) # [1] "1375/01/01" NA # with warning JalaliDate(c("1375/01/03", "1375/0201", "")) # [1] "1375/01/03" NA NA # Warning message: # NAs introduced by validation. # year is out of default options range (1200-1500) JalaliDate(list(9998,1,1)) # [1] NA # Warning message: # NAs introduced by validation. JalaliDate(c("1380/01/01", "9998/10/15"), MAX_YEAR=9999) # [1] "1380/01/01" "9998/10/15" tmp<- c("1375+01+01", "1390/02/02", "2000 02 02", "0100_02_02") JalaliDate(tmp, VALID_SEPARATORS=c("+", "_", " ", "/"), MAX_YEAR=9999, MIN_YEAR = 0) # [1] "1375/01/01" "1390/02/02" "2000/02/02" "0100/02/02"JalaliDate(c(1, NA_real_, 2)) # [1] "1375/01/02" NA "1375/01/03" JalaliDate(as.Date("2024-01-01")) # [1] "1402/10/11" JalaliDate(1.5) # [1] "1375/01/02" JalaliDate(c("1375/01/01", NA)) # [1] "1375/01/01" NA # with warning JalaliDate(c("1375/01/03", "1375/0201", "")) # [1] "1375/01/03" NA NA # Warning message: # NAs introduced by validation. # year is out of default options range (1200-1500) JalaliDate(list(9998,1,1)) # [1] NA # Warning message: # NAs introduced by validation. JalaliDate(c("1380/01/01", "9998/10/15"), MAX_YEAR=9999) # [1] "1380/01/01" "9998/10/15" tmp<- c("1375+01+01", "1390/02/02", "2000 02 02", "0100_02_02") JalaliDate(tmp, VALID_SEPARATORS=c("+", "_", " ", "/"), MAX_YEAR=9999, MIN_YEAR = 0) # [1] "1375/01/01" "1390/02/02" "2000/02/02" "0100/02/02"
get a list of the package options
jdopt_get_options()jdopt_get_options()
Package Options have four parts: DEFAULT_SEPARATOR, VALID_SEPARATORS, MIN_YEAR, and MAX_YEAR. Options are used in validation and type conversion. For example, if 'VALID_SEPARATORS' part of options include c("/", " "), validation of "1390-01-01" return FALSE, because separator of this Jalali date is "-" that does not belong to valid separators set. By default, the conversion of "1000/10/11" to JalaliDate would be failed, because year of Jalali date should be between 1200 and 1500. By setting 'DEFAULT_SEPARATOR' to "_", the result of conversion of JalaliDate(1) to character will be "1375_01_02".
options list that includes DEFAULT_SEPARATOR, VALID_SEPARATORS, MIN_YEAR, MAX_YEAR
jdopt_get_options() # $DEFAULT_SEPARATOR # [1] "/" # # $VALID_SEPARATORS # [1] "" "-" "/" # # $MIN_YEAR # [1] 1200 # # $MAX_YEAR # # [1] 1500jdopt_get_options() # $DEFAULT_SEPARATOR # [1] "/" # # $VALID_SEPARATORS # [1] "" "-" "/" # # $MIN_YEAR # [1] 1200 # # $MAX_YEAR # # [1] 1500
return options value to factory settings
jdopt_reset()jdopt_reset()
The initial values, or factory settings, are: DEFAULT_SEPARATOR = "/" , VALID_SEPARATORS = c("", "-", "/"), MIN_YEAR = 1200L, and MAX_YEAR = 1500L
options list that includes DEFAULT_SEPARATOR, VALID_SEPARATORS, MIN_YEAR, MAX_YEAR
res <- jdopt_reset() res #$DEFAULT_SEPARATOR #[1] "/" # #$VALID_SEPARATORS #[1] "" "-" "/" # #$MIN_YEAR #[1] 1200 # #$MAX_YEAR #[1] 1500res <- jdopt_reset() res #$DEFAULT_SEPARATOR #[1] "/" # #$VALID_SEPARATORS #[1] "" "-" "/" # #$MIN_YEAR #[1] 1200 # #$MAX_YEAR #[1] 1500
specifying one of valid separators as default separator
jdopt_set_default_separator(separator)jdopt_set_default_separator(separator)
separator |
character |
The default separator (where initially is "/") has several uses. For example, to print JalaliDate: JalaliDate(list(1375, 1, 2)) that display "1375/01/02". Selected separator must belong to 'VALID_SEPARATORS' set, otherwise an error would be raised.
options list that includes DEFAULT_SEPARATOR, VALID_SEPARATORS, MIN_YEAR, MAX_YEAR
JalaliDate(Sys.Date()) # [1] "1403/04/29" jdopt_set_default_separator("-") JalaliDate(Sys.Date()) # [1] "1403-04-29"JalaliDate(Sys.Date()) # [1] "1403/04/29" jdopt_set_default_separator("-") JalaliDate(Sys.Date()) # [1] "1403-04-29"
Determining the minimum and maximum valid value of Jalali date year
jdopt_set_min_max_year(min_year, max_year)jdopt_set_min_max_year(min_year, max_year)
min_year |
integer |
max_year |
integer |
'min_year' must be equal or lower than 'max_year' and both must be integer. Minimum value of 'min_year' is 0 and maximum value of 'max_year' is 9999.
options list that includes DEFAULT_SEPARATOR, VALID_SEPARATORS, MIN_YEAR, MAX_YEAR
JalaliDate(list(1000,1,1)) # [1] NA jdopt_set_min_max_year(100L, 2000L) JalaliDate(list(1000,1,1)) # [1] "1000/01/01"JalaliDate(list(1000,1,1)) # [1] NA jdopt_set_min_max_year(100L, 2000L) JalaliDate(list(1000,1,1)) # [1] "1000/01/01"
changing existing set of valid separators and defining a new set
jdopt_set_valid_separators(valid_separators)jdopt_set_valid_separators(valid_separators)
valid_separators |
character |
Argument of the function is a character vector that each of elements has length of 0 or 1. After changing 'VALID_SEPARATORS', if current 'DEFAULT_SEPARATOR' doesn't belong to new 'VALID_SEPARATORS', first element of new 'VALID_SEPARATORS' (after sorting) will be set as 'DEFAULT_SEPARATOR' and a message will be displayed.
options list or warning
jdopt_reset() res <- jdopt_set_valid_separators(c("+", "$")) #After setting new valid separators, the default separator was changed automatically! res # $DEFAULT_SEPARATOR # [1] "$" # # $VALID_SEPARATORS # [1] "$" "+" # # $MIN_YEAR # [1] 1200 # # $MAX_YEAR # [1] 1500jdopt_reset() res <- jdopt_set_valid_separators(c("+", "$")) #After setting new valid separators, the default separator was changed automatically! res # $DEFAULT_SEPARATOR # [1] "$" # # $VALID_SEPARATORS # [1] "$" "+" # # $MIN_YEAR # [1] 1200 # # $MAX_YEAR # [1] 1500
Perform arithmetic operations
Operators(x, y)Operators(x, y)
x |
JalaliDate or numeric |
y |
JalaliDate or numeric |
Only +, - operators work with JalaliDate objects in some cases. If each of the two arguments are JalaliDate, the '-' operator calculates the distance of two dates (see diffdate).
JalaliDate
JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30JalaliDate("1395/10/11") + 1 # [1] "1395/10/12" JalaliDate("1403/08/10") - 367 # [1] "1402/08/08" JalaliDate("1403/09/10") - JalaliDate("1403/08/10") # [1] 30
## S3 method for class 'JalaliDate' print(x, ...)## S3 method for class 'JalaliDate' print(x, ...)
x |
JalaliDate |
... |
for future usages |
display
print(JalaliDate(1)) # [1] "1375/01/02"print(JalaliDate(1)) # [1] "1375/01/02"
return JalaliDate object of today
today.JalaliDate()today.JalaliDate()
JalaliDate object
today.JalaliDate() # [1] "1403/04/31"today.JalaliDate() # [1] "1403/04/31"
return the day of week in Persian #'
## S3 method for class 'JalaliDate' weekdays(x, abbreviate = NULL)## S3 method for class 'JalaliDate' weekdays(x, abbreviate = NULL)
x |
JalaliDate object |
abbreviate |
not applicable in Persian language |
character
weekdays(JalaliDate(1)) #[1] `r stringi::stri_unescape_unicode("\u067E\u0646\u062C\u0020\u0634\u0646\u0628\u0647")`weekdays(JalaliDate(1)) #[1] `r stringi::stri_unescape_unicode("\u067E\u0646\u062C\u0020\u0634\u0646\u0628\u0647")`
It shows which week of the year the desired date is.
yearweek(x, ...)yearweek(x, ...)
x |
JalaliDate object |
... |
for future usage |
list of current and last week number and label
yearweek(JalaliDate(321)) # $week_number # [1] "47" # # $week_label # [1] "75W47" # # $last_week_number # [1] "46" # # $last_week_label # [1] "75W46"yearweek(JalaliDate(321)) # $week_number # [1] "47" # # $week_label # [1] "75W47" # # $last_week_number # [1] "46" # # $last_week_label # [1] "75W46"