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

<br><br><br>

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

<br><br><br>

Getting Started / Installation

<br>

1. Add JitPack Repository

For Groovy (settings.gradle):

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

<br><br>

For Kotlin DSL (settings.gradle.kts):

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

<br>

2. Add Library Dependency

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

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

<br><br>

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

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

<br><br><br>

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 |

<br><br><br>

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 |

<br><br><br>

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(); | سه شنبه |

<br><br><br>

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();