Type: Package
Title: Convert Between Jalaali (Persian or Solar Hijri) and Gregorian Calendar Dates
Description: The Jalaali calendar, also known as the Persian or Solar Hijri calendar, is the official calendar of Iran and Afghanistan. It starts on Nowruz, the spring equinox, and follows an astronomical system for determining leap years. Each year consists of 365 or 366 days, divided into 12 months. This package provides functions for converting dates between the Jalaali and Gregorian calendars. The conversion calculations are based on the work of Kazimierz M. Borkowski (1996) (<doi:10.1007/BF00055188>), who used an analytical model of Earth's motion to compute equinoxes from AD 550 to 3800 and determine leap years based on Tehran time.
Version: 0.3.0
Date: 2025-03-20
Maintainer: Abdollah Jalilian <stat4aj@gmail.com>
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Encoding: UTF-8
RoxygenNote: 7.3.2
URL: https://github.com/jalilian/jalcal
BugReports: https://github.com/jalilian/jalcal/issues
NeedsCompilation: no
Packaged: 2025-03-21 01:16:29 UTC; aj
Author: Abdollah Jalilian ORCID iD [aut, cre], Kazimierz M. Borkowski [ctb]
Repository: CRAN
Date/Publication: 2025-03-28 11:40:16 UTC

Convert Gregorian Dates to Jalaali (Persian) Calendar

Description

This function converts a vector of Gregorian dates (in 'Date' format) to their corresponding Jalaali (Persian) calendar dates. It correctly handles leap years and determines the exact Jalaali year, month, and day for each input date.

Usage

greg2jal(dates)

Arguments

dates

A vector of class 'Date' representing the Gregorian dates to be converted.

Details

The Jalaali calendar is a solar calendar with an irregular leap year pattern. This function follows an algorithm based on equinox calculations to accurately determine the Jalaali date for each given Gregorian date.

**Conversion Process:** - The function first ensures that the input is of class 'Date'. - It estimates the Jalaali year by subtracting 621 from the Gregorian year. - Leap year information for relevant Jalaali years is obtained using 'jalLeap'. - The function then determines the first day of the Jalaali year in the Gregorian calendar. - Using cumulative day counts, it calculates the Jalaali month and day. - If the input date falls before the start of the Jalaali year (before March 21), an adjustment is made to account for the previous year.

The function efficiently handles both single and multiple date inputs, returning either a numeric vector (for a single date) or a well-structured data frame.

Value

A data frame with three columns:

Year

The corresponding Jalaali year.

Month

The corresponding Jalaali month.

Day

The corresponding Jalaali day.

If a single date is provided, a numeric vector of length 3 (Year, Month, Day) is returned.

See Also

- jalLeap for computing leap year information. - jal2greg for converting Jalaali dates to Gregorian dates

Examples

# Convert a single Gregorian date to Jalaali
greg2jal(as.Date("2024-03-21"))

# Convert multiple dates
greg2jal(as.Date(c("2024-03-21", "2024-04-10", "2025-01-01")))


Convert Jalaali (Persian) Calendar Date to Gregorian Calendar Date

Description

This function converts a date from the Jalaali (Persian) calendar to the Gregorian calendar. It supports both single date conversions and vectorized operations for multiple dates.

Usage

jal2greg(year, month, day)

Arguments

year

An integer or a vector of integers representing the Jalali year(s).

month

An integer or a vector of integers representing the Jalali month(s) (1-12).

day

An integer or a vector of integers representing the Jalali day(s) (1-31).

Details

The function first verifies that the input values are valid Jalali dates, ensuring that: - The 'year' values are finite integers. - The 'month' values range from 1 to 12. - The 'day' values are within valid ranges (1-31), considering month-specific limits.

The conversion is performed in two steps: 1. The function determines the Gregorian start date of the given Jalaali year using the 'jalLeap()' function. This function provides the corresponding Gregorian year and the day in March when the Jalaali year begins. 2. The exact Gregorian date is then calculated by adding the number of days elapsed since the start of the Jalaali year.

Value

A 'Date' object or a vector of 'Date' objects representing the corresponding Gregorian date(s). If any input value is invalid, 'NA' is returned for that entry.

See Also

- jalLeap for computing leap year information. - greg2jal for converting Jalaali dates to Gregorian dates

Examples

# Convert a single Jalaali date to Gregorian
jal2greg(1402, 1, 1)

# Convert multiple Jalaali dates to Gregorian
jal2greg(c(1403, 1404), c(12, 1), c(30, 1))


Determine Leap Year and First Day of Jalaali Year

Description

Based on the work by Kazimierz M. Borkowski (1996), this function determines whether a given Jalaali (Persian) year is a leap year and calculates the corresponding Gregorian year and the day in March when the Jalaali New Year (Nowruz) begins.

Usage

jalLeap(yearJ)

Arguments

yearJ

An integer representing the Jalaali (Persian) year.

Details

The Jalaali calendar is a solar calendar with an irregular leap year cycle, designed to align closely with the vernal equinox. Unlike the Gregorian calendar, which follows a fixed leap year rule, the Jalaali leap years are determined by a more complex astronomical system:

- A typical cycle lasts 33 years, with leap years occurring in years that leave a remainder of 1, 5, 9, 13, 17, 22, 26, or 30 when divided by 33. - The cycle is occasionally disrupted by "break years," which adjust for small differences between the astronomical year and the calculated calendar. - This function follows the leap year calculations and algorithm established by Kazimierz M. Borkowski (1996), who analysed equinox timings from AD 550 to 3800.

Value

A named list with the following elements:

leap

An integer: 0 if the Jalaali year is a leap year and 1, 2 or 3 if the Jallai year is a common year.

GregorianYear

The corresponding Gregorian year.

MarchDay

The Gregorian calendar day in March when the Jalaali year starts.

Author(s)

Abdollah Jalilian

References

- Borkowski, K. M. (1996). The Persian calendar for 3000 years. *Earth, Moon, and Planets*, 74, 223–230. [doi:10.1007/BF00055188](https://doi.org/10.1007/BF00055188)

Examples

# Check if 1403 is a leap year and get the start date of Nowruz
result <- jalLeap(1403)
print(result)