HijrahDateTime

HijrahDateTime is a Kotlin Multiplatform library for working with the Hijrah calendar system. It provides a robust set of classes and functions to handle Hijrah dates and times across different platforms, integrating seamlessly with kotlinx-datetime and kotlinx-serialization.

Starting from version 2.0, this library has been rewritten as a Kotlin Multiplatform project, moving away from the previous java.time-only implementation to support a wider range of targets.

Experimental / Alpha Notice (2.0.0-alpha04)

This release is experimental and provided "as-is". It is published to Maven Central for early access and feedback. The API surface and behavior may change without notice, and edge cases are expected. If you plan to use it in production, please share your feedback and suggestions.

---

Features

• Kotlin Multiplatform: Supports JVM, iOS (Arm64, Simulator Arm64), and macOS (Arm64).
• Core Types: Includes HijrahDate, HijrahDateTime, HijrahYearMonth, and HijrahMonth.
• Arithmetic: Support for date/time arithmetic using plus and minus with DatePeriod and DateTimeUnit.
• Formatting & Parsing: Flexible formatting and parsing through HijrahDateTimeFormat and a DSL-based builder.
• Serialization: First-class support for kotlinx-serialization.
• Integration: Easy conversion to and from kotlinx-datetime types (LocalDate, LocalDateTime, Instant).
• Ranges & Progressions: Support for date ranges and progressions (e.g., date1..date2, date1 downTo date2).

---

Supported Platforms

• JVM (JDK 11+)
• Android (API 26+, JDK 11+)
• iOS (Arm64, Simulator Arm64)
• macOS (Arm64)

More targets may be added in the future.

---

Getting Started

Gradle

Add the dependency to your commonMain source set:

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.abdulrahman-b.hijrahdatetime:hijrahdatetime:2.0.0-alpha04")
        }
    }
}

---

Core Concepts

HijrahDate

Represents a date (year, month, day) in the Hijrah calendar.

// Create a HijrahDate
val date = HijrahDate(1446, 10, 12)

// Arithmetic
val tomorrow = date plusDays 1
val nextMonth = date plusMonths 1
val nextYear = date plusYears 1

// Convert to/from kotlinx-datetime.LocalDate
val localDate = date.toLocalDate()
val hijrahDate = localDate.toHijrahDate()

HijrahDateTime

Combines a HijrahDate with a LocalTime.

val dateTime = HijrahDateTime(1446, 10, 12, 12, 30, 0, 0)
println(dateTime.date) // 1446-10-12
println(dateTime.time) // 12:30:00

HijrahYearMonth

Represents a specific year and month in the Hijrah calendar.

val yearMonth = HijrahYearMonth(1446, HijrahMonth.RAMADAN)
println(yearMonth.numberOfDays) // Number of days in Ramadan 1446
val firstDay = yearMonth.firstDay
val lastDay = yearMonth.lastDay

---

Formatting and Parsing

You can use predefined formats or build your own using the DSL.

// Using predefined formats
val date = HijrahDate(1446, 10, 12)
val formatted = date.format(HijrahDateTimeFormats.DATE_ISO) // "1446-10-12"

// Using custom pattern
val customFormat = HijrahDateTimeFormat.ofPattern("yyyy/MM/dd")
val parsedDate = HijrahDate.parse("1446/10/12", customFormat)

// Using DSL builder
val dslFormat = buildDateTimeFormat {
    year()
    char('/')
    monthName(NameStyle.FULL)
    char('/')
    dayOfMonth()
}
println(date.format(dslFormat)) // "1446/Shawwal/12"

---

Serialization

Core types are annotated with @Serializable. You can use them directly in your serializable classes.

@Serializable
data class Event(
    val name: String,
    val date: HijrahDate
)

val json = Json.encodeToString(Event("Eid Al-Fitr", HijrahDate(1446, 10, 1)))

By default, it uses a component-based serializer. For ISO-string serialization, use HijrahDateIsoSerializer:

@Serializable
data class Event(
    @Serializable(with = HijrahDateIsoSerializer::class)
    val date: HijrahDate
)

---

Ranges and Progressions

val start = HijrahDate(1446, 9, 1)
val end = HijrahDate(1446, 9, 30)

// Range
val ramadan = start..end

// Progression
for (day in start..end) {
    println(day)
}

// DownTo
for (day in end downTo start) {
    println(day)
}

---

License

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

---

Support Me

If you'd like to support my work on this project, you can do so via PayPal. Your contributions are greatly appreciated!