timeKit

Documentation

Index

• Constants
• Variables
• func Between(t, min, max time.Time) bool
• func ClearInterval(i *Interval)
• func ClearTimeout(timer *time.Timer)
• func ConvertLocation(t time.Time, loc *time.Location) time.Time
• func CorrectMachineTime(ctx context.Context, rootPassword string) (t time.Time, err error)
• func EarliestBy[T any](collection []T, iteratee func(item T) time.Time) T
• func Format[F ~string](t time.Time, format F) string
• func FormatCurrent[F ~string](f F) string
• func FormatDuration(d time.Duration) string
• func GetGMTLocation() *time.Location
• func GetLocalLocation() *time.Location
• func GetNetworkTime(ctx context.Context) (t time.Time, source string, err error)
• func GetNetworkTimeByUrl(ctx context.Context, url string) (t time.Time, err error)
• func GetUTCLocation() *time.Location
• func LatestBy[T any](collection []T, iteratee func(item T) time.Time) T
• func Parse[F ~string](format F, timeStr string) (time.Time, error)
• func ParseInLocation[F ~string](format F, timeStr string, loc *time.Location) (time.Time, error)
• func SetMachineTime(ctx context.Context, t time.Time, rootPassword string) error
• func SetTimeout(f func(), duration time.Duration) *time.Timer
• func ToDefaultDurationIfInvalid(d, def time.Duration) time.Duration
• func ToZeroAM(t time.Time) time.Time
• type Interval
  • func SetInterval(ctx context.Context, task func(t time.Time), duration time.Duration) *Interval
  • func (i *Interval) IsStopped() (rst bool)
  • func (i *Interval) Stop()
• type TimeFormat

Constants

const (
	Nanosecond  time.Duration = time.Nanosecond
	Microsecond               = time.Microsecond
	Millisecond               = time.Millisecond
	Second                    = time.Second
	Minute                    = time.Minute
	Hour                      = time.Hour
	Day                       = 24 * time.Hour
	Week                      = 7 * Day

	HalfHour = time.Minute * 30
)

Variables

var (
	// Earliest 返回最小值
	Earliest func(times ...time.Time) time.Time = lo.Earliest

	// Latest 返回最大值
	Latest func(times ...time.Time) time.Time = lo.Latest
)

var GetMachineTime func() time.Time = time.Now

GetMachineTime 获取系统时间（机器时间；本地时间；time.Local）.

var LoadLocation func(name string) (*time.Location, error) = time.LoadLocation

LoadLocation string => *time.Location

LoadLocation的输入参数的取值，除了该函数的源代码中可看到的”UTC”、”Local”，其余的值其实是遵照“IANA Time Zone”的规则，可以解压$GOROOT/lib/time/zoneinfo.zip 这个文件打开查看。 在Asia这个目录，我看到了Chongqing，Hong_Kong，但没Beijing。在国外获取中国北京时间，要用”PRC”，当然”Asia/Chongqing”也是个方法 参考：https://blog.csdn.net/qq_26981997/article/details/53454606

@param name (a) 可以为""（将返回 time.UTC）

(b) e.g. "Asia/Chongqing"

var ParseDuration func(str string) (time.Duration, error) = time.ParseDuration

ParseDuration string => time.Duration

@param str (1) 如果为 ""，将返回error

(2) e.g. "300ms"、"-1.5h"、"2h45m"

Functions

func Between

func Between(t, min, max time.Time) bool

Between 检查给定的时间是否处于某一时间区间内（左右都不包含！！！）

参考: 【收藏】开发常用的 10 个通用函数 https://mp.weixin.qq.com/s/tvy9L-pb_8WFWAmA9u-bMg

e.g. (cur, cur, cur.Add(time.Second)) => false (cur, cur.Add(-time.Second), cur.Add(time.Second)) => true

func ClearInterval

func ClearInterval(i *Interval)

ClearInterval 效果类似于JavaScript中的同名函数.

@param i 可以为nil

func ClearTimeout

func ClearTimeout(timer *time.Timer)

func ConvertLocation

func ConvertLocation(t time.Time, loc *time.Location) time.Time

ConvertLocation 时区转换.

PS: 返回值是个副本，不会修改传参t.

@param loc 目标时区

e.g. UTC+8(CST) 转 UTC+0

2022-05-05 14:33:40.562899 +0800 CST m=+0.001585418 => 2022-05-05 06:33:40.562899 +0000 UTC

func CorrectMachineTime

func CorrectMachineTime(ctx context.Context, rootPassword string) (t time.Time, err error)

CorrectMachineTime （根据网络时间）纠正系统时间

func EarliestBy

func EarliestBy[T any](collection []T, iteratee func(item T) time.Time) T

func Format

func Format[F ~string](t time.Time, format F) string

Format time.Time => string

@param t 不用担心t为nil的情况，详见下面的说明 @param formats 不传的话用默认值；传多个（包括一个）的话用第一个

一个方法如果接受类型为time.Time的参数，那么不用考虑该参数为nil的情况，因为： （1）time.Time类型变量的零值不为nil； （2）调用时，该参数位置不能直接传参nil（IDE报错：Cannot use 'nil' as the type time.Time）； （3）time.Time类型变量不能被赋值为nil（IDE报错：Cannot use 'nil' as the type time.Time）.

e.g.

str := timeKit.Format(time.Now(), timeKit.FormatCommon)
fmt.Println(str)	// 2023-08-14T17:10:17.057

func FormatCurrent

func FormatCurrent[F ~string](f F) string

FormatCurrent 格式化 当前时间 为 字符串.

@param formats 可以为""

e.g.

("2006-01-02T15:04:05.000") => "2023-08-17T16:05:14.985"

func FormatDuration

func FormatDuration(d time.Duration) string

FormatDuration time.Duration => string

e.g.

d := time.Minute*63 + time.Second*15
fmt.Println(timeKit.FormatDuration(d)) // 1h3m15s

func GetGMTLocation

func GetGMTLocation() *time.Location

func GetLocalLocation

func GetLocalLocation() *time.Location

func GetNetworkTime

func GetNetworkTime(ctx context.Context) (t time.Time, source string, err error)

GetNetworkTime

!!!: 方法体内不要直接使用 reqKit，以防import cycle.

@param ctx (1) 不能为nil

(2) 建议附带timeout

func GetNetworkTimeByUrl

func GetNetworkTimeByUrl(ctx context.Context, url string) (t time.Time, err error)

GetNetworkTimeByUrl

!!!: 方法体内不要直接使用 reqKit，以防import cycle.

func GetUTCLocation

func GetUTCLocation() *time.Location

func LatestBy

func LatestBy[T any](collection []T, iteratee func(item T) time.Time) T

func Parse

func Parse[F ~string](format F, timeStr string) (time.Time, error)

Parse 类型转换: string => time.Time

PS: (1) 为什么不直接使用 time.Parse()？

因为time.Parse使用 time.UTC 作为loc，会有时差.

(2) 本函数使用 time.Local 作为loc.

@param layout 时间格式 @param str 要解析的时间字符串

e.g. (timeKit.FormatDate, "2016-08-08")

func ParseInLocation

func ParseInLocation[F ~string](format F, timeStr string, loc *time.Location) (time.Time, error)

ParseInLocation

@param loc time.Local || time.UTC

func SetMachineTime

func SetMachineTime(ctx context.Context, t time.Time, rootPassword string) error

SetMachineTime 设置系统时间（机器时间）

PS: (1) 通过date命令设置root权限，需要root权限. (2) 只能精确到"秒".

@param password root用户的密码

func SetTimeout

func SetTimeout(f func(), duration time.Duration) *time.Timer

SetTimeout

参考： golang定时器函数 每隔几分钟执行一个函数

https://www.cnblogs.com/niuben/p/14368715.html

GO语言提前取消定时器

https://blog.csdn.net/u012265809/article/details/114939168

func ToDefaultDurationIfInvalid

func ToDefaultDurationIfInvalid(d, def time.Duration) time.Duration

ToDefaultDurationIfInvalid 如果d的值无效，将返回默认值def；否则返回d.

func ToZeroAM

func ToZeroAM(t time.Time) time.Time

ToZeroAM

@return 传参t对应的当天凌晨零点

e.g.

now := time.Now()
fmt.Println(now) 	// 2023-08-18 15:24:03.167655 +0800 CST m=+0.004041126
t := timeKit.ToZeroAM(now)
fmt.Println(t) 		// 2023-08-18 00:00:00 +0800 CST

Types

type Interval

type Interval struct {
	gmutex.RWMutex
	// contains filtered or unexported fields
}

Interval

参考: Golang正确停止Ticker https://blog.csdn.net/weixin_40098405/article/details/111517279

!!!: (1) 使用 time.Ticker 时要注意: Stop会停止Ticker，停止后，Ticker不会再被发送，但是Stop不会关闭通道，防止读取通道发生错误; (2) 可以重复调用 Ticker.Stop().

func SetInterval

func SetInterval(ctx context.Context, task func(t time.Time), duration time.Duration) *Interval

SetInterval 效果类似于JavaScript中的 window.setInterval().

@param ctx 控制 *Interval实例 的生命周期 @param task (1) 不能为nil

(2) 传参t为执行任务时的 time.Time

@param duration 必须>0

func (*Interval) IsStopped

func (i *Interval) IsStopped() (rst bool)

func (*Interval) Stop

func (i *Interval) Stop()

Stop

PS: (1) 可以多次调用，不会panic，但这样没意义（只有第一次调用才有意义）; (2) 如果有任务正在执行，会等它先执行完.

type TimeFormat

type TimeFormat string

const (
	FormatCommon         TimeFormat = "2006-01-02T15:04:05.000"
	FormatCommonWithoutT TimeFormat = "2006-01-02 15:04:05.000"

	FormatRFC3339         TimeFormat = time.RFC3339 // "2006-01-02T15:04:05Z07:00"
	FormatRFC3339WithoutT TimeFormat = "2006-01-02 15:04:05Z07:00"
	FormatRFC3339Nano     TimeFormat = time.RFC3339Nano // "2006-01-02T15:04:05.999999999Z07:00"

	FormatEntire         TimeFormat = "2006-01-02T15:04:05.000Z07:00 MST"
	FormatEntireWithoutT TimeFormat = "2006-01-02 15:04:05.000Z07:00 MST"

	FormatRFC1123  TimeFormat = time.RFC1123  // "Mon, 02 Jan 2006 15:04:05 MST"
	FormatRFC1123Z TimeFormat = time.RFC1123Z // "Mon, 02 Jan 2006 15:04:05 -0700"

	FormatDateOnly TimeFormat = time.DateOnly // "2006-01-02"
	FormatTimeOnly TimeFormat = time.TimeOnly // "15:04:05"
	FormatDateTime TimeFormat = time.DateTime // "2006-01-02 15:04:05"

	// FormatFileName 用于作为文件名（或目录名）的一部分
	/*
		PS:
		(1) 不能使用 "2006-01-02T15-04-05-000".
		(2) Windows OS，文件名不支持: \ / : * ? " < > |
	*/
	FormatFileName TimeFormat = "2006-01-02T15.04.05.000"

	FormatB TimeFormat = "2006-01-02 3:04:05.000 PM Mon Jan"
	FormatC TimeFormat = "3:04:05.000 PM Mon Jan"
)