547 lines
17 KiB
Kotlin
547 lines
17 KiB
Kotlin
/*
|
||
* Copyright 2026 mingliqiye
|
||
*
|
||
* Licensed under the Apache License, Version 2.0 (the "License");
|
||
* you may not use this file except in compliance with the License.
|
||
* You may obtain a copy of the License at
|
||
*
|
||
* http://www.apache.org/licenses/LICENSE-2.0
|
||
*
|
||
* Unless required by applicable law or agreed to in writing, software
|
||
* distributed under the License is distributed on an "AS IS" BASIS,
|
||
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||
* See the License for the specific language governing permissions and
|
||
* limitations under the License.
|
||
*
|
||
* ProjectName mingli-utils
|
||
* ModuleName mingli-utils.main
|
||
* CurrentFile DateTime.kt
|
||
* LastUpdate 2026-03-14 16:12:08
|
||
* UpdateUser MingLiPro
|
||
*/
|
||
|
||
package com.mingliqiye.utils.time
|
||
|
||
import io.swagger.v3.oas.annotations.media.Schema
|
||
import java.io.Serializable
|
||
import java.time.LocalDateTime
|
||
import java.time.ZoneId
|
||
import java.time.format.DateTimeFormatter
|
||
import java.time.temporal.ChronoUnit
|
||
import java.util.*
|
||
import kotlin.time.Instant
|
||
|
||
|
||
/**
|
||
* 时间类,用于处理日期时间的转换、格式化等操作。
|
||
* 提供了多种静态方法来创建 DateTime 实例,并支持与 Date、LocalDateTime 等类型的互转。
|
||
*<br>
|
||
* windows java 1.8 及以下 使用windows Api 获取高精度时间
|
||
*
|
||
* @author MingLiPro
|
||
* @see java.time
|
||
* @see LocalDateTime
|
||
* @see ChronoUnit
|
||
* @see Date
|
||
* @see DateTimeFormatter
|
||
* @see ZoneId
|
||
* @see Instant
|
||
*/
|
||
@Schema(
|
||
name = "DateTime",
|
||
description = "DateTime",
|
||
type = "string",
|
||
format = "date-time"
|
||
)
|
||
class DateTime private constructor(
|
||
private var localDateTime: LocalDateTime, private val zoneId: ZoneId = ZoneId.systemDefault(),
|
||
) : Serializable {
|
||
|
||
companion object {
|
||
/**
|
||
* 获取当前时间的 DateTime 实例。
|
||
* 如果运行在 Java 1.8 环境下,则通过 WinKernel32 获取高精度时间。
|
||
*
|
||
* @return 返回当前时间的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun now(): DateTime {
|
||
return DateTime(LocalDateTime.now())
|
||
}
|
||
|
||
/**
|
||
* 将 Date 对象转换为 DateTime 实例。
|
||
*
|
||
* @param zoneId 时区信息
|
||
* @param date Date 对象
|
||
* @return 返回对应的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(date: Date, zoneId: ZoneId): DateTime {
|
||
return DateTime(date.toInstant().atZone(zoneId).toLocalDateTime(), zoneId)
|
||
}
|
||
|
||
/**
|
||
* 将 Date 对象转换为 DateTime 实例,使用系统默认时区。
|
||
*
|
||
* @param date Date 对象
|
||
* @return 返回对应的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(date: Date): DateTime {
|
||
return DateTime(
|
||
date.toInstant().atZone(ZoneId.systemDefault()).toLocalDateTime()
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 根据 LocalDateTime 创建 DateTime 实例。
|
||
*
|
||
* @param localDateTime LocalDateTime 对象
|
||
* @return 返回对应的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(localDateTime: LocalDateTime): DateTime {
|
||
return DateTime(localDateTime)
|
||
}
|
||
|
||
|
||
/**
|
||
* 根据 LocalDateTime 创建 DateTime 实例。
|
||
*
|
||
* @param localDateTime LocalDateTime 对象
|
||
* @return 返回对应的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(instant: java.time.Instant, zoneId: ZoneId = ZoneId.systemDefault()): DateTime {
|
||
return DateTime(LocalDateTime.ofInstant(instant, zoneId))
|
||
}
|
||
|
||
/**
|
||
* 解析时间字符串并生成 DateTime 实例。
|
||
*
|
||
* @param timestr 时间字符串
|
||
* @param formatter 格式化模板
|
||
* @param fillZero 是否补零到模板长度
|
||
* @return 返回解析后的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun parse(
|
||
timestr: String, formatter: String, fillZero: Boolean,
|
||
): DateTime {
|
||
return DateTime(
|
||
LocalDateTime.parse(
|
||
if (fillZero) getFillZeroByLen(timestr, formatter) else timestr,
|
||
DateTimeFormatter.ofPattern(formatter)
|
||
)
|
||
)
|
||
}
|
||
|
||
@JvmStatic
|
||
fun parse(
|
||
timestr: String,
|
||
): DateTime {
|
||
|
||
val formatterString = Formatter.STANDARD_DATETIME_MILLISECOUND9.value
|
||
return DateTime(
|
||
LocalDateTime.parse(
|
||
getFillZeroByLen(timestr, formatterString), DateTimeFormatter.ofPattern(formatterString)
|
||
)
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 使用 Formatter 枚举解析时间字符串并生成 DateTime 实例。
|
||
*
|
||
* @param timestr 时间字符串
|
||
* @param formatter 格式化模板枚举
|
||
* @param fillZero 是否补零到模板长度
|
||
* @return 返回解析后的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun parse(
|
||
timestr: String, formatter: Formatter, fillZero: Boolean,
|
||
): DateTime {
|
||
return parse(timestr, formatter.value, fillZero)
|
||
}
|
||
|
||
/**
|
||
* 使用 Formatter 枚举解析时间字符串并生成 DateTime 实例,默认不补零。
|
||
*
|
||
* @param timestr 时间字符串
|
||
* @param formatter 格式化模板枚举
|
||
* @return 返回解析后的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun parse(timestr: String, formatter: Formatter): DateTime {
|
||
return parse(timestr, formatter.value)
|
||
}
|
||
|
||
/**
|
||
* 解析时间字符串并生成 DateTime 实例,默认不补零。
|
||
*
|
||
* @param timestr 时间字符串
|
||
* @param formatter 格式化模板
|
||
* @return 返回解析后的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun parse(timestr: String, formatter: String): DateTime {
|
||
return parse(timestr, formatter, false)
|
||
}
|
||
|
||
/**
|
||
* 补零处理时间字符串以匹配格式化模板长度。
|
||
*
|
||
* @param dstr 原始时间字符串
|
||
* @param formats 格式化模板
|
||
* @return 补零后的时间字符串
|
||
*/
|
||
private fun getFillZeroByLen(dstr: String, formats: String): String {
|
||
val formatslen = formats.replace("'", "").length
|
||
if (dstr.length == formatslen) {
|
||
return dstr
|
||
}
|
||
if (formatslen > dstr.length) {
|
||
var modifiedDstr = dstr
|
||
if (dstr.length == 19) {
|
||
modifiedDstr += "."
|
||
}
|
||
val sb = StringBuilder(modifiedDstr)
|
||
for (i in 0 until formatslen - sb.length) {
|
||
sb.append("0")
|
||
}
|
||
return sb.toString()
|
||
}
|
||
throw IllegalArgumentException(
|
||
String.format(
|
||
"Text: '%s' len %s < %s %s", dstr, dstr.length, formats, formatslen
|
||
)
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 根据年、月、日创建 DateTime 实例
|
||
*
|
||
* @param year 年份
|
||
* @param month 月份 (1-12)
|
||
* @param day 日期 (1-31)
|
||
* @return 返回指定日期的 DateTime 实例(时间部分为 00:00:00)
|
||
*/
|
||
@JvmStatic
|
||
fun of(year: Int, month: Int, day: Int): DateTime {
|
||
return DateTime(LocalDateTime.of(year, month, day, 0, 0))
|
||
}
|
||
|
||
/**
|
||
* 根据年、月、日、时、分创建 DateTime 实例
|
||
*
|
||
* @param year 年份
|
||
* @param month 月份 (1-12)
|
||
* @param day 日期 (1-31)
|
||
* @param hour 小时 (0-23)
|
||
* @param minute 分钟 (0-59)
|
||
* @return 返回指定日期时间的 DateTime 实例(秒部分为 00)
|
||
*/
|
||
@JvmStatic
|
||
fun of(
|
||
year: Int, month: Int, day: Int, hour: Int, minute: Int,
|
||
): DateTime {
|
||
return DateTime(LocalDateTime.of(year, month, day, hour, minute))
|
||
}
|
||
|
||
/**
|
||
* 根据年、月、日、时、分、秒创建 DateTime 实例
|
||
*
|
||
* @param year 年份
|
||
* @param month 月份 (1-12)
|
||
* @param day 日期 (1-31)
|
||
* @param hour 小时 (0-23)
|
||
* @param minute 分钟 (0-59)
|
||
* @param second 秒 (0-59)
|
||
* @return 返回指定日期时间的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(
|
||
year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int,
|
||
): DateTime {
|
||
return DateTime(
|
||
LocalDateTime.of(year, month, day, hour, minute, second)
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 根据年、月、日、时、分、秒、纳秒创建 DateTime 实例
|
||
*
|
||
* @param year 年份
|
||
* @param month 月份 (1-12)
|
||
* @param day 日期 (1-31)
|
||
* @param hour 小时 (0-23)
|
||
* @param minute 分钟 (0-59)
|
||
* @param second 秒 (0-59)
|
||
* @param nano 纳秒 (0-999,999,999)
|
||
* @return 返回指定日期时间的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(
|
||
year: Int, month: Int, day: Int, hour: Int, minute: Int, second: Int, nano: Int,
|
||
): DateTime {
|
||
return DateTime(
|
||
LocalDateTime.of(year, month, day, hour, minute, second, nano)
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 根据毫秒时间戳创建 DateTime 实例
|
||
*
|
||
* @param epochMilli 毫秒时间戳
|
||
* @return 返回对应时间的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(epochMilli: Long): DateTime {
|
||
return DateTime(
|
||
java.time.Instant.ofEpochMilli(epochMilli).atZone(ZoneId.systemDefault()).toLocalDateTime()
|
||
)
|
||
}
|
||
|
||
@JvmStatic
|
||
fun of(seconds: Long, nanos: Long): DateTime {
|
||
return DateTime(
|
||
java.time.Instant.ofEpochSecond(seconds, nanos).atZone(ZoneId.systemDefault()).toLocalDateTime()
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 根据毫秒时间戳和时区创建 DateTime 实例
|
||
*
|
||
* @param epochMilli 毫秒时间戳
|
||
* @param zoneId 时区信息
|
||
* @return 返回对应时间的 DateTime 实例
|
||
*/
|
||
@JvmStatic
|
||
fun of(epochMilli: Long, zoneId: ZoneId): DateTime {
|
||
return DateTime(
|
||
java.time.Instant.ofEpochMilli(epochMilli).atZone(zoneId).toLocalDateTime(), zoneId
|
||
)
|
||
}
|
||
|
||
fun LocalDateTime.toDateTime(): DateTime = of(this)
|
||
fun Date.toDateTime(): DateTime = of(this)
|
||
}
|
||
|
||
/**
|
||
* 将当前 DateTime 转换为 Date 对象。
|
||
*
|
||
* @return 返回对应的 Date 对象
|
||
*/
|
||
fun toDate(): Date {
|
||
return Date.from(localDateTime.atZone(zoneId).toInstant())
|
||
}
|
||
|
||
/**
|
||
* 获取当前 DateTime 中的 LocalDateTime 实例。
|
||
*
|
||
* @return 返回 LocalDateTime 对象
|
||
*/
|
||
fun toLocalDateTime(): LocalDateTime {
|
||
return localDateTime
|
||
}
|
||
|
||
/**
|
||
* 在当前时间基础上增加指定的时间偏移量。
|
||
*
|
||
* @param dateTimeOffset 时间偏移对象
|
||
* @return 返回修改后的 DateTime 实例
|
||
*/
|
||
fun add(dateTimeOffset: DateTimeOffset): DateTime {
|
||
return DateTime(
|
||
this.localDateTime.plus(
|
||
dateTimeOffset.offset, dateTimeOffset.offsetType
|
||
)
|
||
)
|
||
}
|
||
|
||
/**
|
||
* 重载加法运算符,将指定的DateTimeOffset添加到当前DateTime对象
|
||
* @param dateTimeOffset 要添加的时间偏移量
|
||
* @return 返回相加后的新DateTime对象
|
||
*/
|
||
operator fun plus(dateTimeOffset: DateTimeOffset): DateTime = add(dateTimeOffset)
|
||
|
||
/**
|
||
* 重载减法运算符,从当前DateTime对象中减去指定的DateTimeOffset
|
||
* @param dateTimeOffset 要减去的时间偏移量
|
||
* @return 返回相减后的新DateTime对象
|
||
*/
|
||
operator fun minus(dateTimeOffset: DateTimeOffset): DateTime = sub(dateTimeOffset)
|
||
|
||
/**
|
||
* 在当前时间基础上减少指定的时间偏移量。
|
||
*
|
||
* @param dateTimeOffset 时间偏移对象
|
||
* @return 返回修改后的 DateTime 实例
|
||
*/
|
||
fun sub(dateTimeOffset: DateTimeOffset): DateTime {
|
||
return add(DateTimeOffset.of(-dateTimeOffset.offset, dateTimeOffset.offsetType))
|
||
}
|
||
|
||
/**
|
||
* 使用指定格式化模板将当前时间格式化为字符串。
|
||
*
|
||
* @param formatter 格式化模板
|
||
* @return 返回格式化后的时间字符串
|
||
*/
|
||
fun format(formatter: String): String {
|
||
return format(formatter, false)
|
||
}
|
||
|
||
/**
|
||
* 使用 Formatter 枚举将当前时间格式化为字符串。
|
||
*
|
||
* @param formatter 格式化模板枚举
|
||
* @return 返回格式化后的时间字符串
|
||
*/
|
||
fun format(formatter: Formatter): String {
|
||
return format(formatter.value)
|
||
}
|
||
|
||
fun format(): String {
|
||
return format(Formatter.STANDARD_DATETIME_MILLISECOUND9.value, true)
|
||
}
|
||
|
||
/**
|
||
* 使用指定格式化模板将当前时间格式化为字符串,并可选择是否去除末尾多余的零。
|
||
*
|
||
* @param formatter 格式化模板
|
||
* @param repcZero 是否去除末尾多余的零
|
||
* @return 返回格式化后的时间字符串
|
||
*/
|
||
fun format(formatter: String, repcZero: Boolean): String {
|
||
var formatted = DateTimeFormatter.ofPattern(formatter).format(
|
||
toLocalDateTime()
|
||
)
|
||
if (repcZero) {
|
||
// 处理小数点后多余的0
|
||
formatted = formatted.replace(Regex("(\\.\\d*?)0+\\b"), "$1")
|
||
formatted = formatted.replace(Regex("\\.$"), "")
|
||
}
|
||
return formatted
|
||
}
|
||
|
||
/**
|
||
* 使用 Formatter 枚举将当前时间格式化为字符串,并可选择是否去除末尾多余的零。
|
||
*
|
||
* @param formatter 格式化模板枚举
|
||
* @param repcZero 是否去除末尾多余的零
|
||
* @return 返回格式化后的时间字符串
|
||
*/
|
||
fun format(formatter: Formatter, repcZero: Boolean): String {
|
||
return format(formatter.value, repcZero)
|
||
}
|
||
|
||
/**
|
||
* 返回当前时间的标准字符串表示形式。
|
||
*
|
||
* @return 返回标准格式的时间字符串
|
||
*/
|
||
override fun toString(): String {
|
||
return "DateTime(${format()})"
|
||
}
|
||
|
||
/**
|
||
* 比较当前DateTime对象与指定对象是否相等
|
||
*
|
||
* @param other 要比较的对象
|
||
* @return 如果对象相等则返回true,否则返回false
|
||
*/
|
||
override fun equals(other: Any?): Boolean {
|
||
// 检查对象类型是否为DateTime
|
||
if (other is DateTime) {
|
||
// 比较两个DateTime对象转换为LocalDateTime后的值
|
||
return toLocalDateTime() == other.toLocalDateTime()
|
||
}
|
||
return false
|
||
}
|
||
|
||
/**
|
||
* 获取对象的哈希码
|
||
*
|
||
* @return 哈希码
|
||
*/
|
||
override fun hashCode(): Int {
|
||
return localDateTime.hashCode()
|
||
}
|
||
|
||
/**
|
||
* 将当前 DateTime 转换为 Instant 对象。
|
||
*
|
||
* @return 返回 Instant 对象
|
||
*/
|
||
fun toInstant(): java.time.Instant {
|
||
return localDateTime.atZone(zoneId).toInstant()
|
||
}
|
||
|
||
/**
|
||
* 判断当前时间是否在指定时间之后。
|
||
*
|
||
* @param dateTime 指定时间
|
||
* @return 如果当前时间在指定时间之后则返回 true,否则返回 false
|
||
*/
|
||
fun isAfter(dateTime: DateTime?): Boolean {
|
||
if (dateTime == null) {
|
||
return false
|
||
}
|
||
return toInstant().isAfter(dateTime.toInstant())
|
||
}
|
||
|
||
/**
|
||
* 判断当前时间是否在指定时间之前。
|
||
*
|
||
* @param dateTime 指定时间
|
||
* @return 如果当前时间在指定时间之前则返回 true,否则返回 false
|
||
*/
|
||
fun isBefore(dateTime: DateTime?): Boolean {
|
||
if (dateTime == null) {
|
||
return false
|
||
}
|
||
return toInstant().isBefore(dateTime.toInstant())
|
||
}
|
||
|
||
/**
|
||
* 获取时区ID
|
||
*
|
||
* @return ZoneId对象
|
||
*/
|
||
fun getZoneId(): ZoneId {
|
||
return zoneId
|
||
}
|
||
|
||
|
||
/**
|
||
* 将 Instant 转换为纳秒时间戳
|
||
* @throws ArithmeticException 如果结果超出 Long 范围 (-2^63 到 2^63-1)
|
||
*/
|
||
fun toNanoTime(): Long {
|
||
val instant = toInstant()
|
||
return try {
|
||
val secondsInNanos = Math.multiplyExact(instant.epochSecond, 1_000_000_000L)
|
||
Math.addExact(secondsInNanos, instant.nano.toLong())
|
||
} catch (e: ArithmeticException) {
|
||
throw ArithmeticException(
|
||
"无法将 Instant(${instant.epochSecond}s, ${instant.nano}ns) 转换为纳秒: ${e.message}"
|
||
)
|
||
}
|
||
}
|
||
|
||
fun to100NanoTime(): Long {
|
||
return toInstant().let {
|
||
(it.epochSecond * 10_000_000L) + (it.nano / 100L)
|
||
}
|
||
}
|
||
|
||
fun toMillisecondTime(): Long {
|
||
return toInstant().let {
|
||
(it.epochSecond * 1000L) + (it.nano / 1_000_000L)
|
||
}
|
||
}
|
||
}
|