Skip to content

bahaar208/AfghanShamsiCalendar

BranchesTags

Repository files navigation

AfghanShamsiCalendar

AfghanShamsiCalendar is a professional, multilingual calendar library designed for Android applications that implements the Shamsi/Jalali (Afghan & Iranian) Solar Calendar system. It provides accurate conversion between Shamsi, Gregorian, and Hijri calendars, along with localized month and weekday names in Pashto, Persian (Dari), English, and Kurdish.

The library is designed with a clean and stable API, making it suitable for academic, commercial, and production-grade applications.

AfghanShamsiCalendar provides a comprehensive and flexible API with 65+ constructors and utility methods for full control over date calculations and conversions. AfghanShamsiCalendar allows developers to:

  • Initialize dates using Shamsi or Gregorian formats

  • Retrieve Shamsi, Gregorian, and Hijri dates

  • Access month and weekday names in multiple languages

  • Detect Shamsi leap years and calculate month lengths

  • Determine the first weekday of a Shamsi month




Key Capabilities

  • Accurate Shamsi (Afghan & Iranian) date calculations
  • Shamsi (Jalali) ↔ Gregorian ↔ Hijri (Islamic) conversions
  • Hijri date calculation
  • Localized month names (Afghan, Pashto, Persian, Kurdish, English)
  • Localized weekday names in multiple languages
  • Shamsi leap year detection
  • Month length calculation for Shamsi calendar
  • First weekday index of each Shamsi month
  • Clean, well-documented API
  • Compatible with Android projects




Getting Started / Installation


1. Add JitPack Repository

For Groovy (settings.gradle):

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url 'https://jitpack.io' }
    }
}



For Kotlin DSL (settings.gradle.kts):

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}

2. Add Library Dependency

For Groovy (build.gradle in :app module):

dependencies {
	        implementation 'com.github.bahaar208:AfghanShamsiCalendar:v1.0.0'
	}



For Kotlin DSL (build.gradle.kts in :app module):

dependencies {
	        implementation("com.github.bahaar208:AfghanShamsiCalendar:v1.0.0")
	}




AfghanShamsiCalendar API Reference

1. Constructors & Initialization

(Creating and initializing the calendar)

Constructor Description Example Output (e.g.)
AfghanShamsiCalendar() Initializes the calendar with the current system date in Shamsi. AfghanShamsiCalendar shamsiCalendar = new AfghanShamsiCalendar(); Current Shamsi date object. e.g. 2025-12-19
AfghanShamsiCalendar(int year, int month, int day) Initializes the calendar with a specific Gregorian date. AfghanShamsiCalendar shamsiCalendar = new AfghanShamsiCalendar(2026,2,18); Shamsi date object for 2026-2-18
AfghanShamsiCalendar(boolean isShamsi, int year, int month, int day) Initializes the calendar using a Shamsi date, based on the isShamsi flag. AfghanShamsiCalendar shamsiCalendar = new AfghanShamsiCalendar(true, 1404-10-30); Shamsi date object for 1404-10-30
AfghanShamsiCalendar(LocalDate gregorianDate) Initializes the calendar using a specific Gregorian date, automatically converting it to Shamsi. AfghanShamsiCalendar shamsiCalendar = new AfghanShamsiCalendar(LocalDate.of(2026,1,20)); Shamsi date object for equivalent Shamsi date
AfghanShamsiCalendar(LocalDate gregorianDate) Initializes the calendar using a Today's Gregorian date, automatically converting it to Shamsi. AfghanShamsiCalendar shamsiCalendar = new AfghanShamsiCalendar(LocalDate.now()); Shamsi date object for 1404-9-28




2. Date Setters & Mutators

(Updating Gregorian or Shamsi dates after initialization)

Method Description Example Output (e.g)
setGregorianDate(LocalDate date) Set Gregorian date using LocalDate shamsiCalendar.setGregorianDate(LocalDate.of(2026,1,20)); Shamsi: 1404-10-30
setGregorianDate(int year,int month,int day) Set Gregorian date using year, month, day shamsiCalendar.setGregorianDate(2026,1,20); Shamsi: 1404-10-30
setShamsiDate(int shYear,int shMonth,int shDay) Set Shamsi date shamsiCalendar.setShamsiDate(1404,10,30); Gregorian: 2026-1-20
setShYear(int year) Update Shamsi year shamsiCalendar.setShYear(1405); Shamsi: 1405-10-30
setShMonth(int month) Update Shamsi month shamsiCalendar.setShMonth(11); Shamsi: 1405-11-30
setShDay(int day) Update Shamsi day shamsiCalendar.setShDay(29); Shamsi: 1405-11-29




3. Calendar Structure & Leap Year Utilities

(Month length, leap year checks, and first-day-of-month calculations)

Method Description Example Output (e.g.)
isShamsiLeapYear() Returns true if the current Shamsi year is a leap year. shamsiCalendar.isShamsiLeapYear(); false
isShamsiLeapYear(int year) Returns true if the specified Shamsi year is a leap year. (Overloaded) shamsiCalendar.isShamsiLeapYear(1403); true
getAfghanMonthLength() Returns the number of days in the current Shamsi month. shamsiCalendar.getAfghanMonthLength(); 30
getAfghanMonthLength(int year, int month) Returns the number of days in a specific Shamsi month. (Overloaded) shamsiCalendar.getAfghanMonthLength(1404, 1); 31
getFirstWeekdayOfMonth() Returns the weekday name on which the current month starts. shamsiCalendar.getFirstWeekdayOfMonth(); دوشنبه
getDayOfWeek() Returns the number of leading empty days before the first day of the month. shamsiCalendar.getDayOfWeek(); 2
getWeekdayIndex() Returns the weekday index of the current day (Saturday = 0). shamsiCalendar.getWeekdayIndex(); 3
getWeekdayIndexOfFirstDay() Returns the weekday index of the first day of the month (Saturday = 0). shamsiCalendar.getWeekdayIndexOfFirstDay(); 2
getWeekdayName() Returns the weekday name of the current date. shamsiCalendar.getWeekdayName(); سه شنبه




4. Shamsi (Afghan) Date & Month Accessors

(Core Shamsi date values with Afghan/Dari and Pashto month names)

Method Description Example Output (e.g.)
getShamsiDate() Returns the full Shamsi date as a formatted string (yyyy-MM-dd). shamsiCalendar.getShamsiDate(); 1404-10-30
getShYear() Returns the Shamsi year. shamsiCalendar.getShYear(); 1404
getShMonth() Returns the Shamsi month number (1–12). shamsiCalendar.getShMonth(); 10
getShDay() Returns the Shamsi day of month. shamsiCalendar.getShDay(); 30
isShamsiLeapYear() Returns true if the current Shamsi year is a leap year. shamsiCalendar.isShamsiLeapYear(); false
isShamsiLeapYear(int year) Returns true if the specified Shamsi year is a leap year. (Overloaded) shamsiCalendar.isShamsiLeapYear(1403); true
getAfghanMonthLength() Returns number of days in the current Shamsi month. shamsiCalendar.getAfghanMonthLength(); 30
getAfghanMonthLength(int year, int month) Returns number of days in a specific Shamsi month. (Overloaded) shamsiCalendar.getAfghanMonthLength(1404, 1); 31
AfghanMonthName() Returns Afghan (Dari) month name in local script. shamsiCalendar.AfghanMonthName(); جدی
AfghanEnglishMonthName() Returns Afghan month name in English. shamsiCalendar.AfghanEnglishMonthName(); Jaddi
AfghanMonthNameByIndex(int index) Returns Afghan month name by index (1–12). shamsiCalendar.AfghanMonthNameByIndex(12); حوت
AfghanEnglishMonthNameByIndex(int index) Returns Afghan month name in English by index. shamsiCalendar.AfghanEnglishMonthNameByIndex(12); Huth
PashtoMonthName() Returns Pashto month name for current Shamsi month. shamsiCalendar.PashtoMonthName(); مرغومی
PashtoMonthEnglishName() Returns Pashto month name in English. shamsiCalendar.PashtoMonthEnglishName(); Marghomay
PashtoMonthNameByIndex(int index) Returns Pashto month name by index (1–12). shamsiCalendar.PashtoMonthNameByIndex(12); کب
PashtoMonthEnglishNameByIndex(int index) Returns Pashto month name in English by index. shamsiCalendar.PashtoMonthEnglishNameByIndex(12); Kab
setShYear(int year) Updates the Shamsi year while keeping the current month and day. shamsiCalendar.setShYear(1405); 1405-10-30
setShMonth(int month) Updates the Shamsi month while keeping the current year and day. shamsiCalendar.setShMonth(11); 1404-11-30
setShDay(int day) Updates the Shamsi day while keeping the current year and month. shamsiCalendar.setShDay(29); 1404-10-29




5. Gregorian Date Utilities

(Accessing and formatting Gregorian date information)

Method Description Example Output (e.g)
getGregorianDate() Returns LocalDate of Gregorian date shamsiCalendar.getGregorianDate(); 2026-1-20
getGrgYear() Returns Gregorian year shamsiCalendar.getGrgYear(); 2026
getGrgMonth() Returns Gregorian month shamsiCalendar.getGrgMonth(); 1
getGrgDay() Returns Gregorian day shamsiCalendar.getGrgDay(); 20
GregorianMonthName() Current Gregorian month name shamsiCalendar.GregorianMonthName(); January
GregorianMonthNameByIndex(int index) Gregorian month by index shamsiCalendar.GregorianMonthNameByIndex(12); December




6. Hijri (Islamic) Date & Month Methods

(Hijri date values and Arabic/English month names)

Method Description Example Output (e.g.)
getHijriDate() Returns the full Hijri date as a formatted string (yyyy-MM-dd). shamsiCalendar.getHijriDate(); 1447-8-1
getHijriYear() Returns the Hijri year. shamsiCalendar.getHijriYear(); 1447
getHijriMonth() Returns the Hijri month number (1–12). shamsiCalendar.getHijriMonth(); 8
getHijriDay() Returns the Hijri day of month. shamsiCalendar.getHijriDay(); 1
HijriArabicMonthName() Returns the Hijri month name in Arabic. shamsiCalendar.HijriArabicMonthName(); شَعْبَان
HijriEnglishMonthName() Returns the Hijri month name in English. shamsiCalendar.HijriEnglishMonthName(); Shaban
HijriArabicMonthNameByIndex(int index) Returns the Hijri month name in Arabic for a given index (1–12). shamsiCalendar.HijriArabicMonthNameByIndex(9); رَمَضَان
HijriEnglishMonthNameByIndex(int index) Returns the Hijri month name in English for a given index (1–12). shamsiCalendar.HijriEnglishMonthNameByIndex(9); Ramadan




7. Iranian (Persian) Shamsi Month Names

(Iranian calendar month names in Persian and English)

Method Description Example Output (e.g.)
ShamsiIranianPersianMonthName() Iranian Shamsi month in Persian shamsiCalendar.ShamsiIranianPersianMonthName(); دی
ShamsiIranianPersianMonthNameByIndex(int index) Iranian month Persian by index shamsiCalendar.ShamsiIranianPersianMonthNameByIndex(9); آذر
ShamsiIranianEnglishMonthName() Iranian Shamsi month in English shamsiCalendar.ShamsiIranianEnglishMonthName(); Dey
ShamsiIranianEnglishMonthNameByIndex(int index) Iranian month English by index shamsiCalendar.ShamsiIranianEnglishMonthNameByIndex(9); Azar




8. Kurdish Month Names

(Kurdish Sorani month names and English transliterations)

Method Description Example Output (e.g.)
KurdishMonthName() Kurdish Sorani month shamsiCalendar.KurdishMonthName(); بەفرانبار
KurdishMonthNameByIndex(int index) Kurdish month by index shamsiCalendar.KurdishMonthNameByIndex(12); ڕەشەمە
KurdishMonthEnglishName() Kurdish month in English shamsiCalendar.KurdishEnglishMonthName(); Befranbar
KurdishMonthEnglishNameByIndex(int index) Kurdish month English by index shamsiCalendar.KurdishEnglishMonthNameByIndex(12); Reshame




9. Weekday & Day Name Utilities

(Day names, weekday indexes, and month-start calculations)

Method Description Example Output (e.g.)
AfghanDayName() Day name in Afghan (Dari) shamsiCalendar.AfghanDayName(); سه‌شنبه
AfghanDayEnglishName() Day name in English (Dari) shamsiCalendar.AfghanDayEnglishName(); Seshanba
PashtoDayName() Day name in Pashto shamsiCalendar.AfghanDayName(); منځينۍ
PashtoDayEnglishName() Day name in English (Pashto) shamsiCalendar.AfghanDayEnglishName(); Manzinai
EnglishDayName() Weekday name in English shamsiCalendar.EnglishDayName(); Tuesday
PersainDayEnglishName() Persian day name in English shamsiCalendar.PersainDayEnglishName(); Seshanbe
KurdishDayName() Kurdish day name shamsiCalendar.KurdishDayName(); سێ شەممە
KurdishDayEnglishName() Kurdish day name in English shamsiCalendar.KurdishDayEnglishName(); Se Shamma
getWeekdayIndex() Returns index of current weekday shamsiCalendar.getWeekdayIndex(); 3
getWeekdayIndexOfFirstDay() Returns index of first day in the month shamsiCalendar.getWeekdayIndexOfFirstDay(); 2
getDayOfWeek() Returns the number of leading empty days before the first day of the month. shamsiCalendar.getDayOfWeek(); 2
getWeekdayName() Returns Shamsi weekday name shamsiCalendar.getWeekdayName(); سه‌شنبه
getFirstWeekdayOfMonth() Returns weekday name of first day of month shamsiCalendar.getFirstWeekdayOfMonth(); دوشنبه




Usage

Example I: Constructors

// ==================== Constructors ====================

// Initialize AfghanShamsiCalendar with default constructor (today's date)
AfghanShamsiCalendar shamsiCalendar = new AfghanShamsiCalendar(); 
// Example Output: Gregorian: 2025-12-19, Shamsi: 1404-9-28, Hijri: 1447-6-28

// OR initialize with current system date using LocalDate.now()
AfghanShamsiCalendar shamsiCalendar2 = new AfghanShamsiCalendar(LocalDate.now()); 
// Example Output: Gregorian: 2026-01-20, Shamsi: 1404-10-30, Hijri: 1447-8-1

// OR initialize with a specific Gregorian date
AfghanShamsiCalendar shamsiCalendar3 = new AfghanShamsiCalendar(LocalDate.of(2026, 1, 20)); 
// Output: Gregorian: 2026-01-20, Shamsi: 1404-10-30, Hijri: 1447-8-1

// OR initialize directly with a Shamsi date
AfghanShamsiCalendar shamsiCalendar4 = new AfghanShamsiCalendar(true, 1404, 10, 30); 
// Output: Gregorian: 2026-01-20, Shamsi: 1404-10-30, Hijri: 1447-8-1

// OR initialize with Gregorian year, month, day directly
AfghanShamsiCalendar shamsiCalendar5 = new AfghanShamsiCalendar(2026, 1, 20); 
// Output: Gregorian: 2026-01-20, Shamsi: 1404-10-30, Hijri: 1447-8-1




Example II: Weekday Names & Calendar Grid (Core Features)

// ==================== Weekday / Calendar Grid ====================

// Get the weekday name on which the current Shamsi month starts.
// This tells you which day the 1st of the month falls on.
String firstWeekdayName = shamsiCalendar.getFirstWeekdayOfMonth();   // Output: "دوشنبه/Monday"

// Get the number of leading empty days before the first day of the current Shamsi month.
// Example
// If the month starts on Monday, and the week starts from Saturday,
// then Saturday and Sunday come before Monday.
// These two days are considered empty cells in a calendar grid,
// so this method will return 2.
// (Very useful for building calendar grid UI layouts)
int leadingEmptyDays = shamsiCalendar.getDayOfWeek();   // Output: 2


// ==================== Weekday Index ====================

// Get the weekday index of the current day.
// Week index mapping:
// Saturday = 0, Sunday = 1, Monday = 2, ..., Friday = 6
// Useful for positioning the current day inside a week row.
int weekdayIndex = shamsiCalendar.getWeekdayIndex();   // Output: 3

// Get the weekday index of the first day of the current Shamsi month.
// Uses the same index mapping (Saturday = 0).
// Helpful for calculating where the month should start in a calendar grid.
int firstDayIndex = shamsiCalendar.getWeekdayIndexOfFirstDay();   // Output: 2


// ==================== Weekday Name ====================

// Get the weekday name of the current Shamsi date.
// Returns the localized weekday name (e.g., Pashto / Afghan format).
// Useful for headers, date labels, or detail views.
String weekdayName = shamsiCalendar.getWeekdayName();   // Output: "سه‌شنبه/Tuesday"



// ==================== Leap Year ====================

// Check if the current Shamsi year is a leap year.
// A leap year in Shamsi calendar affects the length of the last month (حوت).
boolean isCurrentLeap = shamsiCalendar.isShamsiLeapYear();   // Output: true / false

// Check if a specific Shamsi year is a leap year.
// Useful when calculating month lengths for past or future years.
boolean is1403Leap = shamsiCalendar.isShamsiLeapYear(1403);   // Output: true


// ==================== Afghan (Shamsi) Month Length ====================

// Get the number of days in the current Shamsi month.
// Automatically considers leap year rules if the month is the last month.
int currentMonthLength = shamsiCalendar.getAfghanMonthLength();   // Output: 30

// Get the number of days in a specific Shamsi month and year.
// Useful for generating full calendar views or validating dates.
int monthLength = shamsiCalendar.getAfghanMonthLength(1404, 1);   // Output: 31




Example III: Dates Conversions

// ==================== Get Dates ====================

String gregorian = shamsiCalendar.getGregorianDate().toString(); // Output: "2026-01-20"
String shamsi = shamsiCalendar.getShamsiDate(); // Output: "1404-10-30"
String hijri = shamsiCalendar.getHijriDate(); // Output: "1447-8-1"


// --- Gregorian ---
int grgYear = shamsiCalendar.getGrgYear();   // Output: 2026
int grgMonth = shamsiCalendar.getGrgMonth(); // Output: 1
int grgDay = shamsiCalendar.getGrgDay();     // Output: 20

// --- Shamsi ---
int shYear = shamsiCalendar.getShYear();   // Output: 1404
int shMonth = shamsiCalendar.getShMonth(); // Output: 10
int shDay = shamsiCalendar.getShDay();     // Output: 30

// --- Hijri ---
int hijriYear = shamsiCalendar.getHijriYear();   // Output: 1447
int hijriMonth = shamsiCalendar.getHijriMonth(); // Output: 8
int hijriDay = shamsiCalendar.getHijriDay();     // Output: 1




Example IV: Month Names

// ==================== Month Names ====================

// Get month names for each calendar (current date: 2026-01-20)
String gregorianMonth = shamsiCalendar.GregorianMonthName();        // Output: "January"
String afghanMonth = shamsiCalendar.AfghanMonthName();               // Output: "جدی"
String afghanMonthEnglish = shamsiCalendar.AfghanEnglishMonthName(); // Output: "Jaddi"
String shamsiMonthPashto = shamsiCalendar.PashtoMonthName();         // Output: "مرغومی"
String hijriMonthArabic = shamsiCalendar.HijriArabicMonthName();     // Output: "شَعْبَان"
String hijriMonthEnglish = shamsiCalendar.HijriEnglishMonthName();   // Output: "Shaaban"
String shamsiMonthEnglish = shamsiCalendar.PashtoMonthEnglishName(); // Output: "Marghomay"
String shamsiMonthPersian = shamsiCalendar.ShamsiIranianPersianMonthName(); // Output: "دی"
String shamsiMonthEnglishPersian = shamsiCalendar.ShamsiIranianEnglishMonthName(); // Output: "Dey"
String kurdishMonth = shamsiCalendar.KurdishMonthName();             // Output: "بەفرانبار"
String kurdishMonthEnglish = shamsiCalendar.KurdishEnglishMonthName(); // Output: "Befranbar"



// ---------------- By Index Methods ----------------

// Gregorian
String gregorianMonthByIndex = shamsiCalendar.GregorianMonthNameByIndex(3);   // Output: "March"

// Afghan
String afghanMonthByIndex = shamsiCalendar.AfghanMonthNameByIndex(1);           // Output: "حمل"
String afghanMonthEnglishByIndex = shamsiCalendar.AfghanEnglishMonthNameByIndex(1); // Output: "Hamal"

// Pashto (Shamsi)
String pashtoMonthByIndex = shamsiCalendar.PashtoMonthNameByIndex(2);           // Output: "غويی"
String pashtoMonthEnglishByIndex = shamsiCalendar.PashtoMonthEnglishNameByIndex(2); // Output: "Ghowai"

// Iranian (Persian)
String persianMonthByIndex = shamsiCalendar.ShamsiIranianPersianMonthNameByIndex(7);   // Output: "مهر"
String persianMonthEnglishByIndex = shamsiCalendar.ShamsiIranianEnglishMonthNameByIndex(7); // Output: "Mehr"

// Kurdish
String kurdishMonthByIndex = shamsiCalendar.KurdishMonthNameByIndex(2);       // Output: "گوڵان"
String kurdishMonthEnglishByIndex = shamsiCalendar.KurdishEnglishMonthNameByIndex(2); // Output: "Gulan"

// Hijri
String hijriMonthArabicByIndex = shamsiCalendar.HijriArabicMonthNameByIndex(1); // Output: "ٱلْمُحَرَّم"
String hijriMonthEnglishByIndex = shamsiCalendar.HijriEnglishMonthNameByIndex(1); // Output: "Muharam"




Example V: Weekdays in Multiple Languages

// // ==================== Weekdays in Multiple Languages ====================

// Get weekday names in different languages/localizations

// Get weekday name in Afghan (Pashto) script
String weekdayAfghan = shamsiCalendar.AfghanDayName(); // Output: "سه‌شنبه"

// Get weekday name in Afghan (Pashto) in English
String weekdayAfghanEnglish = shamsiCalendar.AfghanDayEnglishName(); // Output: "Seshanba"

// Get weekday name in English (Gregorian style)
String weekdayEnglish = shamsiCalendar.EnglishDayName(); // Output: "Tuesday"

// Get weekday name in Persian (English)
String weekdayPersianEnglish = shamsiCalendar.PersainDayEnglishName(); // Output: "Seshanbe"

// Get weekday name in Kurdish
String weekdayKurdish = shamsiCalendar.KurdishDayName(); // Output: "سێ شەممە"

// Get weekday name in Kurdish (English)
String weekdayKurdishEnglish = shamsiCalendar.KurdishDayEnglishName(); // Output: "Se Shamma"

// Get weekday name in Pashto
String weekdayPashto = shamsiCalendar.PashtoDayName(); // Output: "منځينۍ"

// Get weekday name in Pashto (English)
String weekdayPashtoEnglish = shamsiCalendar.PashtoDayEnglishName(); // Output: "Manzinai"




License

This project is licensed under the MIT License – see the LICENSE file for details.

About

A lightweight Shamsi/Jalali (Solar Hijri) calendar library supporting Afghan, Persian, Gregorian, and Hijri (Islamic) dates.

Topics

persian-calendar jalali-calendar date-conversion gregorian-calendar iranian-calendar afghan-calendar hijri-calendar islamic-calendar solar-calendar persian-date jalali-date kurdish-calendar afghan-shamsi-calendar afghan-persian-shamsi-jalali-date multilangual-calendar calendar-library-android-library shamsi-gregorian-hijri-convertor pashto-persian-english-kurdish afghan-solar-calendar iranian-persian-date

Resources

Readme

License

MIT license
Activity

Stars

14 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

AfghanShamsiCalendar v1.0.0 – Initial Release Latest
Dec 18, 2025

Packages

 
 
 

Contributors

Languages