aeon

package module

v0.0.0-...-6d44cd7 Latest Latest Go to latest Published: Jan 27, 2026 License: MIT Imports: 6 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/baagod/aeon

Links

Open Source Insights

README ¶

你或许觉得我疯了，没关系，我也这么认为。

记不清是从哪一刻开始了，也许是源于对 time.Time 和现有时间库的不满与愤怒 —— 我产生了一个近乎荒诞的执念：我自己写一个 Go 时间库？

这一切始于那个简陋、甚至可以说是有些 “丑陋” 的前身 thru，我决定对其系统化更新与重构。无数个灵感与想象如烟火般炸裂，才最终让它完成了跨越维度的蜕变。

我将其正式命名为：Aeon。在古老的哲学中，Aeon 代表着 “永恒” 与 “层叠的维度”。

我选择这个名字，是因为它代表了时间更本质的逻辑 —— 时间不是一条细长的直线，它是流动的、是可以被嵌套和穿透的宇宙。

Aeon

Aeon 是一个基于 时间容器 索引的 Go 时间导航库，用结构化导航替代线性计算，以更贴近人类时间直觉的方式表达复杂时间意图。

📦 安装

go get github.com/baagod/aeon

🧊 核心概念：容器

Aeon 的核心是基于容器偏移。所有导航，本质上都是在 当前单位的父容器 中进行索引 (从 0 开始)。例如：

GoYear(5): 不是去公元 5 年，而是在 本年代 这个 父容器 中，索引到第 5 年 ➜ ···5。
GoDecade(2): 索引到 本世纪 第 2 个年代 ➜ ··2·。
GoCentury(0): 索引到 本千年 第 0 个世纪 ➜ ·0··。

[千年 Millennium]
  └─ [0...9 世纪 Century]
       └─ [0...9 年代 Decade]
            └─ [0...9 年份 Year]
                 └─ [1...12 月份 Month]

示例：GoYear(5) 寻址逻辑
         [-9]       [-8]            [-5]        [-4]             [-1]
2020 ─┬─ 2021 ──┬── 2022 ··· ──┬── [2025] ──┬── 2026 ─┬─ ··· ─┬─ 2029
[0]      [1]        [2]             [5]         [6]              [9]

🧭 导航矩阵

Aeon 的 API 设计是完全正交的，你只需要记住 4 个动作：

Go.. [·] 全绝定位： GoYear(5, 1) ➜ 本年代第 5 年 1 月
By.. [➜] 全相偏移： ByYear(1, 5) ➜ 偏移 1 年 5 天
At.. [·, ➜] 先定后移： AtYear(5, 1) ➜ 定位到本年代的第 5 年再偏移 1 个月
In.. [➜, ·] 先移后定： InYear(1, 5) ➜ 明年 5 月

[!IMPORTANT]

By 系列方法默认值为 1，其余为 0。

无效单位 (如 0 月) 在定位模式（而非偏移）下保持不变。

之后，配合 Start/End 前缀可定位到时间边界：

StartYear(): 本年 开始时间 (01-01 00:00:00...)
EndYear(): 本年 结束时间 (12-31 23:59:59...)

配合 6 个顶级方法进入 绝对年份：

Go(2025, 2) ➜ 2025-02
At(2025, 2) ➜ 定位到 2025 年后再偏移 2 个月
Start(2025, 2) ➜ 2025-02-01 00:00:00
StartAt(2025, 1) ➜ 定位到 2025 年后再偏移 1 个月的月初
End(2025, 2) ➜ 2025-02-28 23:59:59...
EndAt(2025, 1) ➜ 定位到 2025 年后再偏移 1 个月的月末

♾️ 级联参数

链式调用？不，是原子操作！所有方法均支持 变长参数 向下级联，参数像水流，一行代码即可完成复杂定位。

Aeon 会根据 入口单位 自动切换 4 种不同的级联序列：

年序列 Default：世纪 ➜ 年代 ➜ 年 ➜ 月 ➜ 日 ➜ 时.. ➜ 纳秒
季度流 Quarter：季度 ➜ 月 (季内) ➜ 日 ➜ 时.. ➜ 纳秒
周序列 Week🦬：周 (智能上下文) ➜ 星期 ➜ 时.. ➜ 纳秒

这是 变形金刚！它根据传入的 标志位 自动切换形态：
- ISO: 遵循 ISO 年周规则，获取本年第 n 个 ISO 年周。
- Full: 完整周。从本月第 1 个周一开始。
- Ord: 序数周。从本月 1 日开始的 7 天周。
- Default: 日历周。遵循日历行视觉的周。
星期流 Weekday：星期 ➜ 时.. ➜ 纳秒

// 相对偏移 1 年 3 月 5 日
ByYear(1, 3, 5)

// 2025 年 2 月最后一天 23 点整
Go(2025).StartMonth(2, -1, 23)

// 本年第 3 个季度最后一个月，最后 2 天结束时间
EndQuarter(3, -1, -2)

// 2025 年第 10 个 ISO 周一
Go(2025).StartWeek(aeon.ISO, 10, 1)

// 本月从 1 日开始的第 3 个 “七天周” 周五（本月第 3 个星期五）
StartWeek(aeon.Ord, 3, 5)

// 本月最后一个周五
GoWeek(aeon.Ord, -1, 5)

// 上个季度结束时间
EndByQuarter(-1)

// 本季度最后一个月 1 号
StartQuarter(0, -1, 1)

// 本周五 18 点 (下班时间)
StartWeekday(5, 18)

// 本月倒数第 3 天
StartDay(-3)

// 下周三下午 2 点
StartInWeek(1, 3, 14)

// 年度归档：年初/年末边界
StartYear() / EndYear()

// 下个月最后一天
EndInMonth(1, -1)

负数不仅仅是减法，它是 反向索引，代表在 “容器内倒数第 N 个”。

🛡️ 溢出保护

Aeon 的核心哲学是 意图优先，默认导航会保护 “月及以上单位” 溢出天数。

base := NewDate(2025, 1, 31)
base.GoMonth(2) // 2025-02-28 (保护)
base.ByMonth(Overflow, 1) // 2025-03-03 (溢出)
base.ByMonth(1, 2) // 🛡️🦬 2025-03-02 (保护到 2-28 再加2天)

// 跨年：从闰年到平年
leap := NewDate(2024, 2, 29)
leap.ByYear(1) // 2025-02-28 (保护)
leap.ByYear(Overflow, 1) // 2025-03-01 (溢出：跨月)
leap.ByYear(4)           // 2028-02-29 (下一个闰年)

🚀 性能基准 (Benchmarks)

Aeon 在实现强大功能的同时，通过 零内存分配 (Zero Alloc) 达到了极高性能。

测试环境：windows / Intel i7-8700K

创建时间

New    | ns/op | B/op | allocs/op | up
Aeon   | █ 17.38 | 0 | 0 | x80
Carbon | ██████████████████████████████████████ 1388.00 | 1600 | 13

Now    | ns/op | B/op | allocs/op | up
Aeon   | █ 10.02 | 0 | 0 | x136
Carbon | ██████████████████████████████████████ 1367.00 | 1600 | 13

Unix   | ns/op | B/op | allocs/op | up
Aeon   | █ 5.57 | 0 | 0 | x243
Carbon | ██████████████████████████████████████ 1356.00 | 1600 | 13

————————————————————————————————————————————————————————————————————

标准互转

ToStd  | ns/op | B/op | allocs/op | up
Aeon   | █ 10.01 | 0 | 0 | x143
Carbon | ██████████████████████████████████████ 1430.00 | 1600 | 13

From   | ns/op | B/op | allocs/op | up
Aeon   | █ 4.89 | 0 | 0 | x285
Carbon | ██████████████████████████████████████ 1396.00 | 1600 | 13

————————————————————————————————————————————————————————————————————

解析时间

"2020-08-05 13:14:15"           | ns/op | B/op | allocs/op | up
Aeon                            | █ 234.0 | 24 | 1 | x7
Carbon                          | ██████████████████████████████████████ 1617.00 | 1600 | 13

"2020-08-05"                    | ns/op | B/op | allocs/op | up
Aeon                            | █ 120.4 | 0 | 0 | x14
Carbon                          | ██████████████████████████████████████ 1738.00 | 1697 | 15

"13:14:15"                      | ns/op | B/op | allocs/op | up
Aeon                            | █ 359.0 | 192 | 6 | x5
Carbon                          | ██████████████████████████████████████ 1821.00 | 1793 | 19

"2020-08-05T13:14:15+08:00"     | ns/op | B/op | allocs/op | up
Aeon                            | █ 583.2 | 184 | 6 | x4
Carbon                          | ██████████████████████████████████████ 2408.00 | 2321 | 30

"20200805131415"                | ns/op | B/op | allocs/op | up
Aeon                            | █ 151.9 | 0 | 0 | x29
Carbon                          | ██████████████████████████████████████ 4475.00 | 4202 | 83

"2020-08-05 13:14:15.123"       | ns/op | B/op | allocs/op | up
Aeon                            | █ 276.4 | 24 | 1 | x6
Carbon                          | ██████████████████████████████████████ 1631.00 | 1600 | 13

"2020/08/05 13:14:15"           | ns/op | B/op | allocs/op | up
Aeon                            | █ 301.3 | 48 | 2 | x39
Carbon                          | ██████████████████████████████████████ 11885.00 | 10726 | 243

"2020.08.05 13:14:15"           | ns/op | B/op | allocs/op | up
Aeon                            | █ 298.8 | 40 | 2 | x38
Carbon                          | ██████████████████████████████████████ 11409.00 | 10006 | 225

"2020-08-05T13:14:15"           | ns/op | B/op | allocs/op | up
Aeon                            | █ 233.7 | 24 | 1 | x13
Carbon                          | ██████████████████████████████████████ 3131.00 | 2577 | 36

"Mon, 04 Aug 2020 13:14:15 GMT" | ns/op | B/op | allocs/op | up
Aeon                            | █ 1021.0 | 915 | 20 | x3
Carbon                          | ██████████████████████████████████████ 3722.00 | 3754 | 59

Documentation ¶

Index ¶

Constants
Variables
func DaysIn(y int, m ...int) int
func IsLeapYear(y int) bool
func IsLongYear(y int) bool
func NewZone(name string, offset ...int) (loc *time.Location)
func RegisterDNA(layout string)
func Since(t Time) time.Duration
func Until(t Time) time.Duration
type DateTimeMilli
type F
type Flag
type Formatter
type Time
type Unit

Constants ¶

View Source

const (
	ISO  = flagSign | (1 << 0) // ISO 周标志
	Ord  = flagSign | (1 << 1) // Ord 周标志
	Full = flagSign | (1 << 2) // Full 周标志

	// Overflow 允许月份溢出标志
	Overflow = flagSign | (1 << 3)
	// ABS 绝对时间标志 (内部使用)
	ABS = flagSign | (1 << 4)
)

View Source

const (
	Local = "Local" // 本地时间
	UTC   = "UTC"   // 协调世界时间

	CET = "CET" // 中欧标准时间
	EET = "EET" // 东欧标准时间
	EST = "EST" // 东部标准时间
	GMT = "GMT" // 格林尼治标准时间
	MET = "MET" // 中欧时间
	MST = "MST" // 山地标准时间
	WET = "WET" // 西欧标准时间

	Cuba      = "Cuba"      // 古巴
	Egypt     = "Egypt"     // 埃及
	Eire      = "Eire"      // 爱尔兰
	Greenwich = "Greenwich" // 格林尼治
	Iceland   = "Iceland"   // 冰岛
	Iran      = "Iran"      // 伊朗
	Israel    = "Israel"    // 以色列
	Jamaica   = "Jamaica"   // 牙买加
	Japan     = "Japan"     // 日本
	Libya     = "Libya"     // 利比亚
	Poland    = "Poland"    // 波兰
	Portugal  = "Portugal"  // 葡萄牙
	PRC       = "PRC"       // 中国
	Singapore = "Singapore" // 新加坡
	Turkey    = "Turkey"    // 土耳其

	Shanghai   = "Asia/Shanghai"       // 上海
	Chongqing  = "Asia/Chongqing"      // 重庆
	Harbin     = "Asia/Harbin"         // 哈尔滨
	Urumqi     = "Asia/Urumqi"         // 乌鲁木齐
	HongKong   = "Asia/Hong_Kong"      // 香港
	Macao      = "Asia/Macao"          // 澳门
	Taipei     = "Asia/Taipei"         // 台北
	Tokyo      = "Asia/Tokyo"          // 东京
	HoChiMinh  = "Asia/Ho_Chi_Minh"    // 胡志明市
	Hanoi      = "Asia/Hanoi"          // 河内
	Saigon     = "Asia/Saigon"         // 西贡 (胡志明市)
	Seoul      = "Asia/Seoul"          // 首尔
	Pyongyang  = "Asia/Pyongyang"      // 平壤
	Bangkok    = "Asia/Bangkok"        // 曼谷
	Dubai      = "Asia/Dubai"          // 迪拜
	Qatar      = "Asia/Qatar"          // 卡塔尔
	Bangalore  = "Asia/Bangalore"      // 班加罗尔
	Kolkata    = "Asia/Kolkata"        // 加尔各答
	Mumbai     = "Asia/Mumbai"         // 孟买
	MexicoCity = "America/Mexico_City" // 墨西哥城
	NewYork    = "America/New_York"    // 纽约
	NewYork1   = "America/New_York"    // 纽约
	LosAngeles = "America/Los_Angeles" // 洛杉矶
	Chicago    = "America/Chicago"     // 芝加哥
	SaoPaulo   = "America/Sao_Paulo"   // 圣保罗
	Moscow     = "Europe/Moscow"       // 莫斯科
	London     = "Europe/London"       // 伦敦
	Berlin     = "Europe/Berlin"       // 柏林
	Paris      = "Europe/Paris"        // 巴黎
	Rome       = "Europe/Rome"         // 罗马
	Sydney     = "Australia/Sydney"    // 悉尼
	Melbourne  = "Australia/Melbourne" // 墨尔本
	Darwin     = "Australia/Darwin"    // 达尔文
)

时区名称常量定义 (IANA 标准)

View Source

const (
	ANSIC      = "Mon Jan _2 15:04:05 2006"
	UnixD      = "Mon Jan _2 15:04:05 MST 2006"
	RubyD      = "Mon Jan 02 15:04:05 -0700 2006"
	RFC822     = "02 Jan 06 15:04 MST"
	RFC822Z    = "02 Jan 06 15:04 -0700"
	RFC850     = "Monday, 02-Jan-06 15:04:05 MST"
	RFC1123    = "Mon, 02 Jan 2006 15:04:05 MST"
	RFC1123Z   = "Mon, 02 Jan 2006 15:04:05 -0700"
	RFC3339    = "2006-01-02T15:04:05Z07:00"
	RFC3339Ns  = "2006-01-02T15:04:05.999999999Z07:00"
	Kitchen    = "3:04PM"
	Stamp      = "Jan _2 15:04:05"
	StampMilli = "Jan _2 15:04:05.000"
	StampMicro = "Jan _2 15:04:05.000000"
	StampNano  = "Jan _2 15:04:05.000000000"
	StampNs    = "Jan _2 15:04:05.999999999"

	// 核心布局 (DT/D 系列)
	DT       = "2006-01-02 15:04:05"
	DTMilli  = "2006-01-02 15:04:05.000"
	DTMicro  = "2006-01-02 15:04:05.000000"
	DTNano   = "2006-01-02 15:04:05.000000000"
	DTNs     = "2006-01-02 15:04:05.999999999"
	DateOnly = "2006-01-02"
	DMilli   = "2006-01-02.000"
	DMicro   = "2006-01-02.000000"
	DNano    = "2006-01-02.000000000"
	TimeOnly = "15:04:05"

	// 补强布局 (归一化复用版)
	DTFull         = "2006-01-02 15:04:05.999999999 -0700 MST"
	DTTZ           = "2006-01-02 15:04:05-07:00"
	DTTZShort      = "2006-01-02 15:04:05-07"
	DTISO          = "2006-01-02T15:04:05-07:00"
	DTPMMST        = "2006-01-02 15:04:05 PM MST"
	DTPMShortMST   = "2006-01-02 15:04:05PM MST"
	RFC3339Space   = "2006-01-02 15:04:05Z07:00"
	RFC3339NsSpace = "2006-01-02 15:04:05.999999999Z07:00"

	// 紧凑与特殊格式
	DTCompact     = "20060102150405"
	DCompact      = "20060102"
	TimeCompact   = "150405"
	DTVeryShort   = "2006-1-2 15:4:5"
	DTShort       = "2006-1-2 15:4"
	DOnlyShort    = "2006-1-2"
	TimeVeryShort = "15:4:5"
	TimeShort     = "15:4"
	MonthD        = "1-2"
	YearOnly      = "2006"

	// 从 Carbon 补强的高价值布局
	DTCompactTZ     = "20060102150405-07:00"
	DTCompactZ      = "20060102150405Z07:00"
	DTCompactMilli  = "20060102150405.000"
	DHourShort      = "2006-1-2 15"
	HourOnly        = "15"
	DMonth          = "2006-1"
	FormattedD      = "Jan 2, 2006"
	FormattedDayD   = "Mon, Jan 2, 2006"
	DayDateTime     = "Mon, Jan 2, 2006 3:04 PM"
	Cookie          = "Monday, 02-Jan-2006 15:04:05 MST"
	Http            = "Mon, 02 Jan 2006 15:04:05 GMT"
	RFC1036         = "Mon, 02 Jan 06 15:04:05 -0700"
	RFC7231         = "Mon, 02 Jan 2006 15:04:05 MST"
	TimeTZShort     = "15:04:05-07"
	DTFullVeryShort = "2006-1-2 15:4:5 -0700 MST"
	DTNsVeryShort   = "2006-1-2 15:4:5.999999999"

	// ISO8601 家族
	ISO8601       = "2006-01-02T15:04:05-07:00"
	ISO8601Ns     = "2006-01-02T15:04:05.999999999-07:00"
	ISO8601Zulu   = "2006-01-02T15:04:05Z"
	ISO8601ZuluNs = "2006-01-02T15:04:05.999999999Z"
)

Variables ¶

View Source

var (
	// DefaultWeekStarts 全局默认周起始日（默认为周一）
	DefaultWeekStarts = time.Monday
	// DefaultTimeZone Parse() 使用的默认时区
	DefaultTimeZone = time.Local
)

Functions ¶

func DaysIn ¶

func DaysIn(y int, m ...int) int

DaysIn 返回 y 年 m 月最大天数，如果忽略 m 则返回 y 年总天数。

1, 3, 5, 7, 8, 10, 12 月有 31 天；4, 6, 9, 11 月有 30 天。
平年 2 月有 28 天，闰年 29 天。

func IsLeapYear ¶

func IsLeapYear(y int) bool

IsLeapYear 返回 y 是否闰年

func IsLongYear ¶

func IsLongYear(y int) bool

IsLongYear 返回当前年份是否为 ISO 8601 规定的 “长年”（包含 53 周）。

func NewZone ¶

func NewZone(name string, offset ...int) (loc *time.Location)

NewZone 返回指定的时区。

参数：

name: 时区名称（如 aeon.Shanghai 或 "Asia/Shanghai"）
shift (可选): 整数偏移小时。若提供，则创建一个以此偏移量为准的固定时区。

示例：

aeon.NewZone(aeon.Shanghai)      // 返回上海时区对象
aeon.NewZone("CST", 8)           // 返回东八区固定时区对象

func RegisterDNA ¶

func RegisterDNA(layout string)

RegisterDNA 将布局字符串注册到 DNA 地图中

func Since ¶

func Since(t Time) time.Duration

Since 返回 t 到现在经过的持续时间

func Until ¶

func Until(t Time) time.Duration

Until 返回现在到 t 经过的持续时间

Types ¶

type DateTimeMilli ¶

type DateTimeMilli = F[formatDateTimeMilli]

type F ¶

type F[T Formatter] struct {
	Time
	// contains filtered or unexported fields
}

func (F[T]) MarshalJSON ¶

func (f F[T]) MarshalJSON() ([]byte, error)

func (F[T]) MarshalText ¶

func (f F[T]) MarshalText() ([]byte, error)

func (*F[T]) Scan ¶

func (f *F[T]) Scan(value any) (err error)

func (*F[T]) UnmarshalJSON ¶

func (f *F[T]) UnmarshalJSON(b []byte) (err error)

func (*F[T]) UnmarshalText ¶

func (f *F[T]) UnmarshalText(data []byte) error

func (F[T]) Value ¶

func (f F[T]) Value() (driver.Value, error)

type Flag ¶

type Flag struct {
	// contains filtered or unexported fields
}

Flag 承载级联操作的上下文配置

type Formatter ¶

type Formatter interface {
	Layout() string
}

type Time ¶

type Time struct {
	// contains filtered or unexported fields
}

func Aeon ¶

func Aeon(t ...time.Time) Time

func Maxmin ¶

func Maxmin(op string, times ...Time) Time

Maxmin 返回一组时间中的极值

参数 op：

">" : 最大值（最晚）
"<" : 最小值（最早）

func Near ¶

func Near(op string, base Time, times ...Time) Time

Near 在集合 times 中寻找距离 base 最近或最远的时间点。

参数 op：

"<" : 最近 (Closest)
">" : 最远 (Farthest)

func New ¶

func New(y, m, d, h, mm, s int, add ...any) Time

func Now ¶

func Now(loc ...*time.Location) Time

func Parse ¶

func Parse(value string, loc ...*time.Location) Time

Parse 解析时间字符串，忽略错误

func ParseBy ¶

func ParseBy(layout string, value string, loc ...*time.Location) Time

ParseBy 指定布局解析，忽略错误

func ParseByE ¶

func ParseByE(layout string, value string, loc ...*time.Location) (Time, error)

ParseByE 指定布局解析，返回 Time 和 error

func ParseE ¶

func ParseE(s string, loc ...*time.Location) (Time, error)

ParseE 解析时间字符串，返回 Time 和 error

func Unix ¶

func Unix(secs int64, loc ...*time.Location) Time

Unix 返回给定时间戳的时间。secs 可以是秒、毫秒、微妙或纳秒级时间戳。

func (Time) AppendFormat ¶

func (t Time) AppendFormat(b []byte, layout string) []byte

func (Time) At ¶

func (t Time) At(n ...int) Time

func (Time) AtCentury ¶

func (t Time) AtCentury(n ...int) Time

func (Time) AtDay ¶

func (t Time) AtDay(n ...int) Time

func (Time) AtDecade ¶

func (t Time) AtDecade(n ...int) Time

func (Time) AtHour ¶

func (t Time) AtHour(n ...int) Time

func (Time) AtMicro ¶

func (t Time) AtMicro(n ...int) Time

func (Time) AtMilli ¶

func (t Time) AtMilli(n ...int) Time

func (Time) AtMinute ¶

func (t Time) AtMinute(n ...int) Time

func (Time) AtMonth ¶

func (t Time) AtMonth(n ...int) Time

func (Time) AtNano ¶

func (t Time) AtNano(n ...int) Time

func (Time) AtQuarter ¶

func (t Time) AtQuarter(n ...int) Time

func (Time) AtSecond ¶

func (t Time) AtSecond(n ...int) Time

func (Time) AtWeek ¶

func (t Time) AtWeek(n ...int) Time

func (Time) AtWeekday ¶

func (t Time) AtWeekday(n ...int) Time

func (Time) AtYear ¶

func (t Time) AtYear(n ...int) Time

func (Time) Between ¶

func (t Time) Between(start, end Time, bounds ...string) bool

Between 判断 t 是否在 (start, end) 区间内。

可选参数 bounds 用于控制边界包含性（默认为 "="）：

"=" : 包含边界
"!" : 不包含边界
"[" : 包含左边界
"]" : 包含右边界

func (Time) By ¶

func (t Time) By(d time.Duration) Time

func (Time) ByCentury ¶

func (t Time) ByCentury(n ...int) Time

func (Time) ByDay ¶

func (t Time) ByDay(n ...int) Time

func (Time) ByDecade ¶

func (t Time) ByDecade(n ...int) Time

func (Time) ByHour ¶

func (t Time) ByHour(n ...int) Time

func (Time) ByMicro ¶

func (t Time) ByMicro(n ...int) Time

func (Time) ByMilli ¶

func (t Time) ByMilli(n ...int) Time

func (Time) ByMinute ¶

func (t Time) ByMinute(n ...int) Time

func (Time) ByMonth ¶

func (t Time) ByMonth(n ...int) Time

func (Time) ByNano ¶

func (t Time) ByNano(n ...int) Time

func (Time) ByQuarter ¶

func (t Time) ByQuarter(n ...int) Time

func (Time) BySecond ¶

func (t Time) BySecond(n ...int) Time

func (Time) ByWeek ¶

func (t Time) ByWeek(n ...int) Time

func (Time) ByYear ¶

func (t Time) ByYear(n ...int) Time

func (Time) Clock ¶

func (t Time) Clock() (h, mm, s int)

func (Time) Compare ¶

func (t Time) Compare(u Time) int

Compare 比较 t 和 u。

如果 t == u，返回 0；t > u 返回 1；t < u 返回 -1。

func (Time) Date ¶

func (t Time) Date() (int, int, int)

Date 返回 t 的年月日

func (Time) Day ¶

func (t Time) Day() int

func (Time) Days ¶

func (t Time) Days() int

func (Time) Diff ¶

func (t Time) Diff(u Time, unit string, abs ...bool) float64

Diff 返回 t 和 u 的时间差。

参数：

unit: 比较单位 ("y"年, "M"月, "d"日, "h"时, "m"分, "s"秒)
abs: 可选，为 true 时返回绝对值

func (Time) End ¶

func (t Time) End(n ...int) Time

func (Time) EndAt ¶

func (t Time) EndAt(n ...int) Time

func (Time) EndAtCentury ¶

func (t Time) EndAtCentury(n ...int) Time

func (Time) EndAtDay ¶

func (t Time) EndAtDay(n ...int) Time

func (Time) EndAtDecade ¶

func (t Time) EndAtDecade(n ...int) Time

func (Time) EndAtHour ¶

func (t Time) EndAtHour(n ...int) Time

func (Time) EndAtMicro ¶

func (t Time) EndAtMicro(n ...int) Time

func (Time) EndAtMilli ¶

func (t Time) EndAtMilli(n ...int) Time

func (Time) EndAtMinute ¶

func (t Time) EndAtMinute(n ...int) Time

func (Time) EndAtMonth ¶

func (t Time) EndAtMonth(n ...int) Time

func (Time) EndAtNano ¶

func (t Time) EndAtNano(n ...int) Time

func (Time) EndAtQuarter ¶

func (t Time) EndAtQuarter(n ...int) Time

func (Time) EndAtSecond ¶

func (t Time) EndAtSecond(n ...int) Time

func (Time) EndAtWeek ¶

func (t Time) EndAtWeek(n ...int) Time

func (Time) EndAtWeekday ¶

func (t Time) EndAtWeekday(n ...int) Time

func (Time) EndAtYear ¶

func (t Time) EndAtYear(n ...int) Time

func (Time) EndByCentury ¶

func (t Time) EndByCentury(n ...int) Time

func (Time) EndByDay ¶

func (t Time) EndByDay(n ...int) Time

func (Time) EndByDecade ¶

func (t Time) EndByDecade(n ...int) Time

func (Time) EndByHour ¶

func (t Time) EndByHour(n ...int) Time

func (Time) EndByMicro ¶

func (t Time) EndByMicro(n ...int) Time

func (Time) EndByMilli ¶

func (t Time) EndByMilli(n ...int) Time

func (Time) EndByMinute ¶

func (t Time) EndByMinute(n ...int) Time

func (Time) EndByMonth ¶

func (t Time) EndByMonth(n ...int) Time

func (Time) EndByNano ¶

func (t Time) EndByNano(n ...int) Time

func (Time) EndByQuarter ¶

func (t Time) EndByQuarter(n ...int) Time

func (Time) EndBySecond ¶

func (t Time) EndBySecond(n ...int) Time

func (Time) EndByWeek ¶

func (t Time) EndByWeek(n ...int) Time

func (Time) EndByWeekday ¶

func (t Time) EndByWeekday(n ...int) Time

func (Time) EndByYear ¶

func (t Time) EndByYear(n ...int) Time

func (Time) EndCentury ¶

func (t Time) EndCentury(n ...int) Time

func (Time) EndDay ¶

func (t Time) EndDay(n ...int) Time

func (Time) EndDecade ¶

func (t Time) EndDecade(n ...int) Time

func (Time) EndHour ¶

func (t Time) EndHour(n ...int) Time

func (Time) EndInCentury ¶

func (t Time) EndInCentury(n ...int) Time

func (Time) EndInDay ¶

func (t Time) EndInDay(n ...int) Time

func (Time) EndInDecade ¶

func (t Time) EndInDecade(n ...int) Time

func (Time) EndInHour ¶

func (t Time) EndInHour(n ...int) Time

func (Time) EndInMicro ¶

func (t Time) EndInMicro(n ...int) Time

func (Time) EndInMilli ¶

func (t Time) EndInMilli(n ...int) Time

func (Time) EndInMinute ¶

func (t Time) EndInMinute(n ...int) Time

func (Time) EndInMonth ¶

func (t Time) EndInMonth(n ...int) Time

func (Time) EndInNano ¶

func (t Time) EndInNano(n ...int) Time

func (Time) EndInQuarter ¶

func (t Time) EndInQuarter(n ...int) Time

func (Time) EndInSecond ¶

func (t Time) EndInSecond(n ...int) Time

func (Time) EndInWeek ¶

func (t Time) EndInWeek(n ...int) Time

func (Time) EndInWeekday ¶

func (t Time) EndInWeekday(n ...int) Time

func (Time) EndInYear ¶

func (t Time) EndInYear(n ...int) Time

func (Time) EndMicro ¶

func (t Time) EndMicro(n ...int) Time

func (Time) EndMilli ¶

func (t Time) EndMilli(n ...int) Time

func (Time) EndMinute ¶

func (t Time) EndMinute(n ...int) Time

func (Time) EndMonth ¶

func (t Time) EndMonth(n ...int) Time

func (Time) EndNano ¶

func (t Time) EndNano(n ...int) Time

func (Time) EndQuarter ¶

func (t Time) EndQuarter(n ...int) Time

func (Time) EndSecond ¶

func (t Time) EndSecond(n ...int) Time

func (Time) EndWeek ¶

func (t Time) EndWeek(n ...int) Time

func (Time) EndWeekday ¶

func (t Time) EndWeekday(n ...int) Time

func (Time) EndYear ¶

func (t Time) EndYear(n ...int) Time

func (Time) Eq ¶

func (t Time) Eq(u Time) bool

Eq 返回 t == u

func (Time) Format ¶

func (t Time) Format(layout string) string

func (Time) Go ¶

func (t Time) Go(n ...int) Time

func (Time) GoCentury ¶

func (t Time) GoCentury(n ...int) Time

func (Time) GoDay ¶

func (t Time) GoDay(n ...int) Time

func (Time) GoDecade ¶

func (t Time) GoDecade(n ...int) Time

func (Time) GoHour ¶

func (t Time) GoHour(n ...int) Time

func (Time) GoMicro ¶

func (t Time) GoMicro(n ...int) Time

func (Time) GoMilli ¶

func (t Time) GoMilli(n ...int) Time

func (Time) GoMinute ¶

func (t Time) GoMinute(n ...int) Time

func (Time) GoMonth ¶

func (t Time) GoMonth(n ...int) Time

func (Time) GoNano ¶

func (t Time) GoNano(n ...int) Time

func (Time) GoQuarter ¶

func (t Time) GoQuarter(n ...int) Time

func (Time) GoSecond ¶

func (t Time) GoSecond(n ...int) Time

func (Time) GoWeek ¶

func (t Time) GoWeek(n ...int) Time

func (Time) GoWeekday ¶

func (t Time) GoWeekday(n ...int) Time

func (Time) GoYear ¶

func (t Time) GoYear(n ...int) Time

func (Time) Gt ¶

func (t Time) Gt(u Time) bool

Gt 返回 t 是否在 u 之后 (t > u)

func (Time) Hour ¶

func (t Time) Hour() int

func (Time) ISOWeek ¶

func (t Time) ISOWeek() (year, week int)

func (Time) InCentury ¶

func (t Time) InCentury(n ...int) Time

func (Time) InDay ¶

func (t Time) InDay(n ...int) Time

func (Time) InDecade ¶

func (t Time) InDecade(n ...int) Time

func (Time) InHour ¶

func (t Time) InHour(n ...int) Time

func (Time) InMicro ¶

func (t Time) InMicro(n ...int) Time

func (Time) InMilli ¶

func (t Time) InMilli(n ...int) Time

func (Time) InMinute ¶

func (t Time) InMinute(n ...int) Time

func (Time) InMonth ¶

func (t Time) InMonth(n ...int) Time

func (Time) InNano ¶

func (t Time) InNano(n ...int) Time

func (Time) InQuarter ¶

func (t Time) InQuarter(n ...int) Time

func (Time) InSecond ¶

func (t Time) InSecond(n ...int) Time

func (Time) InWeek ¶

func (t Time) InWeek(n ...int) Time

func (Time) InYear ¶

func (t Time) InYear(n ...int) Time

func (Time) IsAM ¶

func (t Time) IsAM() bool

IsAM 返回时间是否在上午 (00:00:00 ~ 11:59:59)

func (Time) IsDST ¶

func (t Time) IsDST() bool

IsDST 返回 t 是否夏令时

func (Time) IsLeapYear ¶

func (t Time) IsLeapYear() bool

IsLeapYear 返回 t 是否闰年

func (Time) IsLongYear ¶

func (t Time) IsLongYear() bool

IsLongYear 返回 t 是否长年

func (Time) IsSame ¶

func (t Time) IsSame(u Unit, target Time) bool

IsSame 返回 t 与 target 在指定单位下是否相同（包含上级单位一致性）。

func (Time) IsWeekend ¶

func (t Time) IsWeekend() bool

IsWeekend 返回时间是否在周末 (周六或周日)

func (Time) IsZero ¶

func (t Time) IsZero() bool

IsZero 返回 t 是否零时，即 0001-01-01 00:00:00 UTC。

func (Time) Local ¶

func (t Time) Local() Time

Local 返回本地时间

func (Time) Location ¶

func (t Time) Location() *time.Location

Location 返回时区信息

func (Time) Lt ¶

func (t Time) Lt(u Time) bool

Lt 返回 t 是否在 u 之前 (t < u)

func (Time) MarshalJSON ¶

func (t Time) MarshalJSON() ([]byte, error)

func (Time) MarshalText ¶

func (t Time) MarshalText() ([]byte, error)

func (Time) Micro ¶

func (t Time) Micro() int

Micro 返回微秒数 (0-999999)

func (Time) Milli ¶

func (t Time) Milli() int

Milli 返回毫秒数 (0-999)

func (Time) Minute ¶

func (t Time) Minute() int

func (Time) Month ¶

func (t Time) Month() int

func (Time) Nano ¶

func (t Time) Nano() int

Nano 返回纳秒数 (0-999999999)

func (Time) Round ¶

func (t Time) Round(d time.Duration) Time

Round 返回距离当前时间最近的 "跃点"。

这个函数有点不好理解，让我来尝试解释一下：想象在当前时间之外存在着另一个时间循环，时间轴每次移动 d，而每个 d 就是一个 "跃点"。函数返回距离当前时间最近的那个 "跃点"，如果当前时间正好位于两个 "跃点" 中间，返回指向未来的那个 "跃点"。

示例：假设当前时间是 2021-07-21 14:35:29.650

舍入到秒：t.Round(time.Second)
根据定义，时间 14:35:29.650 距离下一个跃点 14:35:30.000 最近 (只需要 350ms)，而距离上一个跃点 14:35:29.000 较远 (需要 650ms)，故返回下一个跃点 14:35:30.000。
舍入分钟：t.Round(time.Minute)
时间 14:35:29.650 距离上一个跃点 14:35:00 最近（只需要 29.650s），而距离下一个跃点 14:36:00 较远 (需要 30.350s)，故返回上一个跃点 14:35:00.000。
舍入 15 分钟：t.Round(15 * time.Minute)
跃点：--- 14:00:00 --- 14:15:00 --- 14:30:00 -- t --- 14:45:00 ---
时间 14:35:29.650 处在 14:30 (上一个跃点) 和 14:45 (下一个跃点) 之间，距离上一个跃点最近，故返回上一个跃点时间：14:30:00。

func (*Time) Scan ¶

func (t *Time) Scan(value any) (err error)

func (Time) Second ¶

func (t Time) Second() int

Second 返回时间的秒数 (0-59)

func (Time) Start ¶

func (t Time) Start(n ...int) Time

func (Time) StartAt ¶

func (t Time) StartAt(n ...int) Time

func (Time) StartAtCentury ¶

func (t Time) StartAtCentury(n ...int) Time

func (Time) StartAtDay ¶

func (t Time) StartAtDay(n ...int) Time

func (Time) StartAtDecade ¶

func (t Time) StartAtDecade(n ...int) Time

func (Time) StartAtHour ¶

func (t Time) StartAtHour(n ...int) Time

func (Time) StartAtMicro ¶

func (t Time) StartAtMicro(n ...int) Time

func (Time) StartAtMilli ¶

func (t Time) StartAtMilli(n ...int) Time

func (Time) StartAtMinute ¶

func (t Time) StartAtMinute(n ...int) Time

func (Time) StartAtMonth ¶

func (t Time) StartAtMonth(n ...int) Time

func (Time) StartAtNano ¶

func (t Time) StartAtNano(n ...int) Time

func (Time) StartAtQuarter ¶

func (t Time) StartAtQuarter(n ...int) Time

func (Time) StartAtSecond ¶

func (t Time) StartAtSecond(n ...int) Time

func (Time) StartAtWeek ¶

func (t Time) StartAtWeek(n ...int) Time

func (Time) StartAtWeekday ¶

func (t Time) StartAtWeekday(n ...int) Time

func (Time) StartAtYear ¶

func (t Time) StartAtYear(n ...int) Time

func (Time) StartByCentury ¶

func (t Time) StartByCentury(n ...int) Time

func (Time) StartByDay ¶

func (t Time) StartByDay(n ...int) Time

func (Time) StartByDecade ¶

func (t Time) StartByDecade(n ...int) Time

func (Time) StartByHour ¶

func (t Time) StartByHour(n ...int) Time

func (Time) StartByMicro ¶

func (t Time) StartByMicro(n ...int) Time

func (Time) StartByMilli ¶

func (t Time) StartByMilli(n ...int) Time

func (Time) StartByMinute ¶

func (t Time) StartByMinute(n ...int) Time

func (Time) StartByMonth ¶

func (t Time) StartByMonth(n ...int) Time

func (Time) StartByNano ¶

func (t Time) StartByNano(n ...int) Time

func (Time) StartByQuarter ¶

func (t Time) StartByQuarter(n ...int) Time

func (Time) StartBySecond ¶

func (t Time) StartBySecond(n ...int) Time

func (Time) StartByWeek ¶

func (t Time) StartByWeek(n ...int) Time

func (Time) StartByWeekday ¶

func (t Time) StartByWeekday(n ...int) Time

func (Time) StartByYear ¶

func (t Time) StartByYear(n ...int) Time

func (Time) StartCentury ¶

func (t Time) StartCentury(n ...int) Time

func (Time) StartDay ¶

func (t Time) StartDay(n ...int) Time

func (Time) StartDecade ¶

func (t Time) StartDecade(n ...int) Time

func (Time) StartHour ¶

func (t Time) StartHour(n ...int) Time

func (Time) StartInCentury ¶

func (t Time) StartInCentury(n ...int) Time

func (Time) StartInDay ¶

func (t Time) StartInDay(n ...int) Time

func (Time) StartInDecade ¶

func (t Time) StartInDecade(n ...int) Time

func (Time) StartInHour ¶

func (t Time) StartInHour(n ...int) Time

func (Time) StartInMicro ¶

func (t Time) StartInMicro(n ...int) Time

func (Time) StartInMilli ¶

func (t Time) StartInMilli(n ...int) Time

func (Time) StartInMinute ¶

func (t Time) StartInMinute(n ...int) Time

func (Time) StartInMonth ¶

func (t Time) StartInMonth(n ...int) Time

func (Time) StartInNano ¶

func (t Time) StartInNano(n ...int) Time

func (Time) StartInQuarter ¶

func (t Time) StartInQuarter(n ...int) Time

func (Time) StartInSecond ¶

func (t Time) StartInSecond(n ...int) Time

func (Time) StartInWeek ¶

func (t Time) StartInWeek(n ...int) Time

func (Time) StartInWeekday ¶

func (t Time) StartInWeekday(n ...int) Time

func (Time) StartInYear ¶

func (t Time) StartInYear(n ...int) Time

func (Time) StartMicro ¶

func (t Time) StartMicro(n ...int) Time

func (Time) StartMilli ¶

func (t Time) StartMilli(n ...int) Time

func (Time) StartMinute ¶

func (t Time) StartMinute(n ...int) Time

func (Time) StartMonth ¶

func (t Time) StartMonth(n ...int) Time

func (Time) StartNano ¶

func (t Time) StartNano(n ...int) Time

func (Time) StartQuarter ¶

func (t Time) StartQuarter(n ...int) Time

func (Time) StartSecond ¶

func (t Time) StartSecond(n ...int) Time

func (Time) StartWeek ¶

func (t Time) StartWeek(n ...int) Time

func (Time) StartWeekday ¶

func (t Time) StartWeekday(n ...int) Time

func (Time) StartYear ¶

func (t Time) StartYear(n ...int) Time

func (Time) String ¶

func (t Time) String() string

func (Time) Sub ¶

func (t Time) Sub(u Time) time.Duration

Sub 返回 t - u 的时间差

func (Time) Time ¶

func (t Time) Time() time.Time

Time 返回 time.Time

func (Time) To ¶

func (t Time) To(loc *time.Location) Time

To 返回指定的 loc 时间

func (Time) ToString ¶

func (t Time) ToString(f ...string) string

func (Time) Truncate ¶

func (t Time) Truncate(d time.Duration) Time

Truncate 返回最接近当前时间但不超过它的 "跃点"（向过去截断）。

与 Round 的区别：

Round 会选择最近的跃点（可能向未来舍入）
Truncate 永远向过去截断，不进行四舍五入

可视化理解：

时间轴: ---[d1]---- t ----[d2]----[d3]----
                   ↑
                当前时间 t

无论 t 距离 d1 还是 d2 更近，Truncate 都只会返回 d1（向过去）。如果 t 正好落在某个跃点上（如 d2），则返回 t 本身。

示例：假设当前时间是 2021-07-21 14:35:29.650

截断到秒：t.Truncate(time.Second)
直接舍弃毫秒部分，返回 14:35:29.000（向过去）。
截断到分钟：t.Truncate(time.Minute)
舍弃秒和毫秒部分，返回 14:35:00.000（向过去）。
截断到 15 分钟：t.Truncate(15 * time.Minute)
跃点：--- 14:00:00 --- 14:15:00 --- 14:30:00 ---- t ---- 14:45:00 --- ↑ 当前时间 14:35:29.650
返回上一个跃点：14:30:00.000（向过去）。

func (Time) UTC ¶

func (t Time) UTC() Time

UTC 返回 UTC 时间

func (Time) Unix ¶

func (t Time) Unix(n ...int) int64

Unix 返回时间戳，可选择指定精度。

参数 n (可选) 指定返回的时间戳精度：

不提供或 0: 秒级 (10位)
3: 毫秒级 (13位)
6: 微秒级 (16位)
9: 纳秒级 (19位)
其他值: 对应位数的时间戳

func (*Time) UnmarshalJSON ¶

func (t *Time) UnmarshalJSON(b []byte) (err error)

func (*Time) UnmarshalText ¶

func (t *Time) UnmarshalText(data []byte) error

func (Time) Value ¶

func (t Time) Value() (driver.Value, error)

func (Time) Weekday ¶

func (t Time) Weekday() time.Weekday

func (Time) WithWeekStarts ¶

func (t Time) WithWeekStarts(w time.Weekday) Time

WithWeekStarts 返回新实例，周起始日为 w。

func (Time) Year ¶

func (t Time) Year() int

func (Time) YearDay ¶

func (t Time) YearDay() int

YearDay 返回一年中的第几天，非闰年范围 [1,365]，闰年范围 [1,366]。

func (Time) YearDays ¶

func (t Time) YearDays() int

YearDays 返回本年总天数

func (Time) ZeroOr ¶

func (t Time) ZeroOr(u Time) Time

func (Time) Zone ¶

func (t Time) Zone() (name string, offset int)

Zone 获取当前时区的名称和偏移量

type Unit ¶

type Unit int

const (
	Century Unit = iota
	Decade
	Year
	Month
	Day
	Hour
	Minute
	Second
	Millisecond
	Microsecond
	Nanosecond
	Quarter // 季度流
	Week    // 月周流
	Weekday // 星期流
)

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL