Class ClosestDate

java.lang.Object
cloud.opencode.base.date.ClosestDate
public final class ClosestDate extends Object
Utility for finding the closest date in a collection 在集合中查找最接近日期的工具类

This class provides static methods to find the closest LocalDate or LocalDateTime to a given target from a collection of candidates. It supports finding the overall closest, the closest before, or the closest after the target.

此类提供静态方法，从候选集合中查找与给定目标最接近的 LocalDate 或 LocalDateTime。支持查找总体最接近、目标之前最接近或目标之后最接近的日期。

Features | 主要功能:

  • Find closest date to a target - 查找最接近目标的日期
  • Find closest date strictly before target - 查找严格在目标之前最接近的日期
  • Find closest date strictly after target - 查找严格在目标之后最接近的日期
  • Support for both LocalDate and LocalDateTime - 同时支持 LocalDate 和 LocalDateTime

Usage Examples | 使用示例:

List<LocalDate> dates = List.of(
    LocalDate.of(2024, 1, 1),
    LocalDate.of(2024, 6, 15),
    LocalDate.of(2024, 12, 31)
);
LocalDate target = LocalDate.of(2024, 6, 10);

Optional<LocalDate> closest = ClosestDate.closestTo(target, dates);
// returns 2024-06-15

Optional<LocalDate> before = ClosestDate.closestBefore(target, dates);
// returns 2024-01-01

Optional<LocalDate> after = ClosestDate.closestAfter(target, dates);
// returns 2024-06-15

Security | 安全性:

  • Thread-safe: Yes (stateless) - 线程安全: 是（无状态）
  • Null-safe: Yes (null target throws NullPointerException) - 空值安全: 是（null 目标抛出 NullPointerException）
Since:
JDK 25, opencode-base-date V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Details

    • closestTo

      public static Optional<LocalDate> closestTo(LocalDate target, Collection<LocalDate> dates)
      Finds the closest date to the target from the given collection. 从给定集合中查找最接近目标的日期。

      If two dates are equally close, the earlier one is returned.

      如果两个日期距离相等，则返回较早的那个。

      Parameters:
      target - the target date to compare against | 要比较的目标日期
      dates - the collection of candidate dates | 候选日期集合
      Returns:
      the closest date, or empty if collection is null or empty | 最接近的日期，如果集合为 null 或空则返回空
      Throws:
      NullPointerException - if target is null | 如果目标为 null 则抛出空指针异常

    • closestBefore

      public static Optional<LocalDate> closestBefore(LocalDate target, Collection<LocalDate> dates)
      Finds the closest date strictly before the target. 查找严格在目标之前最接近的日期。
      Parameters:
      target - the target date | 目标日期
      dates - the collection of candidate dates | 候选日期集合
      Returns:
      the closest date before target, or empty if none found | 目标之前最接近的日期，如果未找到则返回空
      Throws:
      NullPointerException - if target is null | 如果目标为 null 则抛出空指针异常

    • closestAfter

      public static Optional<LocalDate> closestAfter(LocalDate target, Collection<LocalDate> dates)
      Finds the closest date strictly after the target. 查找严格在目标之后最接近的日期。
      Parameters:
      target - the target date | 目标日期
      dates - the collection of candidate dates | 候选日期集合
      Returns:
      the closest date after target, or empty if none found | 目标之后最接近的日期，如果未找到则返回空
      Throws:
      NullPointerException - if target is null | 如果目标为 null 则抛出空指针异常

    • closestTo

      public static Optional<LocalDateTime> closestTo(LocalDateTime target, Collection<LocalDateTime> dateTimes)
      Finds the closest date-time to the target from the given collection. 从给定集合中查找最接近目标的日期时间。

      Comparison is based on nanosecond precision. If two date-times are equally close, the earlier one is returned.

      比较基于纳秒精度。如果两个日期时间距离相等，则返回较早的那个。

      Parameters:
      target - the target date-time to compare against | 要比较的目标日期时间
      dateTimes - the collection of candidate date-times | 候选日期时间集合
      Returns:
      the closest date-time, or empty if collection is null or empty | 最接近的日期时间，如果集合为 null 或空则返回空
      Throws:
      NullPointerException - if target is null | 如果目标为 null 则抛出空指针异常

    • closestBefore

      public static Optional<LocalDateTime> closestBefore(LocalDateTime target, Collection<LocalDateTime> dateTimes)
      Finds the closest date-time strictly before the target. 查找严格在目标之前最接近的日期时间。
      Parameters:
      target - the target date-time | 目标日期时间
      dateTimes - the collection of candidate date-times | 候选日期时间集合
      Returns:
      the closest date-time before target, or empty if none found | 目标之前最接近的日期时间，如果未找到则返回空
      Throws:
      NullPointerException - if target is null | 如果目标为 null 则抛出空指针异常

    • closestAfter

      public static Optional<LocalDateTime> closestAfter(LocalDateTime target, Collection<LocalDateTime> dateTimes)
      Finds the closest date-time strictly after the target. 查找严格在目标之后最接近的日期时间。
      Parameters:
      target - the target date-time | 目标日期时间
      dateTimes - the collection of candidate date-times | 候选日期时间集合
      Returns:
      the closest date-time after target, or empty if none found | 目标之后最接近的日期时间，如果未找到则返回空
      Throws:
      NullPointerException - if target is null | 如果目标为 null 则抛出空指针异常