net.time4j.calendar

Class PersianCalendar

java.lang.Object

net.time4j.engine.ChronoEntity<T>

net.time4j.engine.TimePoint<U,D>

net.time4j.engine.Calendrical<PersianCalendar.Unit,PersianCalendar>

net.time4j.calendar.PersianCalendar

All Implemented Interfaces:

Serializable, Comparable<PersianCalendar>, CalendarDate, ChronoDisplay, Temporal<CalendarDate>, LocalizedPatternSupport

@CalendarType(value="persian")
public final class PersianCalendar
extends Calendrical<PersianCalendar.Unit,PersianCalendar>
implements LocalizedPatternSupport

Represents the Solar Hijri calendar which is officially used in Iran and Afghanistan.

Introduction

It is a solar calendar which is in close agreement with the astronomical seasons. The vernal equinox serves as the first day of the Persian year (Farvardin 1st). If it is observed before noon at local time in Teheran then the associated day is the first day of the year else the next day. More details about the length of the vernal-equinox-year see: A concise review of the Iranian calendar

The calendar year is divided into 12 Persian months. The first 6 months are 31 days long. The following months are 30 days long with the exception of the last month whose length is 29 days in normal years and 30 days in leap years. The algorithm is based on the excellent work of Borkowski who describes the details at The Persian calendar for 3000 years. It is in agreement with the well known cycle proposed by Omar Khayam for the years 1178-1633 (ISO: 1799-2254). However, dates calculated in far future beyond 2123 can still be wrong due to the uncertainty of astronomical term delta-T and should be considered as approximation.

Following elements which are declared as constants are registered by this class

• DAY_OF_WEEK
• DAY_OF_MONTH
• DAY_OF_YEAR
• WEEKDAY_IN_MONTH
• MONTH_OF_YEAR
• YEAR_OF_ERA
• ERA

Furthermore, all elements defined in EpochDays and CommonElements are supported.

Example of usage

     ChronoFormatter<PersianCalendar> formatter =
       ChronoFormatter.setUp(PersianCalendar.axis(), new Locale("fa"))
       .addPattern("EEE, d. MMMM yy", PatternType.CLDR_DATE).build();
     PlainDate today = SystemClock.inLocalView().today();
     PersianCalendar jalali = today.transform(PersianCalendar.class);
     System.out.println(formatter.format(jalali));
 

Support for unicode ca-extensions

      Locale loc = Locale.forLanguageTag("de-IR-u-ca-persian");
      ChronoFormatter<CalendarDate> formatter = ChronoFormatter.ofGenericCalendarStyle(DisplayMode.MEDIUM, loc);
      PersianCalendar jalali = PersianCalendar.of(1393, 1, 10);
      PlainDate gregorian = jalali.transform(PlainDate.class);
      assertThat(formatter.format(jalali), is("10.01.1393 AP"));
      assertThat(formatter.format(gregorian), is("10.01.1393 AP"));
 

Since:

3.9/4.6

Author:

Meno Hochschild

See Also:

Serialized Form

Concurrency:

This class is immutable and can be used by multiple threads in parallel.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	PersianCalendar.Date Static view of calendar date taking into account possibly different calendar algorithms.
static class	PersianCalendar.Unit Defines some calendar units for the Persian calendar.

Field Summary

Fields

Modifier and Type	Field and Description
static StdCalendarElement<Integer,PersianCalendar>	BOUNDED_WEEK_OF_MONTH Equivalent to CommonElements.boundedWeekOfMonth(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).
static StdCalendarElement<Integer,PersianCalendar>	BOUNDED_WEEK_OF_YEAR Equivalent to CommonElements.boundedWeekOfYear(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).
static StdCalendarElement<Integer,PersianCalendar>	DAY_OF_MONTH Represents the Persian day of month.
static StdCalendarElement<Weekday,PersianCalendar>	DAY_OF_WEEK Represents the Persian day of week.
static StdCalendarElement<Integer,PersianCalendar>	DAY_OF_YEAR Represents the Persian day of year.
static ChronoElement<PersianEra>	ERA Represents the Persian era.
static StdCalendarElement<Weekday,PersianCalendar>	LOCAL_DAY_OF_WEEK Equivalent to CommonElements.localDayOfWeek(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).
static StdCalendarElement<PersianMonth,PersianCalendar>	MONTH_OF_YEAR Represents the Persian month.
static StdCalendarElement<Integer,PersianCalendar>	WEEK_OF_MONTH Equivalent to CommonElements.weekOfMonth(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).
static StdCalendarElement<Integer,PersianCalendar>	WEEK_OF_YEAR Equivalent to CommonElements.weekOfYear(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).
static OrdinalWeekdayElement<PersianCalendar>	WEEKDAY_IN_MONTH Element with the ordinal day-of-week within given calendar month.
static StdCalendarElement<Integer,PersianCalendar>	YEAR_OF_ERA Represents the Persian year.

Method Summary

Modifier and Type	Method and Description
GeneralTimestamp<PersianCalendar>	at(PlainTime time) Creates a new local timestamp with this date and given wall time.
GeneralTimestamp<PersianCalendar>	atTime(int hour, int minute) Is equivalent to at(PlainTime.of(hour, minute)).
static TimeAxis<PersianCalendar.Unit,PersianCalendar>	axis() Returns the associated time axis.
boolean	equals(Object obj) Based on the epoch day number and the calendar system.
PersianCalendar.Date	getDate(PersianAlgorithm algorithm) Obtains an alternative date view specific for given algorithm.
PersianCalendar.Date	getDate(ZonalOffset offset) Obtains an astronomical date view specific for given timezone offset.
int	getDayOfMonth() Yields the Persian day of month.
Weekday	getDayOfWeek() Determines the day of week.
int	getDayOfYear() Yields the Persian day of year.
static Weekmodel	getDefaultWeekmodel() Obtains the standard week model of this calendar.
PersianEra	getEra() Yields the Persian era.
PersianMonth	getMonth() Yields the Persian month.
int	getYear() Yields the Persian year.
int	hashCode() Based on the epoch day number.
boolean	isLeapYear() Is the year of this date a leap year?
static boolean	isValid(int yearOfEra, int month, int dayOfMonth) Queries if given parameter values form a well defined calendar date.
int	lengthOfMonth() Yields the length of current Persian month in days.
int	lengthOfYear() Yields the length of current Persian year in days.
static PersianCalendar	nowInSystemTime() Obtains the current calendar date in system time.
static PersianCalendar	of(int pyear, int pmonth, int pdom) Creates a new instance of a Persian calendar date.
static PersianCalendar	of(int pyear, PersianMonth pmonth, int pdom) Creates a new instance of a Persian calendar date.
String	toString() Provides a complete textual representation of the state of this time point.

Methods inherited from class net.time4j.engine.Calendrical

compareTo, getDaysSinceEpochUTC, isAfter, isBefore, isSimultaneous, minus, plus

Methods inherited from class net.time4j.engine.TimePoint

max, min, minus, minus, plus, plus, until, until

Methods inherited from class net.time4j.engine.ChronoEntity

contains, get, get, getInt, getMaximum, getMinimum, getRegisteredElements, getTimezone, hasTimezone, isValid, isValid, isValid, matches, with, with, with, with

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface net.time4j.format.LocalizedPatternSupport

getFormatPattern, getFormatPattern, useDynamicFormatPattern

Methods inherited from interface net.time4j.engine.CalendarDate

from, from, from, transform, transform, transform, transform, transform, transform

Methods inherited from interface net.time4j.engine.Temporal

isAfterAll, isAfterOrEqual, isBeforeAll, isBeforeOrEqual

Field Detail

ERA

@FormattableElement(format="G")
public static final ChronoElement<PersianEra> ERA

Represents the Persian era.

YEAR_OF_ERA

@FormattableElement(format="y")
public static final StdCalendarElement<Integer,PersianCalendar> YEAR_OF_ERA

Represents the Persian year.

MONTH_OF_YEAR

@FormattableElement(format="M",
                    alt="L")
public static final StdCalendarElement<PersianMonth,PersianCalendar> MONTH_OF_YEAR

Represents the Persian month.

DAY_OF_MONTH

@FormattableElement(format="d")
public static final StdCalendarElement<Integer,PersianCalendar> DAY_OF_MONTH

Represents the Persian day of month.

DAY_OF_YEAR

@FormattableElement(format="D")
public static final StdCalendarElement<Integer,PersianCalendar> DAY_OF_YEAR

Represents the Persian day of year.

DAY_OF_WEEK

@FormattableElement(format="E")
public static final StdCalendarElement<Weekday,PersianCalendar> DAY_OF_WEEK

Represents the Persian day of week.

If the day-of-week is set to a new value then Time4J handles the Persian calendar week as starting on Saturday.

See Also:

getDefaultWeekmodel(), CommonElements.localDayOfWeek(Chronology, Weekmodel)

WEEKDAY_IN_MONTH

@FormattableElement(format="F")
public static final OrdinalWeekdayElement<PersianCalendar> WEEKDAY_IN_MONTH

Element with the ordinal day-of-week within given calendar month.

LOCAL_DAY_OF_WEEK

public static final StdCalendarElement<Weekday,PersianCalendar> LOCAL_DAY_OF_WEEK

Equivalent to CommonElements.localDayOfWeek(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).

Since:

3.40/4.35

See Also:

CommonElements.localDayOfWeek(Chronology, Weekmodel), getDefaultWeekmodel()

WEEK_OF_YEAR

public static final StdCalendarElement<Integer,PersianCalendar> WEEK_OF_YEAR

Equivalent to CommonElements.weekOfYear(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).

Since:

3.40/4.35

See Also:

CommonElements.weekOfYear(Chronology, Weekmodel), getDefaultWeekmodel()

WEEK_OF_MONTH

public static final StdCalendarElement<Integer,PersianCalendar> WEEK_OF_MONTH

Equivalent to CommonElements.weekOfMonth(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).

Since:

3.40/4.35

See Also:

CommonElements.weekOfMonth(Chronology, Weekmodel), getDefaultWeekmodel()

BOUNDED_WEEK_OF_YEAR

public static final StdCalendarElement<Integer,PersianCalendar> BOUNDED_WEEK_OF_YEAR

Equivalent to CommonElements.boundedWeekOfYear(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).

Since:

3.40/4.35

See Also:

CommonElements.boundedWeekOfYear(Chronology, Weekmodel), getDefaultWeekmodel()

BOUNDED_WEEK_OF_MONTH

public static final StdCalendarElement<Integer,PersianCalendar> BOUNDED_WEEK_OF_MONTH

Equivalent to CommonElements.boundedWeekOfMonth(PersianCalendar.axis(), PersianCalendar.getDefaultWeekmodel()).

Since:

3.40/4.35

See Also:

CommonElements.boundedWeekOfMonth(Chronology, Weekmodel), getDefaultWeekmodel()

Method Detail

of

public static PersianCalendar of(int pyear,
                                 PersianMonth pmonth,
                                 int pdom)

Creates a new instance of a Persian calendar date.

Parameters:

pyear - Persian year in the range 1-3000

pmonth - Persian month

pdom - Persian day of month

Returns:

new instance of PersianCalendar

Throws:

IllegalArgumentException - in case of any inconsistencies

Since:

3.9/4.6

of

public static PersianCalendar of(int pyear,
                                 int pmonth,
                                 int pdom)

Creates a new instance of a Persian calendar date.

Parameters:

pyear - Persian year in the range 1-3000

pmonth - Persian month

pdom - Persian day of month

Returns:

new instance of PersianCalendar

Throws:

IllegalArgumentException - in case of any inconsistencies

Since:

3.9/4.6

nowInSystemTime

public static PersianCalendar nowInSystemTime()

Obtains the current calendar date in system time.

Convenient short-cut for: SystemClock.inLocalView().now(PersianCalendar.axis()).

Returns:

current calendar date in system time zone using the system clock

Since:

3.23/4.19

See Also:

SystemClock.inLocalView(), ZonalClock.now(net.time4j.engine.Chronology)

getEra

public PersianEra getEra()

Yields the Persian era.

Returns:

PersianEra.ANNO_PERSICO

Since:

3.9/4.6

getYear

public int getYear()

Yields the Persian year.

Returns:

int

Since:

3.9/4.6

getMonth

public PersianMonth getMonth()

Yields the Persian month.

Returns:

enum

Since:

3.9/4.6

getDayOfMonth

public int getDayOfMonth()

Yields the Persian day of month.

Returns:

int

Since:

3.9/4.6

getDayOfWeek

public Weekday getDayOfWeek()

Determines the day of week.

The Persian calendar also uses a 7-day-week.

Returns:

Weekday

Since:

3.9/4.6

getDayOfYear

public int getDayOfYear()

Yields the Persian day of year.

Returns:

int

Since:

3.9/4.6

getDate

public PersianCalendar.Date getDate(PersianAlgorithm algorithm)

Obtains an alternative date view specific for given algorithm.

Parameters:

algorithm - calendar computation

Returns:

Persian date (possibly modified)

Throws:

IllegalArgumentException - in case of date overflow

Since:

3.33/4.28

getDate

public PersianCalendar.Date getDate(ZonalOffset offset)

Obtains an astronomical date view specific for given timezone offset.

Parameters:

offset - timezone offset

Returns:

Persian date based on astronomical calculations for given offset (possibly modified)

Throws:

IllegalArgumentException - in case of date overflow

Since:

3.33/4.28

See Also:

PersianAlgorithm.ASTRONOMICAL, getDate(PersianAlgorithm)

lengthOfMonth

public int lengthOfMonth()

Yields the length of current Persian month in days.

Returns:

int

Since:

3.9/4.6

lengthOfYear

public int lengthOfYear()

Yields the length of current Persian year in days.

Returns:

int

Since:

3.9/4.6

isLeapYear

public boolean isLeapYear()

Is the year of this date a leap year?

Returns:

boolean

Since:

3.9/4.6

isValid

public static boolean isValid(int yearOfEra,
                              int month,
                              int dayOfMonth)

Queries if given parameter values form a well defined calendar date.

Parameters:

yearOfEra - the year of era to be checked

month - the month to be checked

dayOfMonth - the day of month to be checked

Returns:

true if valid else false

Since:

3.34/4.29

See Also:

of(int, int, int)

at

public GeneralTimestamp<PersianCalendar> at(PlainTime time)

Creates a new local timestamp with this date and given wall time.

If the time T24:00 is used then the resulting timestamp will automatically be normalized such that the timestamp will contain the following day instead.

Parameters:

time - wall time

Returns:

general timestamp as composition of this date and given time

Since:

3.9/4.6

atTime

public GeneralTimestamp<PersianCalendar> atTime(int hour,
                                                int minute)

Is equivalent to at(PlainTime.of(hour, minute)).

Parameters:

hour - hour of day in range (0-24)

minute - minute of hour in range (0-59)

Returns:

general timestamp as composition of this date and given time

Throws:

IllegalArgumentException - if any argument is out of range

Since:

3.9/4.6

equals

public boolean equals(Object obj)

Description copied from class: Calendrical

Based on the epoch day number and the calendar system.

In other words: Two date object are equal if they have the same temporal position on the local timeline and have the same calendrical type. Subclasses which define further state attributes must override this method.

If an only temporal comparison is required then the method Calendrical.isSimultaneous(CalendarDate) is to be used.

Overrides:

equals in class Calendrical<PersianCalendar.Unit,PersianCalendar>

See Also:

Chronology.getChronoType()

hashCode

public int hashCode()

Description copied from class: Calendrical

Based on the epoch day number.

Overrides:

hashCode in class Calendrical<PersianCalendar.Unit,PersianCalendar>

toString

public String toString()

Description copied from class: TimePoint

Provides a complete textual representation of the state of this time point.

The textual description often follows the conventions of ISO-8601. Usually the description starts with the chronological informations which are coarse-grained and ends with those ones which are fine-grained (for example the ISO-notation YYYY-MM-DD).

Specified by:

toString in class TimePoint<PersianCalendar.Unit,PersianCalendar>

getDefaultWeekmodel

public static Weekmodel getDefaultWeekmodel()

Obtains the standard week model of this calendar.

The persian calendar usually starts on Saturday.

Returns:

Weekmodel

Since:

3.24/4.20

axis

public static TimeAxis<PersianCalendar.Unit,PersianCalendar> axis()

Returns the associated time axis.

Returns:

chronology

Since:

3.9/4.6