Go 标准库 —— time 常用类型和方法

time 包提供了时间的显示和测量用的函数，日历的计算采用的是公历

本文仅整理演示常用的类型和方法，完整的可参考标准库文档

原文地址: https://shockerli.net/post/golang-pkg-time/

type Location

Location 代表一个（关联到某个时间点的）地点，以及该地点所在的时区

func LoadLocation

func LoadLocation(name string) (*Location, error)

LoadLocation 返回使用给定的名字创建的 Location

type Time

Time 代表一个纳秒精度的时间点

func Now

func Now() Time

Now 返回当前本地时间

func Parse

func Parse(layout, value string) (Time, error)

Parse 解析一个格式化的时间字符串并返回它代表的时间。
layout 定义输入的时间格式，value 的时间格式需与 layout 保持一致

Example：

t, _ := time.Parse("2006-01-02", "2018-05-31")
fmt.Println(t)

// 输出:
// 2018-05-31 00:00:00 +0000 UTC

func ParseInLocation

func ParseInLocation(layout, value string, loc *Location) (Time, error)

ParseInLocation 功能与 Parse 类似，但有两个重要的不同之处：
第一，当缺少时区信息时，Parse 将时间解释为 UTC 时间，而 ParseInLocation 将返回值的 Location 设置为 loc；
第二，当时间字符串提供了时区偏移量信息时，Parse 会尝试去匹配本地时区，而 ParseInLocation 会去匹配 loc。

Example：

loc, _ := time.LoadLocation("PRC")
t, _ := time.ParseInLocation("2006-01-02", "2018-05-31", loc)
fmt.Println(t)

// 输出:
// 2018-05-31 00:00:00 +0800 CST

func (Time) Location

func (t Time) Location() *Location

Location 返回 t 的地点和时区信息

Example：

loc, _ := time.LoadLocation("PRC")
t, _ := time.ParseInLocation("2006-01-02", "2018-05-31", loc)
fmt.Println(t.Location())

// 输出:
// PRC

func (Time) Unix

func (t Time) Unix() int64

Unix 将 t 表示为 Unix 时间，即从时间点January 1, 1970 UTC到时间点 t 所经过的时间（单位：秒）

func (Time) Format

func (t Time) Format(layout string) string

Format 根据 layout 指定的格式返回 t 代表的时间点的格式化文本表示。layout 定义了参考时间：

Mon Jan 2 15:04:05 -0700 MST 2006

格式化后的字符串表示，它作为期望输出的例子。同样的格式规则会被用于格式化时间。

Example：

loc, _ := time.LoadLocation("PRC")
t, _ := time.ParseInLocation("2006-01-02 15:04:05", "2018-05-31 09:22:19", loc)
fmt.Println(t)
fmt.Println(t.Format("2006-01-02 15:04:05"))

// 输出:
// 2018-05-31 09:22:19 +0800 CST
// 2018-05-31 09:22:19

func (Time) String

func (t Time) String() string

String 返回采用如下格式字符串的格式化时间：

"2006-01-02 15:04:05.999999999 -0700 MST"

type Duration

Duration 类型代表两个时间点之间经过的时间，以纳秒为单位。可表示的最长时间段大约290年。

常用的时间段：

const (
    Nanosecond  Duration = 1
    Microsecond          = 1000 * Nanosecond
    Millisecond          = 1000 * Microsecond
    Second               = 1000 * Millisecond
    Minute               = 60 * Second
    Hour                 = 60 * Minute
)

Example：
要将整数个某时间单元表示为 Duration 类型值，用乘法：

seconds := 100000
fmt.Println(time.Duration(seconds) * time.Second)

// 输出:
// 27h46m40s

type Timer

type Timer struct {
    C <-chan Time
    // 内含隐藏或非导出字段
}

Timer 类型代表单次时间事件。当 Timer 到期时，当时的时间会被发送给 C，除非 Timer 是被 AfterFunc 函数创建的。

func NewTimer

func NewTimer(d Duration) *Timer

NewTimer 创建一个 Timer，它会在最少过去时间段 d 后到期，向其自身的 C 字段发送当时的时间。

Example：

fmt.Println(time.Now())

timer := time.NewTimer(time.Second * 2)

<-timer.C

fmt.Println(time.Now())

// 输出:
// 2018-06-04 12:55:32.426676958 +0800 CST m=+0.000332587
// 2018-06-04 12:55:34.42745008 +0800 CST m=+2.001045690

func AfterFunc

func AfterFunc(d Duration, f func()) *Timer

AfterFunc 另起一个 go 协程等待时间段 d 过去，然后调用 f。它返回一个 Timer，可以通过调用其 Stop 方法来取消等待和对 f 的调用。

wait := sync.WaitGroup{}
fmt.Println("start", time.Now())

wait.Add(1)

timer := time.AfterFunc(time.Second * 3, func() {
    fmt.Println("get timer", time.Now())
    wait.Done()
})

time.Sleep(time.Second)
fmt.Println("sleep", time.Now())

timer.Reset(time.Second * 2)

wait.Wait()

// 输出:
// start 2018-06-04 13:11:25.478294853 +0800 CST m=+0.000332881
// sleep 2018-06-04 13:11:26.480826469 +0800 CST m=+1.002156500
// get timer 2018-06-04 13:11:28.483455973 +0800 CST m=+3.003496118

func (*Timer) Reset

func (t *Timer) Reset(d Duration) bool

Reset 使 t 重新开始计时，（本方法返回后再）等待时间段 d 过去后到期。如果调用时 t 还在等待中会返回真；如果 t 已经到期或者被停止了会返回假。

wait := sync.WaitGroup{}
fmt.Println("start", time.Now())

wait.Add(1)
timer := time.NewTimer(time.Second * 2)

go func() {
    <-timer.C

    fmt.Println("get timer", time.Now())
    wait.Done()
}()

time.Sleep(time.Second)
fmt.Println("sleep", time.Now())

timer.Reset(time.Second * 3)

wait.Wait()

// 输出:
// start 2018-06-04 13:07:51.780367114 +0800 CST m=+0.000324036
// sleep 2018-06-04 13:07:52.783389811 +0800 CST m=+1.003316644
// get timer 2018-06-04 13:07:55.784534298 +0800 CST m=+4.004371103

func (*Timer) Stop

func (t *Timer) Stop() bool

Stop 停止 Timer 的执行。如果停止了 t 会返回真；如果 t 已经被停止或者过期了会返回假。Stop 不会关闭通道 t.C，以避免从该通道的读取不正确的成功。

Example：

fmt.Println("start")

timer := time.NewTimer(time.Second * 2)

go func() {
    <-timer.C

    fmt.Println("get timer")
}()

if timer.Stop() {
    fmt.Println("timer stoped")
}

// 输出:
// start
// timer stoped

type Ticker

type Ticker struct {
    C <-chan Time // 周期性传递时间信息的通道
    // 内含隐藏或非导出字段
}

Ticker 保管一个通道，并每隔一段时间向其传递"tick"。

func NewTicker

func NewTicker(d Duration) *Ticker

NewTicker 返回一个新的 Ticker，该 Ticker 包含一个通道字段，并会每隔时间段 d 就向该通道发送当时的时间。它会调整时间间隔或者丢弃 tick 信息以适应反应慢的接收者。如果d <= 0会触发panic。关闭该 Ticker 可以释放相关资源。

Example：

fmt.Println("start", time.Now())

ticker := time.NewTicker(time.Second)

go func() {
    for tick := range ticker.C {
        fmt.Println("tick at", tick)
    }
}()

time.Sleep(time.Second * 5)
ticker.Stop()

fmt.Println("stoped", time.Now())

// 输出: 
// start 2018-06-04 13:21:20.443700752 +0800 CST m=+0.000376994
// tick at 2018-06-04 13:21:21.448276294 +0800 CST m=+1.004922401
// tick at 2018-06-04 13:21:22.44666211 +0800 CST m=+2.003278267
// tick at 2018-06-04 13:21:23.446749266 +0800 CST m=+3.003335423
// tick at 2018-06-04 13:21:24.445154097 +0800 CST m=+4.001710303
// stoped 2018-06-04 13:21:25.445239727 +0800 CST m=+5.001765933

func Sleep

func Sleep(d Duration)

Sleep 阻塞当前 go 协程至少 d 时间段。d <= 0时，Sleep 会立刻返回。

func After

func After(d Duration) <-chan Time

After 会在另一线程经过时间段 d 后向返回值发送当时的时间。等价于NewTimer(d).C。

Example：

fmt.Println("start", time.Now())

timer := time.After(time.Second)

select {
case t := <-timer:
    fmt.Println("get timer", t)
}

fmt.Println("stoped", time.Now())

// 输出:
// start 2018-06-04 13:35:23.367586344 +0800 CST m=+0.000370476
// get timer 2018-06-04 13:35:24.368447041 +0800 CST m=+1.001201148
// stoped 2018-06-04 13:35:24.368787684 +0800 CST m=+1.001541781

func Tick

func Tick(d Duration) <-chan Time

Tick 是 NewTicker 的封装，只提供对 Ticker 的通道的访问。如果不需要关闭 Ticker，本函数就很方便。

Example：

fmt.Println("start", time.Now())

count := 0
wait := sync.WaitGroup{}
wait.Add(1)
ticker := time.Tick(time.Second)

go func() {
    for tick := range ticker {
        count += 1
        fmt.Println("tick at", tick)

        if count >= 5 {
            wait.Done()
            break
        }
    }
}()

wait.Wait()

fmt.Println("stoped", time.Now())

// 输出:
// start 2018-06-04 13:30:56.49323192 +0800 CST m=+0.000306375
// tick at 2018-06-04 13:30:57.493468434 +0800 CST m=+1.000512884
// tick at 2018-06-04 13:30:58.493509786 +0800 CST m=+2.000524236
// tick at 2018-06-04 13:30:59.494584076 +0800 CST m=+3.001568495
// tick at 2018-06-04 13:31:00.494248484 +0800 CST m=+4.001202915
// tick at 2018-06-04 13:31:01.498742563 +0800 CST m=+5.005666860
// stoped 2018-06-04 13:31:01.499025155 +0800 CST m=+5.005949444

原文地址: https://shockerli.net/post/golang-pkg-time/