Class YearQuarter

java.lang.Object
cloud.opencode.base.date.extra.YearQuarter
All Implemented Interfaces:
Serializable, Comparable<YearQuarter>, Temporal, TemporalAccessor, TemporalAdjuster
public final class YearQuarter extends Object implements Temporal, TemporalAdjuster, Comparable<YearQuarter>, Serializable
Year-Quarter combination representing a specific quarter in a specific year 年-季度组合，表示特定年份的特定季度

This class represents a year and quarter combination, such as "2024-Q1" for the first quarter of 2024. It is modeled after ThreeTen-Extra's YearQuarter class.

此类表示年份和季度的组合，例如"2024-Q1"表示2024年第一季度。 设计参考ThreeTen-Extra的YearQuarter类。

Features | 主要功能:

  • Create from year and quarter - 从年份和季度创建
  • Parse from string format - 从字符串格式解析
  • Add/subtract quarters and years - 加减季度和年份
  • Get start/end date of quarter - 获取季度的开始/结束日期
  • Comparison and equality - 比较和相等性

Usage Examples | 使用示例:

// Create YearQuarter
YearQuarter yq = YearQuarter.of(2024, 1);           // 2024-Q1
YearQuarter yq2 = YearQuarter.of(2024, Quarter.Q2); // 2024-Q2
YearQuarter now = YearQuarter.now();                // Current quarter

// Parse from string
YearQuarter parsed = YearQuarter.parse("2024-Q1");

// Calculate
YearQuarter next = yq.plusQuarters(1);  // 2024-Q2
YearQuarter prev = yq.minusYears(1);    // 2023-Q1

// Get dates
LocalDate start = yq.atStartOfQuarter(); // 2024-01-01
LocalDate end = yq.atEndOfQuarter();     // 2024-03-31

// Compare
boolean before = yq.isBefore(yq2);  // true

Performance | 性能特性:

  • Immutable and thread-safe - 不可变且线程安全
  • Cached formatter for parsing - 解析使用缓存的格式化器

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Immutable: Yes - 不可变: 是
Since:
JDK 25, opencode-base-date V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • of

      public static YearQuarter of(int year, int quarter)
      Creates a YearQuarter from year and quarter value 从年份和季度值创建YearQuarter
      Parameters:
      year - the year | 年份
      quarter - the quarter value from 1 to 4 | 季度值，范围1到4
      Returns:
      the YearQuarter instance | YearQuarter实例
      Throws:
      OpenDateException - if the quarter is invalid | 如果季度无效则抛出异常

    • of

      public static YearQuarter of(int year, Quarter quarter)
      Creates a YearQuarter from year and Quarter enum 从年份和Quarter枚举创建YearQuarter
      Parameters:
      year - the year | 年份
      quarter - the Quarter enum | Quarter枚举
      Returns:
      the YearQuarter instance | YearQuarter实例
      Throws:
      NullPointerException - if quarter is null | 如果季度为null则抛出异常

    • from

      public static YearQuarter from(TemporalAccessor temporal)
      Creates a YearQuarter from a TemporalAccessor 从TemporalAccessor创建YearQuarter
      Parameters:
      temporal - the temporal accessor | 时间访问器
      Returns:
      the YearQuarter instance | YearQuarter实例
      Throws:
      OpenDateException - if unable to convert | 如果无法转换则抛出异常

    • now

      public static YearQuarter now()
      Gets the current YearQuarter using system default zone 使用系统默认时区获取当前YearQuarter
      Returns:
      the current YearQuarter | 当前YearQuarter

    • now

      public static YearQuarter now(ZoneId zone)
      Gets the current YearQuarter for the specified zone 获取指定时区的当前YearQuarter
      Parameters:
      zone - the zone ID | 时区ID
      Returns:
      the current YearQuarter | 当前YearQuarter

    • now

      public static YearQuarter now(Clock clock)
      Gets the current YearQuarter using the specified clock 使用指定时钟获取当前YearQuarter
      Parameters:
      clock - the clock to use | 要使用的时钟
      Returns:
      the current YearQuarter | 当前YearQuarter

    • parse

      public static YearQuarter parse(CharSequence text)
      Parses a string to YearQuarter 解析字符串为YearQuarter

      Supported formats: "2024-Q1", "2024Q1"

      支持的格式："2024-Q1"、"2024Q1"

      Parameters:
      text - the text to parse | 要解析的文本
      Returns:
      the parsed YearQuarter | 解析后的YearQuarter
      Throws:
      OpenDateException - if the text cannot be parsed | 如果文本无法解析则抛出异常

    • parse

      public static YearQuarter parse(CharSequence text, DateTimeFormatter formatter)
      Parses a string to YearQuarter using the specified formatter 使用指定格式化器解析字符串为YearQuarter
      Parameters:
      text - the text to parse | 要解析的文本
      formatter - the formatter to use | 要使用的格式化器
      Returns:
      the parsed YearQuarter | 解析后的YearQuarter
      Throws:
      OpenDateException - if the text cannot be parsed | 如果文本无法解析则抛出异常

    • getYear

      public int getYear()
      Gets the year 获取年份
      Returns:
      the year | 年份

    • getQuarterValue

      public int getQuarterValue()
      Gets the quarter value (1-4) 获取季度值(1-4)
      Returns:
      the quarter value | 季度值

    • getQuarter

      public Quarter getQuarter()
      Gets the Quarter enum 获取Quarter枚举
      Returns:
      the Quarter | Quarter枚举

    • isLeapYear

      public boolean isLeapYear()
      Checks if this year is a leap year 检查此年份是否为闰年
      Returns:
      true if leap year | 如果是闰年返回true

    • lengthOfQuarter

      public int lengthOfQuarter()
      Gets the length of this quarter in days 获取此季度的天数
      Returns:
      the number of days | 天数

    • isFirstQuarter

      public boolean isFirstQuarter()
      Checks if this is the first quarter of the year 检查是否为年度第一季度
      Returns:
      true if Q1 | 如果是Q1返回true

    • isLastQuarter

      public boolean isLastQuarter()
      Checks if this is the last quarter of the year 检查是否为年度最后一个季度
      Returns:
      true if Q4 | 如果是Q4返回true

    • plusYears

      public YearQuarter plusYears(long years)
      Adds years to this YearQuarter 在此YearQuarter基础上加年数
      Parameters:
      years - the years to add | 要加的年数
      Returns:
      a new YearQuarter | 新的YearQuarter

    • plusQuarters

      public YearQuarter plusQuarters(long quarters)
      Adds quarters to this YearQuarter 在此YearQuarter基础上加季度数
      Parameters:
      quarters - the quarters to add | 要加的季度数
      Returns:
      a new YearQuarter | 新的YearQuarter

    • minusYears

      public YearQuarter minusYears(long years)
      Subtracts years from this YearQuarter 在此YearQuarter基础上减年数
      Parameters:
      years - the years to subtract | 要减的年数
      Returns:
      a new YearQuarter | 新的YearQuarter

    • minusQuarters

      public YearQuarter minusQuarters(long quarters)
      Subtracts quarters from this YearQuarter 在此YearQuarter基础上减季度数
      Parameters:
      quarters - the quarters to subtract | 要减的季度数
      Returns:
      a new YearQuarter | 新的YearQuarter

    • atStartOfQuarter

      public LocalDate atStartOfQuarter()
      Gets the start date of this quarter 获取此季度的开始日期
      Returns:
      the first day of the quarter | 季度的第一天

    • atEndOfQuarter

      public LocalDate atEndOfQuarter()
      Gets the end date of this quarter 获取此季度的结束日期
      Returns:
      the last day of the quarter | 季度的最后一天

    • atDay

      public LocalDate atDay(int dayOfQuarter)
      Gets the date at a specific day within this quarter 获取此季度内特定天的日期
      Parameters:
      dayOfQuarter - the day within the quarter (1 to length) | 季度内的天数（1到长度）
      Returns:
      the LocalDate | LocalDate
      Throws:
      OpenDateException - if the day is invalid | 如果天数无效则抛出异常

    • atMonth

      public YearMonth atMonth(int monthOfQuarter)
      Gets the YearMonth at a specific month within this quarter 获取此季度内特定月份的YearMonth
      Parameters:
      monthOfQuarter - the month within the quarter (1, 2, or 3) | 季度内的月份（1、2或3）
      Returns:
      the YearMonth | YearMonth
      Throws:
      OpenDateException - if the month is invalid | 如果月份无效则抛出异常

    • isBefore

      public boolean isBefore(YearQuarter other)
      Checks if this YearQuarter is before the specified one 检查此YearQuarter是否在指定的之前
      Parameters:
      other - the other YearQuarter | 另一个YearQuarter
      Returns:
      true if before | 如果在之前返回true

    • isAfter

      public boolean isAfter(YearQuarter other)
      Checks if this YearQuarter is after the specified one 检查此YearQuarter是否在指定的之后
      Parameters:
      other - the other YearQuarter | 另一个YearQuarter
      Returns:
      true if after | 如果在之后返回true

    • compareTo

      public int compareTo(YearQuarter other)
      Specified by:
      compareTo in interface Comparable<YearQuarter>

    • format

      public String format()
      Formats this YearQuarter using the default format (2024-Q1) 使用默认格式(2024-Q1)格式化此YearQuarter
      Returns:
      the formatted string | 格式化的字符串

    • format

      public String format(DateTimeFormatter formatter)
      Formats this YearQuarter using the specified formatter 使用指定格式化器格式化此YearQuarter
      Parameters:
      formatter - the formatter to use | 要使用的格式化器
      Returns:
      the formatted string | 格式化的字符串

    • isSupported

      public boolean isSupported(TemporalField field)
      Specified by:
      isSupported in interface TemporalAccessor

    • isSupported

      public boolean isSupported(TemporalUnit unit)
      Specified by:
      isSupported in interface Temporal

    • getLong

      public long getLong(TemporalField field)
      Specified by:
      getLong in interface TemporalAccessor

    • range

      public ValueRange range(TemporalField field)
      Specified by:
      range in interface TemporalAccessor

    • with

      public Temporal with(TemporalField field, long newValue)
      Specified by:
      with in interface Temporal

    • plus

      public Temporal plus(long amountToAdd, TemporalUnit unit)
      Specified by:
      plus in interface Temporal

    • until

      public long until(Temporal endExclusive, TemporalUnit unit)
      Specified by:
      until in interface Temporal

    • adjustInto

      public Temporal adjustInto(Temporal temporal)
      Specified by:
      adjustInto in interface TemporalAdjuster

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object