@spec addDays(t(), integer()) :: t()

Adds the given number of days (can be negative).

@spec addMonths(t(), integer()) :: t()

Adds the given number of Jalali months (can be negative).

@spec addWeeks(t(), integer()) :: t()

Adds the given number of weeks (can be negative).

@spec addYears(t(), integer()) :: t()

Adds the given number of Jalali years (can be negative).

@spec clone(t()) :: t()

Creates a copy of this JalaliX instance (same instant and timezone).

@spec compare(t(), t()) :: boolean()

Returns true if a is before b.

@spec create(
  integer()
  | float()
  | String.t()
  | Date.t()
  | DateTime.t()
  | NaiveDateTime.t()
  | t(),
  map() | keyword()
) :: t()

Creates a JalaliX instance from a Gregorian date value.

Accepts a Unix millisecond timestamp (integer/float), an ISO8601 string, a Date/DateTime/NaiveDateTime, or another JalaliX.

opts may contain timezone: to set the active zone (map or keyword list).

@spec format(t(), String.t(), boolean() | map() | keyword(), boolean()) :: String.t()

Formats the date according to a format string.

Prefer format(j, str, %{calendar: ..., persianDigits: ...}). Positional booleans remain supported: format(j, str, persianDigits?, gregorian?).

Tokens

YYYY YYY YY Y       year
MMM MM M            month name / number
W w                 week of year (padded / not)
DW dw WN wn WL wl    day-of-week (iso number / number / name / letter)
DDDD DDD             day of year (padded / not)
DD D                 day of month (padded / not)
HH H                 hour, 24h (padded / not)
hh h                 hour, 12h (padded / not)
mm m                 minutes (padded / not)
ss s                 seconds (padded / not)
SSS sss              milliseconds
A a                  meridiem
X x                  unix seconds / milliseconds

@spec fromPersian(String.t()) :: String.t()

Converts Persian numerals (۰-۹) to Western numerals (0-9) in a string.

@spec getDate(t()) :: integer()

Gets the day of the month in the Jalali calendar (1-31).

@spec getDay(t()) :: integer()

Gets the day of the week (1=Saturday .. 7=Friday in Jalali).

@spec getDayISO(t()) :: integer()

Gets the ISO day of the week (1=Monday .. 7=Sunday).

@spec getDayOfYear(t()) :: integer()

Gets the Jalali day of the year (1-366).

@spec getEndOfDay(t()) :: t()

Returns a new instance set to the end of the current day (23:59:59.999).

@spec getEndOfMonth(t()) :: t()

Returns a new instance set to the end of the current Jalali month.

@spec getEndOfWeek(t()) :: t()

Returns a new instance set to the end of the current week (Friday).

@spec getEndOfYear(t()) :: t()

Returns a new instance set to the end of the Jalali year (23:59:59.999).

@spec getFullYear(t()) :: integer()

Gets the Jalali year.

@spec getHours(t()) :: integer()

Gets the hour (0-23) using wall time in the active timezone.

@spec getHoursISO(t()) :: integer()

Gets the hour in 12-hour format (1-12).

@spec getMeridiem(t()) :: String.t()

Gets the meridiem (AM/PM) in Persian.

@spec getMilliseconds(t()) :: integer()

Gets the milliseconds (0-999).

@spec getMinutes(t()) :: integer()

Gets the minutes (0-59) using wall time in the active timezone.

@spec getMonth(t()) :: integer()

Gets the Jalali month (1-12, Farvardin = 1).

@spec getSeconds(t()) :: integer()

Gets the seconds (0-59) using wall time in the active timezone.

@spec getStartOfDay(t()) :: t()

Returns a new instance set to the start of the current day (00:00:00.000).

@spec getStartOfMonth(t()) :: t()

Returns a new instance set to the start of the current Jalali month.

@spec getStartOfWeek(t()) :: t()

Returns a new instance set to the start of the current week (Saturday).

@spec getStartOfYear(t()) :: t()

Returns a new instance set to the start of the Jalali year.

@spec getTime(t()) :: integer()

Gets the Unix millisecond timestamp.

@spec getTimezone(t()) :: String.t()

Gets the active IANA timezone id of this instance.

@spec getWeekOfYear(t()) :: integer()

Gets the Jalali week number of the year (1-53).

@spec isValidDate(any()) :: boolean()

Returns true if value is a recognized date-like value.

@spec parseJalali(String.t(), map() | keyword()) :: t()

Parses a Jalali date string into a JalaliX instance.

Accepts YYYY/MM/DD or YYYY-MM-DD, optional time (HH:mm / HH:mm:ss), and Persian digits.

@spec setDate(t(), integer()) :: t()

Sets the day of the month (Jalali) using wall time.

@spec setFullYear(t(), integer(), integer() | nil, integer() | nil) :: t()

Sets the Jalali year (and optionally month/day) using wall time.

month is 0-based (Farvardin = 0 .. Esfand = 11), matching JS Date.

@spec setHours(t(), number(), number() | nil, number() | nil, number() | nil) :: t()

Sets the hour (and optionally minutes/seconds/milliseconds) using wall time.

@spec setMilliseconds(t(), number()) :: t()

Sets the milliseconds using wall time in the active timezone.

@spec setMinutes(t(), number(), number() | nil, number() | nil) :: t()

Sets the minutes (and optionally seconds/milliseconds) using wall time.

@spec setMonth(t(), integer(), integer() | nil) :: t()

Sets the Jalali month using wall time.

month is 0-based (Farvardin = 0 .. Esfand = 11), matching JS Date.

@spec setSeconds(t(), number(), number() | nil) :: t()

Sets the seconds (and optionally milliseconds) using wall time.

@spec setTime(t(), number()) :: t()

Sets the Unix millisecond timestamp.

@spec setTimezone(t(), String.t() | nil) :: t()

Creates a new JalaliX with the same UTC instant in a different timezone.

Instant-preserving: getTime/1 is unchanged; wall clock / Jalali day may change. Aliases: local/system/default -> host zone (or UTC), utc/gmt -> UTC. Raises ArgumentError for an unrecognized zone.

@spec toDateString(t()) :: String.t()

Date string with weekday, day, month, and year (no time).

@spec toISODate(t(), String.t()) :: String.t()

Returns a calendar date string using wall getters in the active timezone (no UTC shift).

calendar is "gregorian" (default, YYYY-MM-DD Gregorian) or "jalali" (Jalali YYYY-MM-DD).

@spec toLocaleDateString(t()) :: String.t()

Locale-formatted date string: YYYY/MM/DD.

@spec toLocaleTimeString(t()) :: String.t()

Time string with meridiem, e.g. 10:30:45 ق.ظ..

@spec toPersian(String.t()) :: String.t()

Converts Western numerals (0-9) to Persian numerals (۰-۹) in a string.

@spec toString(t()) :: String.t()

Full date string with weekday, day, month, year, and time.