Add support for ordinal day formatting

[mustafadakhel]

Hi! Thanks to everyone for all the great work on this library.

I have been trying to use the formatting system in a private project and i noticed that there is currently no way to format the day-of-month as an ordinal (for example "1st", "2nd", "3rd", ..) or as a full string ordinal in other languages (for example Arabic "الأول", "الثاني", ..).

Use Case

Some applications need to display dates with ordinal formatting like "January 1st, 2024", "March 22nd, 2024" in English, or "الأول من يناير" in Arabic. This is particularly useful for legal/formal documents, editorial logs, or any applications requiring a more natural date representation.

Current Workarounds

Right now we have two problematic workarounds:

Breaking isolation by exposing date values

fun LocalDate.formatWithOrdinal(): String {
    val dateFormat = LocalDate.Formats.ordinalShort { dayOfMonth }
    return dateFormat.format(this)
}

fun LocalDate.Formats.ordinalShort(
    dayProvider: () -> Int
): DateTimeFormat<LocalDate> = LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED)
    char(' ')
    dayOfMonth()
    val day = dayProvider()
    chars(day.ordinalSuffix)
}

Postprocessing the formatted string

val formatted = baseFormat.format(date).replace("${date.dayOfMonth},", "${date.dayOfMonth.ordinalSuffix},")

Both are error-prone, and most importantly, prevent round trip parsing.

Suggestion

We should add a DSL directive that handles ordinal day formatting with customizable mappings. Default to English ordinals but allow custom mappings for other languages, something like:

val date = LocalDate(2026, 1, 1)
val format = LocalDate.Format {
    monthName(MonthNames.ENGLISH_FULL)
    char(' ')
    dayOfMonthOrdinal() // English ordinals by default
    // or ..
    // dayOfMonthOrdinal(..anotherLanguageOrdinalsDirective..)
    chars(", ")
    year()
}
println(date.format(format)) // Output: "January 1st, 2026"

Let me know what you think
Cheers