persianutils

persianutils is a robust collection of utilities for Scala and Java developers targeting Persian (Farsi) speaking users, cross-compiled for both JVM and Scala.js environments.

Key Capabilities

DateConverter: Precision conversion between Gregorian and Persian (Solar Hijri) calendars based on astronomical algorithms covering a 3,000-year epoch.
DateToWord: Converts calendar dates into natural Persian verbal expressions and text representations.
NumToWord: Converts cardinal and ordinal numbers into written Persian words.
TextSanitiser: Automated typography normalisation, character variant standardisation, digit unification, and whitespace/ZWNJ sanitisation.
Cross-Platform & Dual-Ecosystem: Native support for Scala 2.13 and Scala 3.x across the JVM and Scala.js, with seamless Java interop.

Documentation & Guides

Core Modules

DateConverter Guide: Detailed algorithmic background, date representations, and dual-calendar conversion recipes.
DateToWord Guide: Transforming Persian calendar dates into spoken and written words.
NumToWord Guide: Cardinal and ordinal number to Persian word conversions.
TextSanitiser Guide: Normalising Persian text, standardising Arabic letter variants, converting digits, cleaning non-breaking spaces, and deduplicating zero-width non-joiners (ZWNJ).

Reference & API

API Reference (Scala 3): Interactive Scaladoc for the Scala 3 build.
API Reference (Scala 2.13): Interactive Scaladoc for the Scala 2.13 build.
Compatibility Matrix: Platform and runtime matrix across Scala 2.10 through 3.x and Java LTS releases.

Quick Installation

SBT

For JVM projects:

libraryDependencies ++= Seq(
  "com.bahmanm" %% "persianutils" % "6.0"
)

For Scala.js projects:

libraryDependencies ++= Seq(
  "com.bahmanm" %%% "persianutils" % "6.0"
)

Maven

With Scala 3.x:

<dependency>
  <groupId>com.bahmanm</groupId>
  <artifactId>persianutils_3</artifactId>
  <version>6.0</version>
</dependency>

With Scala 2.13.x:

<dependency>
  <groupId>com.bahmanm</groupId>
  <artifactId>persianutils_2.13</artifactId>
  <version>6.0</version>
</dependency>

Scala-CLI

//> using dep com.bahmanm::persianutils:6.0

Mill

def ivyDeps = Agg(
  ivy"com.bahmanm::persianutils:6.0"
)

Gradle

With Scala 3.x:

implementation 'com.bahmanm:persianutils_3:6.0'

With Scala 2.13.x:

implementation 'com.bahmanm:persianutils_2.13:6.0'

Quick Example

import com.bahmanm.persianutils.DateConverter._

// Months and days are 1-indexed (e.g. Farvardin is 1, Esfand is 12)
val gDate = GregorianDate(2026, 3, 21)
val pDate = gregorianToPersian(gDate)

println(pDate) // 1405/1/1

For comprehensive recipes in both Scala and Java, consult the individual module guides.