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