Class 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
  • Method Details

    • 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