Class DateRounding

java.lang.Object
cloud.opencode.base.date.DateRounding
public final class DateRounding extends Object
Utility for rounding date/time values to various intervals 将日期时间值舍入到各种间隔的工具类

This class provides static methods to round, floor, and ceil LocalDateTime values to specified time intervals such as hours, minutes, half hours, quarter hours, and arbitrary Duration values.

此类提供静态方法，将 LocalDateTime 值舍入、向下取整和向上取整到指定的时间间隔， 如小时、分钟、半小时、刻钟以及任意 Duration 值。

Features | 主要功能:

  • Round to nearest hour/minute - 舍入到最接近的小时/分钟
  • Floor and ceil operations - 向下取整和向上取整操作
  • Round to arbitrary N-minute intervals - 舍入到任意 N 分钟间隔
  • Round to arbitrary Duration intervals - 舍入到任意 Duration 间隔
  • Half-hour and quarter-hour rounding - 半小时和刻钟舍入

Usage Examples | 使用示例:

LocalDateTime dt = LocalDateTime.of(2024, 6, 15, 10, 37, 45);

DateRounding.roundToNearestHour(dt);        // 2024-06-15T11:00
DateRounding.floorToHour(dt);               // 2024-06-15T10:00
DateRounding.ceilToHour(dt);                // 2024-06-15T11:00
DateRounding.roundToNearest(dt, 15);        // 2024-06-15T10:45
DateRounding.roundToNearestHalfHour(dt);    // 2024-06-15T10:30

Duration fiveMin = Duration.ofMinutes(5);
DateRounding.roundToNearest(dt, fiveMin);   // 2024-06-15T10:40

Note | 注意: Generic Duration rounding uses UTC epoch seconds as the reference point. This means results are consistent regardless of timezone but may not align with local midnight for durations that don't evenly divide 24 hours.

通用 Duration 舍入使用 UTC 纪元秒作为参考点。这意味着结果在各时区间一致， 但对于不能整除 24 小时的间隔，结果可能不与本地午夜对齐。

Security | 安全性:

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

  • Method Details

    • roundToNearestHour

      public static LocalDateTime roundToNearestHour(LocalDateTime dateTime)
      Rounds to the nearest hour. Minutes >= 30 round up, otherwise round down. 舍入到最接近的小时。分钟 >= 30 向上舍入，否则向下舍入。
      Parameters:
      dateTime - the date-time to round | 要舍入的日期时间
      Returns:
      the rounded date-time | 舍入后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • ceilToHour

      public static LocalDateTime ceilToHour(LocalDateTime dateTime)
      Ceils to the next hour boundary. If already at an exact hour, returns unchanged. 向上取整到下一个小时边界。如果已经在整点，则原样返回。
      Parameters:
      dateTime - the date-time to ceil | 要向上取整的日期时间
      Returns:
      the ceiled date-time | 向上取整后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • floorToHour

      public static LocalDateTime floorToHour(LocalDateTime dateTime)
      Floors to the current hour boundary. 向下取整到当前小时边界。
      Parameters:
      dateTime - the date-time to floor | 要向下取整的日期时间
      Returns:
      the floored date-time | 向下取整后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • roundToNearestMinute

      public static LocalDateTime roundToNearestMinute(LocalDateTime dateTime)
      Rounds to the nearest minute. Seconds >= 30 round up, otherwise round down. 舍入到最接近的分钟。秒 >= 30 向上舍入，否则向下舍入。
      Parameters:
      dateTime - the date-time to round | 要舍入的日期时间
      Returns:
      the rounded date-time | 舍入后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • ceilToMinute

      public static LocalDateTime ceilToMinute(LocalDateTime dateTime)
      Ceils to the next minute boundary. If already at an exact minute, returns unchanged. 向上取整到下一个分钟边界。如果已经在整分钟，则原样返回。
      Parameters:
      dateTime - the date-time to ceil | 要向上取整的日期时间
      Returns:
      the ceiled date-time | 向上取整后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • floorToMinute

      public static LocalDateTime floorToMinute(LocalDateTime dateTime)
      Floors to the current minute boundary. 向下取整到当前分钟边界。
      Parameters:
      dateTime - the date-time to floor | 要向下取整的日期时间
      Returns:
      the floored date-time | 向下取整后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • roundToNearest

      public static LocalDateTime roundToNearest(LocalDateTime dateTime, int minutes)
      Rounds to the nearest N-minute interval. 舍入到最接近的 N 分钟间隔。

      For example, with minutes=15, 10:07 rounds to 10:00 and 10:08 rounds to 10:15.

      例如，minutes=15 时，10:07 舍入到 10:00，10:08 舍入到 10:15。

      Parameters:
      dateTime - the date-time to round | 要舍入的日期时间
      minutes - the interval in minutes (must be positive) | 间隔分钟数（必须为正数）
      Returns:
      the rounded date-time | 舍入后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常
      OpenDateException - if minutes is not positive | 如果分钟数不为正数则抛出异常

    • roundToNearestHalfHour

      public static LocalDateTime roundToNearestHalfHour(LocalDateTime dateTime)
      Rounds to the nearest half hour (30-minute interval). 舍入到最接近的半小时（30 分钟间隔）。
      Parameters:
      dateTime - the date-time to round | 要舍入的日期时间
      Returns:
      the rounded date-time | 舍入后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • roundToNearestQuarterHour

      public static LocalDateTime roundToNearestQuarterHour(LocalDateTime dateTime)
      Rounds to the nearest quarter hour (15-minute interval). 舍入到最接近的刻钟（15 分钟间隔）。
      Parameters:
      dateTime - the date-time to round | 要舍入的日期时间
      Returns:
      the rounded date-time | 舍入后的日期时间
      Throws:
      NullPointerException - if dateTime is null | 如果 dateTime 为 null 则抛出空指针异常

    • roundToNearest

      public static LocalDateTime roundToNearest(LocalDateTime dateTime, Duration duration)
      Rounds to the nearest multiple of the given duration. 舍入到给定持续时间的最接近倍数。

      Uses UTC epoch seconds as the reference point for alignment. For sub-second durations, nanosecond precision is used.

      使用 UTC 纪元秒作为对齐参考点。对于亚秒级持续时间，使用纳秒精度。

      Parameters:
      dateTime - the date-time to round | 要舍入的日期时间
      duration - the rounding interval (must be positive) | 舍入间隔（必须为正数）
      Returns:
      the rounded date-time | 舍入后的日期时间
      Throws:
      NullPointerException - if dateTime or duration is null | 如果 dateTime 或 duration 为 null 则抛出空指针异常
      OpenDateException - if duration is zero or negative | 如果 duration 为零或负数则抛出异常

    • ceilTo

      public static LocalDateTime ceilTo(LocalDateTime dateTime, Duration duration)
      Ceils to the next multiple of the given duration. 向上取整到给定持续时间的下一个倍数。

      If the date-time is already exactly on a boundary, returns unchanged.

      如果日期时间已经在边界上，则原样返回。

      Parameters:
      dateTime - the date-time to ceil | 要向上取整的日期时间
      duration - the interval (must be positive) | 间隔（必须为正数）
      Returns:
      the ceiled date-time | 向上取整后的日期时间
      Throws:
      NullPointerException - if dateTime or duration is null | 如果 dateTime 或 duration 为 null 则抛出空指针异常
      OpenDateException - if duration is zero or negative | 如果 duration 为零或负数则抛出异常

    • floorTo

      public static LocalDateTime floorTo(LocalDateTime dateTime, Duration duration)
      Floors to the current multiple of the given duration. 向下取整到给定持续时间的当前倍数。
      Parameters:
      dateTime - the date-time to floor | 要向下取整的日期时间
      duration - the interval (must be positive) | 间隔（必须为正数）
      Returns:
      the floored date-time | 向下取整后的日期时间
      Throws:
      NullPointerException - if dateTime or duration is null | 如果 dateTime 或 duration 为 null 则抛出空指针异常
      OpenDateException - if duration is zero or negative | 如果 duration 为零或负数则抛出异常