Class YearWeek

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

This class represents an ISO week-based year and week combination, such as "2024-W01" for the first week of 2024. The week numbering follows ISO-8601 standard where week 1 is the first week containing at least 4 days of the new year.

此类表示基于ISO的年份和周的组合，例如"2024-W01"表示2024年第一周。 周编号遵循ISO-8601标准，第1周是包含新年至少4天的第一周。

Features | 主要功能:

  • Create from week-based year and week - 从周基准年和周创建
  • Parse from string format (2024-W01) - 从字符串格式解析
  • Add/subtract weeks and years - 加减周和年
  • Get specific day of week - 获取特定星期几的日期
  • ISO-8601 compliant week numbering - 符合ISO-8601的周编号

Usage Examples | 使用示例:

// Create YearWeek
YearWeek yw = YearWeek.of(2024, 1);     // 2024-W01
YearWeek now = YearWeek.now();          // Current week

// Parse from string
YearWeek parsed = YearWeek.parse("2024-W01");

// Calculate
YearWeek next = yw.plusWeeks(1);        // 2024-W02
YearWeek prev = yw.minusYears(1);       // 2023-W01

// Get specific day
LocalDate monday = yw.atMonday();       // First Monday of week
LocalDate friday = yw.atDay(DayOfWeek.FRIDAY);

// Compare
boolean before = yw.isBefore(next);     // 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 YearWeek of(int weekBasedYear, int week)
      Creates a YearWeek from week-based year and week 从周基准年和周创建YearWeek
      Parameters:
      weekBasedYear - the week-based year | 周基准年
      week - the week number (1-52 or 53) | 周数（1-52或53）
      Returns:
      the YearWeek instance | YearWeek实例
      Throws:
      OpenDateException - if the week is invalid for the year | 如果周数对该年无效则抛出异常

    • from

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

    • now

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

    • now

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

    • now

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

    • parse

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

      Supported formats: "2024-W01", "2024W01"

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

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

    • parse

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

    • getYear

      public int getYear()
      Gets the week-based year 获取周基准年
      Returns:
      the week-based year | 周基准年

    • getWeek

      public int getWeek()
      Gets the week number (1-52 or 53) 获取周数（1-52或53）
      Returns:
      the week number | 周数

    • lengthOfYear

      public int lengthOfYear()
      Gets the number of weeks in this week-based year 获取此周基准年的周数
      Returns:
      52 or 53 | 52或53

    • isFirstWeek

      public boolean isFirstWeek()
      Checks if this is the first week of the year 检查是否为年度第一周
      Returns:
      true if week 1 | 如果是第1周返回true

    • isLastWeek

      public boolean isLastWeek()
      Checks if this is the last week of the year 检查是否为年度最后一周
      Returns:
      true if last week | 如果是最后一周返回true

    • plusYears

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

    • plusWeeks

      public YearWeek plusWeeks(long weeks)
      Adds weeks to this YearWeek 在此YearWeek基础上加周数
      Parameters:
      weeks - the weeks to add | 要加的周数
      Returns:
      a new YearWeek | 新的YearWeek

    • minusYears

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

    • minusWeeks

      public YearWeek minusWeeks(long weeks)
      Subtracts weeks from this YearWeek 在此YearWeek基础上减周数
      Parameters:
      weeks - the weeks to subtract | 要减的周数
      Returns:
      a new YearWeek | 新的YearWeek

    • atDay

      public LocalDate atDay(DayOfWeek dayOfWeek)
      Gets the date for a specific day of week within this week 获取此周内特定星期几的日期
      Parameters:
      dayOfWeek - the day of week | 星期几
      Returns:
      the LocalDate | LocalDate
      Throws:
      NullPointerException - if dayOfWeek is null | 如果dayOfWeek为null则抛出异常

    • atMonday

      public LocalDate atMonday()
      Gets the Monday of this week 获取此周的周一
      Returns:
      the Monday date | 周一日期

    • atTuesday

      public LocalDate atTuesday()
      Gets the Tuesday of this week 获取此周的周二
      Returns:
      the Tuesday date | 周二日期

    • atWednesday

      public LocalDate atWednesday()
      Gets the Wednesday of this week 获取此周的周三
      Returns:
      the Wednesday date | 周三日期

    • atThursday

      public LocalDate atThursday()
      Gets the Thursday of this week 获取此周的周四
      Returns:
      the Thursday date | 周四日期

    • atFriday

      public LocalDate atFriday()
      Gets the Friday of this week 获取此周的周五
      Returns:
      the Friday date | 周五日期

    • atSaturday

      public LocalDate atSaturday()
      Gets the Saturday of this week 获取此周的周六
      Returns:
      the Saturday date | 周六日期

    • atSunday

      public LocalDate atSunday()
      Gets the Sunday of this week 获取此周的周日
      Returns:
      the Sunday date | 周日日期

    • isBefore

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

    • isAfter

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

    • compareTo

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

    • format

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

    • format

      public String format(DateTimeFormatter formatter)
      Formats this YearWeek using the specified formatter 使用指定格式化器格式化此YearWeek
      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