Class DateDiff

java.lang.Object
cloud.opencode.base.date.between.DateDiff
public final class DateDiff extends Object
Detailed date difference breakdown with years, months, and days 详细的日期差异分解，包含年、月、日

This class provides a detailed breakdown of the difference between two dates, showing the exact number of years, months, days, hours, minutes, and seconds.

此类提供两个日期之间差异的详细分解，显示精确的年数、月数、天数、 小时数、分钟数和秒数。

Features | 主要功能:

  • Complete breakdown in human-readable units - 完整的人类可读单位分解
  • Support for dates and date-times - 支持日期和日期时间
  • Formatted output - 格式化输出

Usage Examples | 使用示例:

LocalDate birth = LocalDate.of(1990, 5, 15);
LocalDate today = LocalDate.of(2024, 3, 20);

DateDiff diff = DateDiff.of(birth, today);
System.out.println(diff.getYears());   // 33
System.out.println(diff.getMonths());  // 10
System.out.println(diff.getDays());    // 5
System.out.println(diff);              // "33 years, 10 months, 5 days"

Security | 安全性:

  • Thread-safe: Yes (immutable) - 线程安全: 是（不可变）
  • Null-safe: Yes (with explicit null checks) - 空值安全: 是（有明确的空值检查）
Since:
JDK 25, opencode-base-date V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object o)
     
    String
    format()
    Formats as a human-readable string 格式化为人类可读的字符串
    String
    formatChinese()
    Formats as a Chinese human-readable string 格式化为中文人类可读的字符串
    int
    getDays()
    Gets the number of days (0-30) 获取天数（0-30）
    Temporal
    getEnd()
    Gets the end temporal 获取结束时间
    int
    getHours()
    Gets the number of hours (0-23) 获取小时数（0-23）
    int
    getMinutes()
    Gets the number of minutes (0-59) 获取分钟数（0-59）
    int
    getMonths()
    Gets the number of complete months (0-11) 获取完整月数（0-11）
    int
    getSeconds()
    Gets the number of seconds (0-59) 获取秒数（0-59）
    Temporal
    getStart()
    Gets the start temporal 获取开始时间
    int
    getYears()
    Gets the number of complete years 获取完整年数
    int
    hashCode()
     
    boolean
    isNegative()
    Checks if the difference is negative (end before start) 检查差异是否为负（结束在开始之前）
    static DateDiff
    of(LocalDate start, LocalDate end)
    Creates a DateDiff from two LocalDate objects 从两个LocalDate对象创建DateDiff
    static DateDiff
    of(LocalDateTime start, LocalDateTime end)
    Creates a DateDiff from two LocalDateTime objects 从两个LocalDateTime对象创建DateDiff
    static DateDiff
    of(Temporal start, Temporal end)
    Creates a DateDiff from any two Temporal objects 从任意两个Temporal对象创建DateDiff
    Period
    toPeriod()
    Converts to Period (date part only) 转换为Period（仅日期部分）
    String
    toString()
     
    long
    toTotalDays()
    Converts to total days (approximate for months/years) 转换为总天数（月/年为近似值）

    Methods inherited from class Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Method Details

    • of

      public static DateDiff of(LocalDate start, LocalDate end)
      Creates a DateDiff from two LocalDate objects 从两个LocalDate对象创建DateDiff
      Parameters:
      start - the start date | 开始日期
      end - the end date | 结束日期
      Returns:
      the DateDiff instance | DateDiff实例

    • of

      public static DateDiff of(LocalDateTime start, LocalDateTime end)
      Creates a DateDiff from two LocalDateTime objects 从两个LocalDateTime对象创建DateDiff
      Parameters:
      start - the start date-time | 开始日期时间
      end - the end date-time | 结束日期时间
      Returns:
      the DateDiff instance | DateDiff实例

    • of

      public static DateDiff of(Temporal start, Temporal end)
      Creates a DateDiff from any two Temporal objects 从任意两个Temporal对象创建DateDiff
      Parameters:
      start - the start temporal | 开始时间
      end - the end temporal | 结束时间
      Returns:
      the DateDiff instance | DateDiff实例

    • getYears

      public int getYears()
      Gets the number of complete years 获取完整年数
      Returns:
      the years | 年数

    • getMonths

      public int getMonths()
      Gets the number of complete months (0-11) 获取完整月数（0-11）
      Returns:
      the months | 月数

    • getDays

      public int getDays()
      Gets the number of days (0-30) 获取天数（0-30）
      Returns:
      the days | 天数

    • getHours

      public int getHours()
      Gets the number of hours (0-23) 获取小时数（0-23）
      Returns:
      the hours | 小时数

    • getMinutes

      public int getMinutes()
      Gets the number of minutes (0-59) 获取分钟数（0-59）
      Returns:
      the minutes | 分钟数

    • getSeconds

      public int getSeconds()
      Gets the number of seconds (0-59) 获取秒数（0-59）
      Returns:
      the seconds | 秒数

    • isNegative

      public boolean isNegative()
      Checks if the difference is negative (end before start) 检查差异是否为负（结束在开始之前）
      Returns:
      true if negative | 如果为负返回true

    • getStart

      public Temporal getStart()
      Gets the start temporal 获取开始时间
      Returns:
      the start temporal | 开始时间

    • getEnd

      public Temporal getEnd()
      Gets the end temporal 获取结束时间
      Returns:
      the end temporal | 结束时间

    • toTotalDays

      public long toTotalDays()
      Converts to total days (approximate for months/years) 转换为总天数（月/年为近似值）
      Returns:
      the total days | 总天数

    • toPeriod

      public Period toPeriod()
      Converts to Period (date part only) 转换为Period（仅日期部分）
      Returns:
      the Period | Period对象

    • format

      public String format()
      Formats as a human-readable string 格式化为人类可读的字符串
      Returns:
      the formatted string | 格式化字符串

    • formatChinese

      public String formatChinese()
      Formats as a Chinese human-readable string 格式化为中文人类可读的字符串
      Returns:
      the formatted string | 格式化字符串

    • equals

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object