java.lang.Object

cloud.opencode.base.date.TemporalUtil

public final class TemporalUtil extends Object

Utility class for temporal operations 时间操作工具类

This class provides utility methods for working with temporal objects, including type conversions, comparisons, and common operations.

此类提供处理时间对象的工具方法，包括类型转换、比较和常用操作。

Features | 主要功能:

Type conversions between temporal types - 时间类型之间的转换
Comparison utilities - 比较工具
Truncation and rounding - 截断和取整
Range and boundary operations - 范围和边界操作

Usage Examples | 使用示例:

// Convert between types
LocalDateTime dateTime = TemporalUtil.toLocalDateTime(instant, ZoneId.systemDefault());
Instant instant = TemporalUtil.toInstant(localDateTime, ZoneId.systemDefault());

// Comparisons
boolean between = TemporalUtil.isBetween(date, start, end);
LocalDate max = TemporalUtil.max(date1, date2);

// Truncation
LocalDateTime startOfDay = TemporalUtil.startOfDay(dateTime);
LocalDateTime endOfMonth = TemporalUtil.endOfMonth(dateTime);

Security | 安全性:

Thread-safe: Yes - 线程安全: 是
Null-safe: Yes (with explicit null checks) - 空值安全: 是（有明确的空值检查）

Performance | 性能特性:

Time complexity: O(1) - all operations are constant-time type conversions and comparisons - 时间复杂度: O(1) - 所有操作均为常数时间的类型转换和比较
Space complexity: O(1) - no additional data structures allocated - 空间复杂度: O(1) - 不分配额外的数据结构

Since:

JDK 25, opencode-base-date V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Method Summary

Modifier and Type

Method

Description

static int

compareTemporal(Object a, Object b)

Compares two temporal/date objects generically.

static long

daysBetween(LocalDate start, LocalDate end)

Calculates days between two dates 计算两个日期之间的天数

static int

daysInMonth(int year, int month)

Gets the number of days in a month 获取月份的天数

static int

daysInMonth(YearMonth yearMonth)

Gets the number of days in a month 获取月份的天数

static LocalDateTime

endOfDay(LocalDateTime dateTime)

Gets the end of day for a date-time 获取日期时间的当天结束

static LocalDateTime

endOfMonth(LocalDateTime dateTime)

Gets the end of month for a date-time 获取日期时间的当月结束

static LocalDateTime

endOfWeek(LocalDateTime dateTime)

Gets the end of week for a date-time (Sunday) 获取日期时间的当周结束（周日）

static LocalDateTime

endOfYear(LocalDateTime dateTime)

Gets the end of year for a date-time 获取日期时间的当年结束

static LocalDateTime

fromEpochMilli(long epochMilli)

Converts epoch milliseconds to LocalDateTime 将纪元毫秒转换为LocalDateTime

static LocalDateTime

fromEpochSecond(long epochSecond)

Converts epoch seconds to LocalDateTime 将纪元秒转换为LocalDateTime

static int

getQuarter(int month)

Gets the quarter for a month (1-4) 获取月份的季度（1-4）

static int

getQuarter(LocalDate date)

Gets the quarter for a date (1-4) 获取日期的季度（1-4）

static long

hoursBetween(LocalDateTime start, LocalDateTime end)

Calculates hours between two date-times 计算两个日期时间之间的小时数

static boolean

isBetween(LocalDate date, LocalDate start, LocalDate end)

Checks if a date is between two dates (inclusive) 检查日期是否在两个日期之间（包含边界）

static boolean

isBetween(LocalDateTime dateTime, LocalDateTime start, LocalDateTime end)

Checks if a date-time is between two date-times (inclusive) 检查日期时间是否在两个日期时间之间（包含边界）

static boolean

isLeapYear(int year)

Checks if a year is a leap year 检查年份是否为闰年

static boolean

isLeapYear(LocalDate date)

Checks if a date is in a leap year 检查日期是否在闰年中

static boolean

isWeekday(LocalDate date)

Checks if a date is a weekday 检查日期是否为工作日（周一到周五）

static boolean

isWeekend(LocalDate date)

Checks if a date is a weekend 检查日期是否为周末

static LocalDate

max(LocalDate a, LocalDate b)

Gets the maximum of two dates 获取两个日期中的较大值

static LocalDateTime

max(LocalDateTime a, LocalDateTime b)

Gets the maximum of two date-times 获取两个日期时间中的较大值

static LocalDate

min(LocalDate a, LocalDate b)

Gets the minimum of two dates 获取两个日期中的较小值

static LocalDateTime

min(LocalDateTime a, LocalDateTime b)

Gets the minimum of two date-times 获取两个日期时间中的较小值

static long

minutesBetween(LocalDateTime start, LocalDateTime end)

Calculates minutes between two date-times 计算两个日期时间之间的分钟数

static long

monthsBetween(LocalDate start, LocalDate end)

Calculates months between two dates 计算两个日期之间的月数

static LocalDateTime

startOfDay(LocalDateTime dateTime)

Gets the start of day for a date-time 获取日期时间的当天开始

static LocalDateTime

startOfMonth(LocalDateTime dateTime)

Gets the start of month for a date-time 获取日期时间的当月开始

static LocalDateTime

startOfWeek(LocalDateTime dateTime)

Gets the start of week for a date-time (Monday) 获取日期时间的当周开始（周一）

static LocalDateTime

startOfYear(LocalDateTime dateTime)

Gets the start of year for a date-time 获取日期时间的当年开始

static long

toEpochMilli(LocalDateTime dateTime)

Converts LocalDateTime to epoch milliseconds 将LocalDateTime转换为纪元毫秒

static long

toEpochSecond(LocalDateTime dateTime)

Converts LocalDateTime to epoch seconds 将LocalDateTime转换为纪元秒

static Instant

toInstant(Object temporal)

Converts any supported temporal/date object to Instant.

static Instant

toInstant(LocalDateTime dateTime)

Converts a LocalDateTime to Instant using the system default zone 使用系统默认时区将LocalDateTime转换为Instant

static Instant

toInstant(LocalDateTime dateTime, ZoneId zone)

Converts a LocalDateTime to Instant using the specified zone 使用指定时区将LocalDateTime转换为Instant

static LocalDateTime

toLocalDateTime(Instant instant)

Converts an Instant to LocalDateTime using the system default zone 使用系统默认时区将Instant转换为LocalDateTime

static LocalDateTime

toLocalDateTime(Instant instant, ZoneId zone)

Converts an Instant to LocalDateTime using the specified zone 使用指定时区将Instant转换为LocalDateTime

static LocalDateTime

toLocalDateTime(LocalDate date)

Converts a LocalDate to LocalDateTime at start of day 将LocalDate转换为当天开始的LocalDateTime

static long

yearsBetween(LocalDate start, LocalDate end)

Calculates years between two dates 计算两个日期之间的年数

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- toLocalDateTime
  
  public static LocalDateTime toLocalDateTime(Instant instant, ZoneId zone)
  
  Converts an Instant to LocalDateTime using the specified zone 使用指定时区将Instant转换为LocalDateTime
  
  Parameters:
  
  instant - the instant | 瞬间
  
  zone - the zone | 时区
  
  Returns:
  
  the LocalDateTime | 本地日期时间
- toLocalDateTime
  
  public static LocalDateTime toLocalDateTime(Instant instant)
  
  Converts an Instant to LocalDateTime using the system default zone 使用系统默认时区将Instant转换为LocalDateTime
  
  Parameters:
  
  instant - the instant | 瞬间
  
  Returns:
  
  the LocalDateTime | 本地日期时间
- toInstant
  
  public static Instant toInstant(LocalDateTime dateTime, ZoneId zone)
  
  Converts a LocalDateTime to Instant using the specified zone 使用指定时区将LocalDateTime转换为Instant
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  zone - the zone | 时区
  
  Returns:
  
  the Instant | 瞬间
- toInstant
  
  public static Instant toInstant(LocalDateTime dateTime)
  
  Converts a LocalDateTime to Instant using the system default zone 使用系统默认时区将LocalDateTime转换为Instant
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the Instant | 瞬间
- toLocalDateTime
  
  public static LocalDateTime toLocalDateTime(LocalDate date)
  
  Converts a LocalDate to LocalDateTime at start of day 将LocalDate转换为当天开始的LocalDateTime
  
  Parameters:
  
  date - the date | 日期
  
  Returns:
  
  the LocalDateTime | 本地日期时间
- fromEpochMilli
  
  public static LocalDateTime fromEpochMilli(long epochMilli)
  
  Converts epoch milliseconds to LocalDateTime 将纪元毫秒转换为LocalDateTime
  
  Parameters:
  
  epochMilli - the epoch milliseconds | 纪元毫秒
  
  Returns:
  
  the LocalDateTime | 本地日期时间
- fromEpochSecond
  
  public static LocalDateTime fromEpochSecond(long epochSecond)
  
  Converts epoch seconds to LocalDateTime 将纪元秒转换为LocalDateTime
  
  Parameters:
  
  epochSecond - the epoch seconds | 纪元秒
  
  Returns:
  
  the LocalDateTime | 本地日期时间
- toEpochMilli
  
  public static long toEpochMilli(LocalDateTime dateTime)
  
  Converts LocalDateTime to epoch milliseconds 将LocalDateTime转换为纪元毫秒
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the epoch milliseconds | 纪元毫秒
- toEpochSecond
  
  public static long toEpochSecond(LocalDateTime dateTime)
  
  Converts LocalDateTime to epoch seconds 将LocalDateTime转换为纪元秒
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the epoch seconds | 纪元秒
- toInstant
  
  public static Instant toInstant(Object temporal)
  
  Converts any supported temporal/date object to Instant. 将任意支持的时间/日期对象转换为 Instant。
  Supports: Instant, LocalDate, LocalDateTime, ZonedDateTime, OffsetDateTime, java.util.Date, java.util.Calendar. Uses system default timezone for local types.
  
  支持：Instant、LocalDate、LocalDateTime、ZonedDateTime、OffsetDateTime、 java.util.Date、java.util.Calendar。本地类型使用系统默认时区。
  
  Parameters:
  
  temporal - the temporal object | 时间对象
  
  Returns:
  
  the Instant, or null if unsupported type | Instant，不支持的类型返回 null
- compareTemporal
  
  public static int compareTemporal(Object a, Object b)
  
  Compares two temporal/date objects generically. 通用比较两个时间/日期对象。
  If both objects are the same Comparable type, uses natural ordering. Otherwise falls back to Instant conversion for cross-type comparison.
  
  如果两个对象是相同的 Comparable 类型，使用自然排序。否则回退到 Instant 转换进行跨类型比较。
  
  Parameters:
  
  a - the first temporal | 第一个时间
  
  b - the second temporal | 第二个时间
  
  Returns:
  
  negative if a < b, 0 if equal, positive if a > b
  
  Throws:
  
  IllegalArgumentException - if types are not comparable | 类型不可比较时抛出
- isBetween
  
  public static boolean isBetween(LocalDate date, LocalDate start, LocalDate end)
  
  Checks if a date is between two dates (inclusive) 检查日期是否在两个日期之间（包含边界）
  
  Parameters:
  
  date - the date to check | 要检查的日期
  
  start - the start date | 开始日期
  
  end - the end date | 结束日期
  
  Returns:
  
  true if between | 如果在之间返回true
- isBetween
  
  public static boolean isBetween(LocalDateTime dateTime, LocalDateTime start, LocalDateTime end)
  
  Checks if a date-time is between two date-times (inclusive) 检查日期时间是否在两个日期时间之间（包含边界）
  
  Parameters:
  
  dateTime - the date-time to check | 要检查的日期时间
  
  start - the start date-time | 开始日期时间
  
  end - the end date-time | 结束日期时间
  
  Returns:
  
  true if between | 如果在之间返回true
- max
  
  public static LocalDate max(LocalDate a, LocalDate b)
  
  Gets the maximum of two dates 获取两个日期中的较大值
  
  Parameters:
  
  a - the first date | 第一个日期
  
  b - the second date | 第二个日期
  
  Returns:
  
  the maximum | 较大值
- min
  
  public static LocalDate min(LocalDate a, LocalDate b)
  
  Gets the minimum of two dates 获取两个日期中的较小值
  
  Parameters:
  
  a - the first date | 第一个日期
  
  b - the second date | 第二个日期
  
  Returns:
  
  the minimum | 较小值
- max
  
  public static LocalDateTime max(LocalDateTime a, LocalDateTime b)
  
  Gets the maximum of two date-times 获取两个日期时间中的较大值
  
  Parameters:
  
  a - the first date-time | 第一个日期时间
  
  b - the second date-time | 第二个日期时间
  
  Returns:
  
  the maximum | 较大值
- min
  
  public static LocalDateTime min(LocalDateTime a, LocalDateTime b)
  
  Gets the minimum of two date-times 获取两个日期时间中的较小值
  
  Parameters:
  
  a - the first date-time | 第一个日期时间
  
  b - the second date-time | 第二个日期时间
  
  Returns:
  
  the minimum | 较小值
- startOfDay
  
  public static LocalDateTime startOfDay(LocalDateTime dateTime)
  
  Gets the start of day for a date-time 获取日期时间的当天开始
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the start of day | 当天开始
- endOfDay
  
  public static LocalDateTime endOfDay(LocalDateTime dateTime)
  
  Gets the end of day for a date-time 获取日期时间的当天结束
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the end of day | 当天结束
- startOfMonth
  
  public static LocalDateTime startOfMonth(LocalDateTime dateTime)
  
  Gets the start of month for a date-time 获取日期时间的当月开始
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the start of month | 当月开始
- endOfMonth
  
  public static LocalDateTime endOfMonth(LocalDateTime dateTime)
  
  Gets the end of month for a date-time 获取日期时间的当月结束
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the end of month | 当月结束
- startOfYear
  
  public static LocalDateTime startOfYear(LocalDateTime dateTime)
  
  Gets the start of year for a date-time 获取日期时间的当年开始
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the start of year | 当年开始
- endOfYear
  
  public static LocalDateTime endOfYear(LocalDateTime dateTime)
  
  Gets the end of year for a date-time 获取日期时间的当年结束
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the end of year | 当年结束
- startOfWeek
  
  public static LocalDateTime startOfWeek(LocalDateTime dateTime)
  
  Gets the start of week for a date-time (Monday) 获取日期时间的当周开始（周一）
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the start of week | 当周开始
- endOfWeek
  
  public static LocalDateTime endOfWeek(LocalDateTime dateTime)
  
  Gets the end of week for a date-time (Sunday) 获取日期时间的当周结束（周日）
  
  Parameters:
  
  dateTime - the date-time | 日期时间
  
  Returns:
  
  the end of week | 当周结束
- daysBetween
  
  public static long daysBetween(LocalDate start, LocalDate end)
  
  Calculates days between two dates 计算两个日期之间的天数
  
  Parameters:
  
  start - the start date | 开始日期
  
  end - the end date | 结束日期
  
  Returns:
  
  the number of days | 天数
- monthsBetween
  
  public static long monthsBetween(LocalDate start, LocalDate end)
  
  Calculates months between two dates 计算两个日期之间的月数
  
  Parameters:
  
  start - the start date | 开始日期
  
  end - the end date | 结束日期
  
  Returns:
  
  the number of months | 月数
- yearsBetween
  
  public static long yearsBetween(LocalDate start, LocalDate end)
  
  Calculates years between two dates 计算两个日期之间的年数
  
  Parameters:
  
  start - the start date | 开始日期
  
  end - the end date | 结束日期
  
  Returns:
  
  the number of years | 年数
- hoursBetween
  
  public static long hoursBetween(LocalDateTime start, LocalDateTime end)
  
  Calculates hours between two date-times 计算两个日期时间之间的小时数
  
  Parameters:
  
  start - the start date-time | 开始日期时间
  
  end - the end date-time | 结束日期时间
  
  Returns:
  
  the number of hours | 小时数
- minutesBetween
  
  public static long minutesBetween(LocalDateTime start, LocalDateTime end)
  
  Calculates minutes between two date-times 计算两个日期时间之间的分钟数
  
  Parameters:
  
  start - the start date-time | 开始日期时间
  
  end - the end date-time | 结束日期时间
  
  Returns:
  
  the number of minutes | 分钟数
- isWeekend
  
  public static boolean isWeekend(LocalDate date)
  
  Checks if a date is a weekend 检查日期是否为周末
  
  Parameters:
  
  date - the date | 日期
  
  Returns:
  
  true if weekend | 如果是周末返回true
- isWeekday
  
  public static boolean isWeekday(LocalDate date)
  
  Checks if a date is a weekday 检查日期是否为工作日（周一到周五）
  
  Parameters:
  
  date - the date | 日期
  
  Returns:
  
  true if weekday | 如果是工作日返回true
- isLeapYear
  
  public static boolean isLeapYear(int year)
  
  Checks if a year is a leap year 检查年份是否为闰年
  
  Parameters:
  
  year - the year | 年份
  
  Returns:
  
  true if leap year | 如果是闰年返回true
- isLeapYear
  
  public static boolean isLeapYear(LocalDate date)
  
  Checks if a date is in a leap year 检查日期是否在闰年中
  
  Parameters:
  
  date - the date | 日期
  
  Returns:
  
  true if in leap year | 如果在闰年中返回true
- daysInMonth
  
  public static int daysInMonth(int year, int month)
  
  Gets the number of days in a month 获取月份的天数
  
  Parameters:
  
  year - the year | 年份
  
  month - the month | 月份
  
  Returns:
  
  the number of days | 天数
- daysInMonth
  
  public static int daysInMonth(YearMonth yearMonth)
  
  Gets the number of days in a month 获取月份的天数
  
  Parameters:
  
  yearMonth - the year-month | 年月
  
  Returns:
  
  the number of days | 天数
- getQuarter
  
  public static int getQuarter(int month)
  
  Gets the quarter for a month (1-4) 获取月份的季度（1-4）
  
  Parameters:
  
  month - the month (1-12) | 月份（1-12）
  
  Returns:
  
  the quarter (1-4) | 季度（1-4）
- getQuarter
  
  public static int getQuarter(LocalDate date)
  
  Gets the quarter for a date (1-4) 获取日期的季度（1-4）
  
  Parameters:
  
  date - the date | 日期
  
  Returns:
  
  the quarter (1-4) | 季度（1-4）

Class TemporalUtil

Method Summary

Methods inherited from class Object

Method Details

toLocalDateTime

toLocalDateTime

toInstant

toInstant

toLocalDateTime

fromEpochMilli

fromEpochSecond

toEpochMilli

toEpochSecond

toInstant

compareTemporal

isBetween

isBetween

max

min

max

min

startOfDay

endOfDay

startOfMonth

endOfMonth

startOfYear

endOfYear

startOfWeek

endOfWeek

daysBetween

monthsBetween

yearsBetween

hoursBetween

minutesBetween

isWeekend

isWeekday

isLeapYear

isLeapYear

daysInMonth

daysInMonth

getQuarter

getQuarter