/* * 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 等类型的互转。 *
* 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) } } }