README.md

# Persian (Solar Hijri) Calendar

This library implements the Solar Hijri calendar that is used in Iran and Afghanistan.

From [wikipedia](https://en.wikipedia.org/wiki/Solar_Hijri_calendar):

The Solar Hijri calendar (Persian: گاه‌شماری هجری خورشیدی‎, romanized: gāh-shomāri-ye hejri-ye khorshidi; Pashto: لمريز لېږدیز کلیز‎), also called the Solar Hejri calendar or Shamsi Hijri calendar, and abbreviated as SH, is the official calendar of Iran and Afghanistan. It begins on the March equinox (Nowruz) as determined by astronomical calculation for the Iran Standard Time meridian (52.5°E, UTC+03:30) and has years of 365 or 366 days.

Its determination of the start of each year is astronomically accurate year-to-year as opposed to the more fixed Gregorian calendar or "Common Era calendar" which, averaged out, has the same year length, achieving the same accuracy (a more simply patterned calendar of 365 days for three consecutive years plus an extra day in the next year, save for exceptions to the latter in three out of every four centuries). The start of the year and its number of days remain fixed to one of the two equinoxes, the astronomically important days which have the same duration of day as night. It results in less variability of all celestial bodies when comparing a specific calendar date from one year to others.[2]

Each of the twelve months corresponds with a zodiac sign. The first six months have 31 days, the next five have 30 days, and the last month has 29 days in usual years but 30 days in leap years. The New Year's Day always falls on the March equinox.

## Usage

[ex_cldr_calendars_persian](https://hex.pm/packages/ex_cldr_calenars_persian) conforms to both the `Calendar` and `Cldr.Calendar` behaviours and therefore the functions in the `Date`, `DateTime`, `NaiveDateTime`, `Time` and `Calendar` functions are supported.

For Elixir versions up to and including 1.9, a date can be created by:
```elixir
iex> {:ok, date} = Date.new(1354, 1, 1, Cldr.Calendar.Persian)
{:ok, ~D[1354-01-01 Cldr.Calendar.Persian]}
```
For Elixir version 1.10 and later `Sigil_D` supports user-defined calendars:
```
iex> ~D[1354-01-01 Cldr.Calendar.Persian]
~D[1354-01-01 Cldr.Calendar.Persian]
```

## Localization

`ex_cldr_calendars_persian` depends on [ex_cldr_calendars](https://hex.pm/packages/ex_cldr_calendars) which supports calendar localization. For full date and time formatting see [ex_cldr_dates_times](https://hex.pm/packages/ex_cldr_dates_times).

Basic localization is executed by the `Cldr.Calendar.localize/3`. For example:

```elixir
iex> Cldr.Calendar.localize(date, :month, locale: "en")
"Farvardin"

iex> Cldr.Calendar.localize(date, :month, locale: "fa")
"فروردین"

iex> Cldr.Calendar.localize(date, :day_of_week, locale: "fa")
"جمعه"

iex> Cldr.Calendar.localize(date, :day_of_week, locale: "en")
"Fri"
```

## Relationship to other libraries

This library is part of the [CLDR](https://cldr.unicode.org)-based libraries for Elixir including:

* [ex_cldr](https://hex.pm/packages/ex_cldr)
* [ex_cldr_numbers](https://hex.pm/packages/ex_cldr_numbers)
* [ex_cldr_dates_times](https://hex.pm/packages/ex_cldr_dates_times)
* [ex_cldr_units](https://hex.pm/packages/ex_cldr_units)
* [ex_cldr_lists](https://hex.pm/packages/ex_cldr_lists)
* [ex_cldr_messages](https://hex.pm/packages/ex_cldr_messages)
* [ex_cldr_calendars](https://hex.pm/packages/ex_cldr_calendars)
* [ex_cldr_currencies](https://hex.pm/packages/ex_cldr_currencies)

## Installation

The package can be installed by adding `cldr_calendars_persian` to your list of dependencies in `mix.exs`:

```elixir
def deps do
  [
    {:cldr_calendars_persian, "~> 0.1.0"}
  ]
end
```
Documentation can be found at [https://hexdocs.pm/cldr_calendars_persian](https://hexdocs.pm/cldr_calendars_persian).