thru

package module
v0.0.12 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 26, 2024 License: MIT Imports: 6 Imported by: 0

README

thru

Golang 时间包

安装

go get -u github.com/baagod/thru@latest

使用

创建时间

使用 thru 包中提供的函数创建时间对象。

now := thru.Now()                              // 现在。通过快捷函数创建
thru.New(time.Now())                           // 通过 time.Time 创建
thru.Unix(now.Unix())                          // 通过秒时间戳创建
thru.Unix(now.Unix(3))                         // 通过毫秒时间戳创建
thru.Parse("2023-03-19")                       // 通过解析自动字符串创建
thru.ParseByLayout("2006-01-02", "2023-03-19") // 通过布局格式创建
偏移时间

主要使用 AddYear(ymd ...int) 方法进行操作。该函数跟 time.AddDate() 相似，但是在不传入参数 d (要偏移的天数) 时，年、月不会溢出。 y, m, d 可以为负数。

现在假设当前时间是：2023-01-31 13:14:15 +0800 CST ( 中国标准时间 )

now.AddYear()       // 添加一年
now.AddMonth(-2, 3) // 在当前时间上偏移 -2月3天
now.AddDay(3)       // 三天后
now.Add(time.Hour)  // 1小时后

指定 d 参数时可能会导致日期溢出，例如：

now.AddYear(1, 1, 0)

该函数在指定 d 参数时的行为和 time.AddDate() 完全相同，因此返回 2024-03-02 13:14:15。这导致我们以为结果和预期不符，其实就是日期溢出了。

让我来尝试解释一下，这是因为 2024 年 2 月一共有 29 天。当我们预期从 2023-01-31 移动到 2024-02-31 时，实际上天数已经溢出 2 天，结果就是它跑到 2024-02-29 时发现后面还有 2 天要继续增加，最终返回 2024-03-02。

选择时间

主要使用 Go(y int, md ...int) 方法进行操作。该函数偏移 ±y 年并选择 m 月 d 日，如果 m, d 为负数，则从最后的月、日开始选择，并且不会溢出。例如：

  • Go(1, 13, 1) 会返回 2024-12-01 13:14:15。
  • Go(1, 2, 31) 返回二月最后一天 2024-02-29 13:14:15。
now.Go(-1, 11, -3) // 去年11月最后三天
now.GoMonth(-1, 2) // 年末第二天
now.GoDay(10)      // 本月10号

为了扩展，我还添加了一个 now.GoYear(y int, md ...int) 方法。跟 Go() 一样，但 y 指定为确切年份而非偏移。例如：

now.GoYear(2024, 03, 15) // 返回 2024-03-15 13:14:15

但是这就跟直接创建差不多了？有用吗？也许吧。

开始时间、结束时间

我们经常需要定位要时间边界，因此定义开始时间和结束时间的相关函数。

开始时间主要使用 Start(ymd ...int) 进行操作，它和 AddYear() 类似，但是返回开始时间。

now.Start()         // 今年开始时间 2023-01-01 00:00:00
now.Start(-1)       // 去年开始时间 2022-01-01 00:00:00
now.Start(1)        // 明年开始时间 2024-01-01 00:00:00
now.Start(1, 1, 1)  // 偏移后的开始时间 2024-03-03 00:00:00

now.StartWeek(-1) // 上周开始时间
now.StartWeek()   // 本周开始时间
now.StartWeek(1)  // 下周开始时间
now.StartWeek(2)  // 两周后的星期一开始时间

另外还提供以下方便方法，和 Start(ymd ...int) 一样：

  • StartMonth(md ...int): 从 m 开始。
  • StartDay(d int): 从 d 开始。

还有与开始时间 Start() 系列方法对应的所有结束时间函数: End, EndMoth, EndDay, EndWeek。

获取时间

获得各种时间的函数，例如要获得年、月、日、时、分、秒等。

Year() int   // 今年
Month() int  // 本月
Day() int    // 返回本月的第几天
Hour() int   // 返回小时 [0, 23]
Minute() int // 返回分钟 [0, 59]
Second() int // 返回秒 [0, 59]
Second(3)int // 毫秒 (3位)
Second(6)int // 微秒 (6位)
Second(9)int // 纳秒 (9位)

Clock() (hour, min, sec int) // 一天中的小时、分钟和秒
YearDay() int   // 一年中的第几天，非闰年范围 [1, 365]，闰年范围 [1, 366]。
Days() int      // 本年总天数
MonthDays() int // 本月总天数

Unix()  int64  // 秒时间戳 (10位)
Unix(3) int64  // 毫秒时间戳 (13位)
Unix(6) int64  // 微秒时间戳 (16位)
Unix(9) int64  // 纳秒时间戳 (19位)

Round(d time.Duration) Time    // 将时间四舍五入到最近接 d 的时间 (详情查阅注释)
Truncate(d time.Duration) Time // 永远向下取整到最近接 d 的时间 (详情查阅注释)

UTC() Time                  // 返回 UTC 时间
Local() Time                // 返回本地时间
In(loc *time.Location) Time // 返回指定的 loc 时间
Location() *time.Location   // 返回时区信息
Time() Time                 // 返回 time.Time
比较时间

比较时间差主要由以下两个函数返回，可指定要比较的时间单位。

  • DiffIn(u Time, uint string) float64
  • DiffAbsIn(u Time, uint string) float64
DiffIn('y') // 返回年差
DiffIn('M') // 返回月差
DiffIn('d') // 返回天差
DiffIn('h') // 返回时差
DiffIn('m') // 返回分差
DiffIn('s') // 返回秒差

另外补充具有和 time 包中相同的行为的函数：

  • Before(u Time) bool: 返回 t < u
  • After(u Time) bool: 返回 t > u
  • Equal(u Time) bool: 返回 t == u
  • Compare(u Time) int: 如果 t 小于 u，返回 -1；大于返回 1；等于返回 0
  • Sub(u Time) time.Duration: 返回 t - u 的时间差
  • thru.Since(Time): 返回自 t 以来经过的时间。它是 Now().Sub(t) 的简写。
  • thru.Until(Time): 返回直到 t 的持续时间。它是 t.Sub(Now()) 的简写。
时间字符串
now.String()   // 返回日期时间字符串: 2023-03-19 15:05:27
now.Format("2006年01年02日") // 指定时间布局格式返回
其他
IsZero() bool // 返回时间是否零时，即 0001-01-01 00:00:00 UTC。
ZeroOr(u Time) // 使用 u 代替零时 (isZero() is true) 时间
thru.IsLeapYear(y int) // 返回 y 是否闰年
thru.DaysIn(y int, ...m int) // 返回 y 年天数或 y 年 m 月天数

Documentation

Index

Constants

View Source 
const (
	Layout      = "01/02 03:04:05PM '06 -0700" // The reference time, in numerical order.
	ANSIC       = "Mon Jan _2 15:04:05 2006"
	UnixDate    = "Mon Jan _2 15:04:05 MST 2006"
	RubyDate    = "Mon Jan 02 15:04:05 -0700 2006"
	RFC822      = "02 Jan 06 15:04 MST"
	RFC822Z     = "02 Jan 06 15:04 -0700" // RFC822 with numeric zone
	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" // RFC1123 with numeric zone
	RFC3339     = "2006-01-02T15:04:05Z07:00"
	RFC3339Nano = "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"
	DateTime    = "2006-01-02 15:04:05"
	DateOnly    = "2006-01-02"
	TimeOnly    = "15:04:05"
)

Variables

This section is empty.

Functions

func Clamp 

func Clamp[T int | int64 | float64](value, min, max T) int

func DaysIn 

func DaysIn[T ~int](y T, m ...T) int

DaysIn 返回 y 年天数或 y 年 m 月天数

各月份的最大天数：

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

func IsLeapYear added in v0.0.11 

func IsLeapYear(y int) bool

IsLeapYear 返回 y 是否闰年

func Since 

func Since(t Time) time.Duration

Since 返回自 t 以来经过的时间。它是 Now().Sub(t) 的简写。

func Until 

func Until(t Time) time.Duration

Until 返回直到 t 的持续时间。它是 t.Sub(Now()) 的简写。

Types

type Time 

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

func Date 

func Date[Month ~int](
	year int, month Month, day, hour,
	min, sec, nsec int, loc ...*time.Location,
) Time

func New 

func New(t time.Time) Time

func Now 

func Now() Time

func Parse 

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

Parse 返回忽略错误的 ParseE()

func ParseByLayout 

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

func ParseByLayoutE 

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

func ParseE 

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

ParseE 解析 value 并返回它所表示的时间

func Unix 

func Unix(secs int64) Time

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

func (Time) Add 

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

Add 返回 t + d 时间

func (Time) AddDay 

func (t Time) AddDay(d ...int) Time

AddDay 添加天数，默认添加一天。

func (Time) AddMonth 

func (t Time) AddMonth(md ...int) Time

AddMonth 添加月日，默认添加一月。

func (Time) AddYear 

func (t Time) AddYear(ymd ...int) Time

AddYear 添加年月日，指定 d 参数时年、月会溢出。默认添加一年。

func (Time) After 

func (t Time) After(u Time) bool

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

func (Time) Before 

func (t Time) Before(u Time) bool

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

func (Time) Clock added in v0.0.10 

func (t Time) Clock() (hour, min, sec int)

Clock 返回一天中的小时、分钟和秒

func (Time) Compare 

func (t Time) Compare(u Time) int

Compare 比较 t 和 u。 如果 t 小于 u，返回 -1；大于返回 1；等于返回 0。

func (Time) Day 

func (t Time) Day() int

Day 返回 t 的天数

func (Time) Days 

func (t Time) Days() int

Days 返回本年总天数

func (Time) DiffAbsIn 

func (t Time) DiffAbsIn(u Time, unit string) float64

func (Time) DiffIn 

func (t Time) DiffIn(u Time, unit string) float64

DiffIn 返回 t 和 u 的时间差。使用 unit 参数指定比较单位：

  • "y": 年
  • "M": 月
  • "d": 日
  • "h": 小时
  • "m": 分钟
  • "s": 秒

func (Time) End 

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

End 它和 `AddYear(ymd ...int)` 类似，但是返回结束时间。

func (Time) EndDay 

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

EndDay 时间 t 的 d 日的结束时间

func (Time) EndMonth 

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

EndMonth 时间 t 的 m 月 d 日的结束时间

func (Time) EndWeek 

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

EndWeek 偏移至 ±n 周结束时间，默认返回本周结束时间。

func (Time) Equal 

func (t Time) Equal(u Time) bool

Equal 返回 t == u

func (Time) Format 

func (t Time) Format(layout string) string

func (Time) Go 

func (t Time) Go(y int, md ...int) Time

Go 偏移 ±y 年并选择 m 月 d 日，如果 m, d 为负数，则从最后的月、日开始偏移。

func (Time) GoDay 

func (t Time) GoDay(d int) Time

func (Time) GoMonth 

func (t Time) GoMonth(m int, d ...int) Time

func (Time) GoYear 

func (t Time) GoYear(y int, md ...int) Time

GoYear 和 Go() 一样，但 y 指定为确切年份而非偏移。

func (Time) Hour 

func (t Time) Hour() int

Hour 返回小时，范围 [0, 23]

func (Time) In 

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

In 返回指定的 loc 时间

func (Time) IsDST added in v0.0.10 

func (t Time) IsDST() bool

IsDST 返回时间是否夏令时

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) MarshalJSON 

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

MarshalJSON 将 t 转为 JSON 字符串时调用

func (Time) Minute 

func (t Time) Minute() int

Minute 返回分钟，范围 [0, 59]

func (Time) Month 

func (t Time) Month() int

Month 返回 t 的月份

func (Time) MonthDays added in v0.0.11 

func (t Time) MonthDays() int

MonthDays 返回本月总天数

func (Time) Round added in v0.0.10 

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 最近 (只需要 0.35ns)， 而距离上一个跃点 14:35:29.000 较远 (需要 65ns)，故返回下一个跃点 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) error

Scan 由 DB 转到 Go 时调用

func (Time) Second 

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

Second 返回时间的秒数或指定纳秒精度的小数部分

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

  • 不提供或 0: 返回整秒数 (0-59)
  • 1-9: 返回纳秒精度的小数部分，n 表示小数位数

func (Time) Start 

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

Start 它和 `AddYear(ymd ...int)` 类似，但是返回开始时间。

func (Time) StartDay 

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

StartDay 返回 t 月 d 日开始时间

func (Time) StartMonth 

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

StartMonth 返回 m 月 d 日的开始时间

func (Time) StartWeek 

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

StartWeek 偏移至 ±n 周开始时间，默认返回本周开始时间。

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) Truncate added in v0.0.10 

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

Truncate 与 Round 类似，但是 Truncate 永远返回指向过去时间的 "跃点"，不会进行四舍五入。

可视化理解： 

----|----|----|----|----
   d1    t   d2   d3

Truncate 将永远返回 d1，如果时间 t 正好处于某个 "跃点" 位置，返回 t。

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)

UnmarshalJSON 将 JSON 字符串转为 t 时调用

func (Time) Value 

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

Value 由 Go 转到 DB 时调用

func (Time) Weekday 

func (t Time) Weekday() time.Weekday

Weekday 返回星期几

func (Time) Year 

func (t Time) Year() int

Year 返回 t 的年份

func (Time) YearDay 

func (t Time) YearDay() int

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

func (Time) ZeroOr 

func (t Time) ZeroOr(u Time) Time

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.