HijriCalendar

HijriCalendar is an Elixir library for converting between Gregorian dates and Islamic Hijri dates.

Current release focuses on:

• Date and DateTime conversion
• Hijri date representation and validation
• Month names
• Strategy-based calendar architecture

Installation

Add hijri_calendar to your dependencies in mix.exs:

def deps do
  [
    {:hijri_calendar, "~> 0.1.0"}
  ]
end

Quick start (iex)

From the project root:

iex -S mix

Then run:

HijriCalendar.today()
HijriCalendar.now()

gregorian = ~D[2026-08-10]
hijri = HijriCalendar.from_gregorian(gregorian)
HijriCalendar.to_gregorian(hijri)

datetime = DateTime.new!(~D[2026-08-10], ~T[15:45:00], "Etc/UTC")
HijriCalendar.from_datetime(datetime)
HijriCalendar.to_datetime(hijri)

HijriCalendar.month_name(9)

Public API

• HijriCalendar.today/0
• HijriCalendar.now/0
• HijriCalendar.from_gregorian/1
• HijriCalendar.from_gregorian/2
• HijriCalendar.from_datetime/1
• HijriCalendar.from_datetime/2
• HijriCalendar.to_gregorian/1
• HijriCalendar.to_gregorian/2
• HijriCalendar.to_datetime/1
• HijriCalendar.to_datetime/2
• HijriCalendar.month_name/1

Calendar strategies

The API supports strategy selection:

• :tabular
• :astronomical
• :umm_al_qura

Example:

gregorian = ~D[2026-08-10]

HijriCalendar.from_gregorian(gregorian, :tabular)
HijriCalendar.from_gregorian(gregorian, :astronomical)
HijriCalendar.from_gregorian(gregorian, :umm_al_qura)

Astronomical and UmmAlQura currently delegate to Tabular while keeping a clean extension boundary for future implementations.

Hijri date struct

%HijriCalendar.Date{year: 1448, month: 2, day: 25}

Use validated construction with:

HijriCalendar.Date.new(year, month, day)

Development

mix format
mix test
mix credo