Class LunarUtil

java.lang.Object
cloud.opencode.base.date.lunar.LunarUtil
public final class LunarUtil extends Object
Utility class for lunar calendar conversions 农历转换工具类

This class provides static methods for converting between Gregorian (solar) calendar dates and Chinese lunar calendar dates.

此类提供阳历（公历）和农历之间相互转换的静态方法。

Features | 主要功能:

  • Solar to lunar conversion - 阳历转农历
  • Lunar to solar conversion - 农历转阳历
  • Get zodiac for a date - 获取日期的生肖
  • Solar term calculations - 节气计算

Usage Examples | 使用示例:

// Convert solar to lunar
Lunar lunar = LunarUtil.toLunar(LocalDate.of(2024, 2, 10));

// Convert lunar to solar
LocalDate solar = LunarUtil.toSolar(Lunar.of(2024, 1, 1));

// Get zodiac
String zodiac = LunarUtil.getZodiac(2024);  // "龙"

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Yes (with explicit null checks) - 空值安全: 是（有明确的空值检查）

Performance | 性能特性:

  • Time complexity: O(1) - conversions iterate over a bounded range (years 1900-2100, max ~200 years × 13 months) backed by a fixed lookup table - 时间复杂度: O(1) - 转换在有限范围（1900-2100 年，最多约 200 年 × 13 个月）内迭代，依赖固定查找表
  • Space complexity: O(1) - uses a pre-allocated static LUNAR_INFO array; no additional allocations per call - 空间复杂度: O(1) - 使用预分配的静态 LUNAR_INFO 数组；每次调用不额外分配内存
Since:
JDK 25, opencode-base-date V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    static int
    getLeapMonth(int year)
    Gets the leap month for a year (0 if no leap month) 获取指定年份的闰月（如果没有闰月则为0）
    static int
    getLeapMonthDays(int year)
    Gets the number of days in the leap month 获取闰月的天数
    static int
    getLunarMonthDays(int year, int month)
    Gets the number of days in a lunar month 获取农历月的天数
    static int
    getLunarYearDays(int year)
    Gets the number of days in a lunar year 获取农历年的总天数
    static String
    getStemBranchYear(int year)
    Gets the stem-branch year name 获取干支纪年
    static String
    getZodiac(int year)
    Gets the Chinese zodiac animal for a year 获取指定年份的生肖
    static String
    getZodiac(LocalDate date)
    Gets the Chinese zodiac animal for a date 获取指定日期的生肖
    static boolean
    hasLeapMonth(int year)
    Checks if a lunar year has a leap month 检查农历年是否有闰月
    static Lunar
    today()
    Gets the current lunar date 获取当前农历日期
    static Lunar
    toLunar(LocalDate solarDate)
    Converts a solar (Gregorian) date to lunar date 将阳历（公历）日期转换为农历日期
    static LocalDate
    toSolar(Lunar lunar)
    Converts a lunar date to solar (Gregorian) date 将农历日期转换为阳历（公历）日期

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • toLunar

      public static Lunar toLunar(LocalDate solarDate)
      Converts a solar (Gregorian) date to lunar date 将阳历（公历）日期转换为农历日期
      Parameters:
      solarDate - the solar date | 阳历日期
      Returns:
      the lunar date | 农历日期

    • toSolar

      public static LocalDate toSolar(Lunar lunar)
      Converts a lunar date to solar (Gregorian) date 将农历日期转换为阳历（公历）日期
      Parameters:
      lunar - the lunar date | 农历日期
      Returns:
      the solar date | 阳历日期

    • getLeapMonth

      public static int getLeapMonth(int year)
      Gets the leap month for a year (0 if no leap month) 获取指定年份的闰月（如果没有闰月则为0）
      Parameters:
      year - the lunar year | 农历年
      Returns:
      the leap month (1-12) or 0 | 闰月（1-12）或0

    • getLunarYearDays

      public static int getLunarYearDays(int year)
      Gets the number of days in a lunar year 获取农历年的总天数
      Parameters:
      year - the lunar year | 农历年
      Returns:
      the number of days | 天数

    • getLunarMonthDays

      public static int getLunarMonthDays(int year, int month)
      Gets the number of days in a lunar month 获取农历月的天数
      Parameters:
      year - the lunar year | 农历年
      month - the lunar month | 农历月
      Returns:
      the number of days (29 or 30) | 天数（29或30）

    • getLeapMonthDays

      public static int getLeapMonthDays(int year)
      Gets the number of days in the leap month 获取闰月的天数
      Parameters:
      year - the lunar year | 农历年
      Returns:
      the number of days (0, 29, or 30) | 天数（0、29或30）

    • getZodiac

      public static String getZodiac(int year)
      Gets the Chinese zodiac animal for a year 获取指定年份的生肖
      Parameters:
      year - the year | 年份
      Returns:
      the zodiac animal | 生肖

    • getZodiac

      public static String getZodiac(LocalDate date)
      Gets the Chinese zodiac animal for a date 获取指定日期的生肖
      Parameters:
      date - the date | 日期
      Returns:
      the zodiac animal | 生肖

    • getStemBranchYear

      public static String getStemBranchYear(int year)
      Gets the stem-branch year name 获取干支纪年
      Parameters:
      year - the year | 年份
      Returns:
      the stem-branch year name | 干支年名

    • hasLeapMonth

      public static boolean hasLeapMonth(int year)
      Checks if a lunar year has a leap month 检查农历年是否有闰月
      Parameters:
      year - the lunar year | 农历年
      Returns:
      true if has leap month | 如果有闰月返回true

    • today

      public static Lunar today()
      Gets the current lunar date 获取当前农历日期
      Returns:
      the current lunar date | 当前农历日期