net.time4j.calendar

Class CyclicYear

java.lang.Object

net.time4j.calendar.SexagesimalName

net.time4j.calendar.CyclicYear

All Implemented Interfaces:

Serializable, Comparable<SexagesimalName>

public final class CyclicYear
extends SexagesimalName

Represents the cyclic year used in East Asian calendars.

Since:

3.40/4.35

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/interfaces inherited from class net.time4j.calendar.SexagesimalName

SexagesimalName.Branch, SexagesimalName.Stem

Method Summary

Modifier and Type	Method and Description
EastAsianYear	inCycle(int cycle) Obtains a year reference for given cycle number (technical identifier).
EastAsianYear	inQingDynasty(ChineseEra era) Obtains an unambivalent year reference for given Qing dynasty.
static CyclicYear	of(int yearOfCycle) Obtains an instance of cyclic year.
static CyclicYear	of(SexagesimalName.Stem stem, SexagesimalName.Branch branch) Obtains an instance of cyclic year.
static CyclicYear	parse(String text, Locale locale) Parses the given localized name as a combination of stem and branch to a cyclic year.
CyclicYear	roll(int amount) Rolls this cyclic year by given amount.

Methods inherited from class net.time4j.calendar.SexagesimalName

compareTo, equals, getBranch, getDisplayName, getNumber, getStem, getZodiac, hashCode, toString

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

of

public static CyclicYear of(int yearOfCycle)

Obtains an instance of cyclic year.

Parameters:

yearOfCycle - year number in the range 1-60

Returns:

CyclicYear

Throws:

IllegalArgumentException - if the parameter is out of range

of

public static CyclicYear of(SexagesimalName.Stem stem,
                            SexagesimalName.Branch branch)

Obtains an instance of cyclic year.

Parameters:

stem - celestial stem

branch - terrestrial branch

Returns:

CyclicYear

Throws:

IllegalArgumentException - if the combination of stem and branch is invalid

parse

public static CyclicYear parse(String text,
                               Locale locale)
                        throws ParseException

Parses the given localized name as a combination of stem and branch to a cyclic year.

The original Chinese names are usually not translatable. A few languages like Korean, Vietnamese and Russian use their own transcriptions. The pinyin-transcription (official Chinese romanization) serves as fallback for other languages. And the root locale will use a simplified version of pinyin without diacritic accents. This method will always expect a minus sign as separator between stem and branch unless the language is Chinese, Korean or Japanese.

Parameters:

text - the text to be parsed

locale - language

Returns:

parsed cyclic year

Throws:

ParseException - if the text cannot be parsed

See Also:

SexagesimalName.getDisplayName(Locale)

roll

public CyclicYear roll(int amount)

Rolls this cyclic year by given amount.

Overrides:

roll in class SexagesimalName

Parameters:

amount - determines how many years/units this instance should be rolled

Returns:

changed copy of this instance

inQingDynasty

public EastAsianYear inQingDynasty(ChineseEra era)

Obtains an unambivalent year reference for given Qing dynasty.

Note: The years AD 1662 and AD 1722 have the same cyclic year so an unambivalent year reference cannot be determined. This is because the Kangxi-era was 61 years long.

Parameters:

era - the Chinese era representing a historic Qing dynasty

Returns:

EastAsianYear

Throws:

IllegalArgumentException - if the era is not a Qing dynasty or if the combination of this cyclic year together with the era is ambivalent (rare case in QING_KANGXI_1662_1723)

inCycle

public EastAsianYear inCycle(int cycle)

Obtains a year reference for given cycle number (technical identifier).

Parameters:

cycle - number of sexagesimal year cycle

Returns:

EastAsianYear

Throws:

IllegalArgumentException - if the cycle is smaller than 1