time

原文：https://pkg.go.dev/time@go1.24.2

Package time provides functionality for measuring and displaying time.

​ time包提供了测量和显示时间的功能。

The calendrical calculations always assume a Gregorian calendar, with no leap seconds.

​ 日历计算总是假定格里高利日历，没有闰秒。

单调钟 Monotonic Clocks

Operating systems provide both a “wall clock,” which is subject to changes for clock synchronization, and a “monotonic clock,” which is not. The general rule is that the wall clock is for telling time and the monotonic clock is for measuring time. Rather than split the API, in this package the Time returned by time.Now contains both a wall clock reading and a monotonic clock reading; later time-telling operations use the wall clock reading, but later time-measuring operations, specifically comparisons and subtractions, use the monotonic clock reading.

​ 操作系统提供了“挂钟(wall clock)”和“单调钟(monotonic clock)”两种时钟，前者会受到时间同步的影响，后者则不会。一般规则是挂钟用于显示时间，而单调钟用于计时。为了不分割API，在这个包中，time.Now返回的时间包含了挂钟读数和单调钟读数；后续的时间显示操作使用挂钟读数，而后续的时间计算操作，特别是比较和减法操作，使用单调钟读数。

For example, this code always computes a positive elapsed time of approximately 20 milliseconds, even if the wall clock is changed during the operation being timed:

​ 例如，即使在计时操作中挂钟被更改，以下代码始终计算出大约20毫秒的正计时：

1
2
3
4

start := time.Now()
... operation that takes 20 milliseconds ...
t := time.Now()
elapsed := t.Sub(start)

Other idioms, such as time.Since(start), time.Until(deadline), and time.Now().Before(deadline), are similarly robust against wall clock resets.

​ 其他的习语，比如time.Since(start)，time.Until(deadline)，和time.Now().Before(deadline)，同样能够很好地应对挂钟重置的情况。

The rest of this section gives the precise details of how operations use monotonic clocks, but understanding those details is not required to use this package.

​ 本节的其余部分详细介绍了操作如何使用单调钟，但理解这些细节并不是使用该包的必要条件。

The Time returned by time.Now contains a monotonic clock reading. If Time t has a monotonic clock reading, t.Add adds the same duration to both the wall clock and monotonic clock readings to compute the result. Because t.AddDate(y, m, d), t.Round(d), and t.Truncate(d) are wall time computations, they always strip any monotonic clock reading from their results. Because t.In, t.Local, and t.UTC are used for their effect on the interpretation of the wall time, they also strip any monotonic clock reading from their results. The canonical way to strip a monotonic clock reading is to use t = t.Round(0).

​ time.Now返回的Time包含一个单调钟读数。如果Time t具有单调钟读数，则t.Add会将相同的持续时间添加到挂钟和单调钟读数中，以计算结果。因为t.AddDate(y, m, d)，t.Round(d)，和t.Truncate(d)都是针对挂钟时间的计算，它们总是从结果中剥离任何单调钟读数。因为t.In，t.Local，和t.UTC用于影响挂钟时间解释的效果，它们也会从结果中剥离任何单调钟读数。剥离单调钟读数的规范方法是使用t = t.Round(0)。

If Times t and u both contain monotonic clock readings, the operations t.After(u), t.Before(u), t.Equal(u), t.Compare(u), and t.Sub(u) are carried out using the monotonic clock readings alone, ignoring the wall clock readings. If either t or u contains no monotonic clock reading, these operations fall back to using the wall clock readings.

​ 如果Times t和u都包含单调钟读数，则操作t.After(u)，t.Before(u)，t.Equal(u)，t.Compare(u)，和t.Sub(u)仅使用单调钟读数进行计算，忽略挂钟读数。如果t或u中没有单调钟读数，则这些操作将回退到使用挂钟读数。

On some systems the monotonic clock will stop if the computer goes to sleep. On such a system, t.Sub(u) may not accurately reflect the actual time that passed between t and u.

​ 在某些系统上，如果计算机进入睡眠状态，单调钟会停止。在这种情况下，t.Sub(u)可能无法准确反映t和u之间经过的实际时间。

Because the monotonic clock reading has no meaning outside the current process, the serialized forms generated by t.GobEncode, t.MarshalBinary, t.MarshalJSON, and t.MarshalText omit the monotonic clock reading, and t.Format provides no format for it. Similarly, the constructors time.Date, time.Parse, time.ParseInLocation, and time.Unix, as well as the unmarshalers t.GobDecode, t.UnmarshalBinary. t.UnmarshalJSON, and t.UnmarshalText always create times with no monotonic clock reading.

​ 由于单调钟读数在当前进程之外没有意义，因此t.GobEncode、t.MarshalBinary、t.MarshalJSON和t.MarshalText生成的序列化形式都省略了单调钟读数，而t.Format则不提供任何格式。同样，构造函数time.Date、time.Parse、time.ParseInLocation和time.Unix，以及解码器t.GobDecode、t.UnmarshalBinary、t.UnmarshalJSON和t.UnmarshalText始终创建没有单调钟读数的时间。

The monotonic clock reading exists only in Time values. It is not a part of Duration values or the Unix times returned by t.Unix and friends.

​ 单调钟读数仅存在于Time值中。它不是Duration值或t.Unix和相关函数返回的Unix时间的一部分。

Note that the Go == operator compares not just the time instant but also the Location and the monotonic clock reading. See the documentation for the Time type for a discussion of equality testing for Time values.

​ 请注意，Go的==运算符不仅比较时间瞬间，还比较Location (时区)和单调钟读数。有关Time值的相等性测试的讨论，请参阅Time类型的文档。

For debugging, the result of t.String does include the monotonic clock reading if present. If t != u because of different monotonic clock readings, that difference will be visible when printing t.String() and u.String().

​ 为了调试，如果存在单调钟读数，则t.String的结果会包含该读数。如果t != u，因为具有不同的单调钟读数，那么在打印t.String()和u.String()时将可见这种差异。

计时器的精度 Timer Resolution

Timer resolution varies depending on the Go runtime, the operating system and the underlying hardware. On Unix, the resolution is ~1ms. On Windows version 1803 and newer, the resolution is ~0.5ms. On older Windows versions, the default resolution is ~16ms, but a higher resolution may be requested using golang.org/x/sys/windows.TimeBeginPeriod.

​ 计时器 的精度取决于 Go 运行时、操作系统以及底层硬件。在 Unix 系统中，计时器的精度约为 1 毫秒。在 Windows 1803 及更新版本中，精度约为 0.5 毫秒。在较早的 Windows 版本中，默认精度约为 16 毫秒，但可以通过使用 golang.org/x/sys/windows.TimeBeginPeriod 请求更高的精度。

常量

View Source

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

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"
	// Handy time stamps.
	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"
)

These are predefined layouts for use in Time.Format and time.Parse. The reference time used in these layouts is the specific time stamp:

​ 这些是用于Time.Format和time.Parse的预定义布局。这些布局中使用的参考时间是特定的时间戳：

01/02 03:04:05PM '06 -0700

(January 2, 15:04:05, 2006, in time zone seven hours west of GMT). That value is recorded as the constant named Layout, listed below. As a Unix time, this is 1136239445. Since MST is GMT-0700, the reference would be printed by the Unix date command as:

（2006年1月2日，15:04:05，位于GMT西七小时的时区）。该值被记录为名为Layout的常量，如下所示。作为Unix时间，这是1136239445。由于MST是GMT-0700，Unix date命令将打印出该参考值：

Mon Jan 2 15:04:05 MST 2006

It is a regrettable historic error that the date uses the American convention of putting the numerical month before the day.

​ 令人遗憾的是，该日期使用将数字月份放在日前的美国惯例。

The example for Time.Format demonstrates the working of the layout string in detail and is a good reference.

​ Time.Format 的示例详细演示了布局字符串的工作方式，是一个很好的参考。

Note that the RFC822, RFC850, and RFC1123 formats should be applied only to local times. Applying them to UTC times will use “UTC” as the time zone abbreviation, while strictly speaking those RFCs require the use of “GMT” in that case. In general RFC1123Z should be used instead of RFC1123 for servers that insist on that format, and RFC3339 should be preferred for new protocols. RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting; when used with time.Parse they do not accept all the time formats permitted by the RFCs and they do accept time formats not formally defined. The RFC3339Nano format removes trailing zeros from the seconds field and thus may not sort correctly once formatted.

​ 请注意，RFC822、RFC850 和 RFC1123 格式应仅应用于本地时间。将它们应用于 UTC 时间将使用 “UTC” 作为时区缩写，而严格来说，这些 RFC 要求在这种情况下使用 “GMT”。通常应该使用 RFC1123Z 替代 RFC1123，用于坚持该格式的服务器，并且应该为新协议首选 RFC3339。RFC3339、RFC822、RFC822Z、RFC1123 和 RFC1123Z 适用于格式化；与 time.Parse 一起使用时，它们不接受 RFC 允许的所有时间格式，并且它们接受形式上未定义的时间格式。RFC3339Nano 格式从秒字段中删除尾随的零，因此一旦格式化，可能无法正确排序。

Most programs can use one of the defined constants as the layout passed to Format or Parse. The rest of this comment can be ignored unless you are creating a custom layout string.

​ 大多数程序可以使用定义的常量之一作为传递给 Format 或 Parse 的布局。除非您要创建自定义布局字符串，否则可以忽略此注释的其余部分。

To define your own format, write down what the reference time would look like formatted your way; see the values of constants like ANSIC, StampMicro or Kitchen for examples. The model is to demonstrate what the reference time looks like so that the Format and Parse methods can apply the same transformation to a general time value.

​ 要定义自己的格式，请编写引用时间以您的方式格式化的样子；请参阅 ANSIC、StampMicro 或 Kitchen 等常量的值。模型是演示引用时间的外观，以便 Format 和 Parse 方法可以将相同的转换应用于一般时间值。

Here is a summary of the components of a layout string. Each element shows by example the formatting of an element of the reference time. Only these values are recognized. Text in the layout string that is not recognized as part of the reference time is echoed verbatim during Format and expected to appear verbatim in the input to Parse.

​ 以下是布局字符串的组件摘要。每个元素都以示例形式显示了参考时间的一个元素的格式。仅识别这些值。布局字符串中未被识别为参考时间的文本在 Format 中被回显，并期望在 Parse 的输入中以原样出现。

It is a regrettable historic error that the date uses the American convention of putting the numerical month before the day.

​ 这是一个令人遗憾的历史错误，日期使用了美国的习惯，在日期之前放置数字月份。

The example for Time.Format demonstrates the working of the layout string in detail and is a good reference.

​ Time.Format的示例详细演示了布局字符串的工作原理，是一个很好的参考。

Note that the RFC822, RFC850, and RFC1123 formats should be applied only to local times. Applying them to UTC times will use “UTC” as the time zone abbreviation, while strictly speaking those RFCs require the use of “GMT” in that case. In general RFC1123Z should be used instead of RFC1123 for servers that insist on that format, and RFC3339 should be preferred for new protocols. RFC3339, RFC822, RFC822Z, RFC1123, and RFC1123Z are useful for formatting; when used with time.Parse they do not accept all the time formats permitted by the RFCs and they do accept time formats not formally defined. The RFC3339Nano format removes trailing zeros from the seconds field and thus may not sort correctly once formatted.

​ 请注意，RFC822、RFC850和RFC1123格式仅适用于本地时间。将它们应用于UTC时间将使用"UTC"作为时区缩写，严格来说，这些RFC要求在这种情况下使用"GMT"。一般应该使用RFC1123Z而不是RFC1123，以满足一些服务器对该格式的要求，并且对于新协议应该优先选择RFC3339。RFC3339、RFC822、RFC822Z、RFC1123和RFC1123Z适用于格式化；当与time.Parse一起使用时，它们不接受RFC允许的所有时间格式，但可以接受未正式定义的时间格式。RFC3339Nano格式从秒字段中去除尾随的零，因此一旦格式化可能无法正确排序。

Most programs can use one of the defined constants as the layout passed to Format or Parse. The rest of this comment can be ignored unless you are creating a custom layout string.

​ 大多数程序可以使用定义的常量之一作为传递给Format或Parse的布局。除非您正在创建自定义布局字符串，否则可以忽略此注释的其余部分。

To define your own format, write down what the reference time would look like formatted your way; see the values of constants like ANSIC, StampMicro or Kitchen for examples. The model is to demonstrate what the reference time looks like so that the Format and Parse methods can apply the same transformation to a general time value.

​ 为了定义自己的格式，请按照您的方式编写参考时间的格式；参考ANSIC、StampMicro或Kitchen等常量的值以获取示例。该模型旨在演示参考时间的样式，以便Format和Parse方法可以将相同的转换应用于一般时间值。

Here is a summary of the components of a layout string. Each element shows by example the formatting of an element of the reference time. Only these values are recognized. Text in the layout string that is not recognized as part of the reference time is echoed verbatim during Format and expected to appear verbatim in the input to Parse.

​ 以下是布局字符串的组成部分的摘要。每个元素都通过示例显示了参考时间的格式化方式。只有这些值会被识别。布局字符串中未被识别为参考时间部分的文本在Format期间会被原样回显，并且期望在Parse的输入中原样出现。

Year: "2006" "06"
Month: "Jan" "January" "01" "1"
Day of the week: "Mon" "Monday"
Day of the month: "2" "_2" "02"
Day of the year: "__2" "002"
Hour: "15" "3" "03" (PM or AM)
Minute: "4" "04"
Second: "5" "05"
AM/PM mark: "PM"

Numeric time zone offsets format as follows:

​ 数字时区偏移的格式如下：

"-0700"     ±hhmm
"-07:00"    ±hh:mm
"-07"       ±hh
"-070000"   ±hhmmss
"-07:00:00" ±hh:mm:ss

Replacing the sign in the format with a Z triggers the ISO 8601 behavior of printing Z instead of an offset for the UTC zone. Thus:

​ 用 Z 替换格式中的符号会触发 ISO 8601 的行为，打印 Z 代替 UTC 时区的偏移。因此：

​ 用Z替换格式中的符号会触发ISO 8601的行为，将Z打印为UTC时区的偏移量。因此：

​ 将格式中的符号替换为 Z 会触发 ISO 8601 行为，即在 UTC 时区打印 Z 而不是时区偏移。因此：

"Z0700"      Z or ±hhmm
"Z07:00"     Z or ±hh:mm
"Z07"        Z or ±hh
"Z070000"    Z or ±hhmmss
"Z07:00:00"  Z or ±hh:mm:ss

Within the format string, the underscores in “_2” and “__2” represent spaces that may be replaced by digits if the following number has multiple digits, for compatibility with fixed-width Unix time formats. A leading zero represents a zero-padded value.

​ 在格式字符串中，"_2" 和 “__2“中的下划线表示空格，如果后面的数字有多个数字，则可以替换为空格，以与固定宽度的Unix时间格式兼容。前导零表示零填充值。

The formats __2 and 002 are space-padded and zero-padded three-character day of year; there is no unpadded day of year format.

​ 格式 __2 和 002 是以空格填充和以零填充的三位数年份的格式；没有未填充的年份格式。

A comma or decimal point followed by one or more zeros represents a fractional second, printed to the given number of decimal places. A comma or decimal point followed by one or more nines represents a fractional second, printed to the given number of decimal places, with trailing zeros removed. For example “15:04:05,000” or “15:04:05.000” formats or parses with millisecond precision.

​ 逗号或小数点后面跟着一个或多个零表示小数秒，打印到指定的小数位数。逗号或小数点后面跟着一个或多个九表示小数秒，打印到指定的小数位数，并去掉尾随的零。例如，“15:04:05,000” 或"15:04:05.000"格式可以用毫秒精度进行打印或解析。

Some valid layouts are invalid time values for time.Parse, due to formats such as _ for space padding and Z for zone information.

​ 一些有效的布局对于 time.Parse 来说是无效的时间值，原因是格式中使用了 _ 进行空格填充和 Z 进行时区信息的表示。

View Source

1
2
3
4
5
6
7
8

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

Common durations. There is no definition for units of Day or larger to avoid confusion across daylight savings time zone transitions.

​ 常见的时间段。为了避免在夏令时区转换中产生混淆，没有对Day （天）或更长时间单位进行定义。

To count the number of units in a Duration, divide:

​ 要计算Duration （持续时间）中的单位数量，请进行除法运算：

1
2

second := time.Second
fmt.Print(int64(second/time.Millisecond)) // prints 1000

To convert an integer number of units to a Duration, multiply:

​ 要将整数单位转换为 Duration，请使用乘法：

1
2

seconds := 10
fmt.Print(time.Duration(seconds)*time.Second) // prints 10s

变量

This section is empty.

函数

func After

1

func After(d Duration) <-chan Time

After waits for the duration to elapse and then sends the current time on the returned channel. It is equivalent to NewTimer(d).C.

​ After 等待指定的持续时间过去，然后将当前时间发送到返回的通道上。它等价于 NewTimer(d).C。

Before Go 1.23, this documentation warned that the underlying Timer would not be recovered by the garbage collector until the timer fired, and that if efficiency was a concern, code should use NewTimer instead and call Timer.Stop if the timer is no longer needed. As of Go 1.23, the garbage collector can recover unreferenced, unstopped timers. There is no reason to prefer NewTimer when After will do.

​ 在 Go 1.23 之前，这段文档警告说，底层的 Timer 在触发前不会被垃圾回收器回收，如果效率是一个问题，代码应该使用 NewTimer 并在计时器不再需要时调用 Timer.Stop。从 Go 1.23 开始，垃圾回收器可以回收未被引用且未停止的计时器。因此，当 After 可以满足需求时，没有理由偏向 NewTimer。

After Example(go1.23.0之前)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

package main

import (
	"fmt"
	"time"
)

var c chan int

func handle(int) {}

func main() {
	fmt.Println("before:", time.Now())
	select {
	case m := <-c:
		handle(m)
	case t, ok := <-time.After(2 * time.Second):
		if ok {
			fmt.Println("timed out:", t)
		}
	}
}

// Output:
//before: 2023-10-22 20:02:07.1865854 +0800 CST m=+0.006234601
//timed out: 2023-10-22 20:02:09.2169465 +0800 CST m=+2.036595701

After Example(go1.23.0开始)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

package main

import (
	"fmt"
	"time"
)

var c chan int

func handle(int) {}

func main() {
	select {
	case m := <-c:
		handle(m)
	case <-time.After(10 * time.Second):
		fmt.Println("timed out")
	}
}
Output:

timed out

func Sleep

1

func Sleep(d Duration)

Sleep pauses the current goroutine for at least the duration d. A negative or zero duration causes Sleep to return immediately.

​ Sleep函数暂停当前 goroutine 至少持续时间 d。负或零持续时间会使 Sleep 立即返回。

Sleep Example

1
2
3
4
5
6
7
8
9

package main

import (
	"time"
)

func main() {
	time.Sleep(100 * time.Millisecond)
}

func Tick

1

func Tick(d Duration) <-chan Time

Tick is a convenience wrapper for NewTicker providing access to the ticking channel only. Unlike NewTicker, Tick will return nil if d <= 0.

​ Tick 是 NewTicker 的便捷包装，只提供对滴答通道的访问。如果 d <= 0，与 NewTicker 不同，Tick 会返回 nil。

Before Go 1.23, this documentation warned that the underlying Ticker would never be recovered by the garbage collector, and that if efficiency was a concern, code should use NewTicker instead and call Ticker.Stop when the ticker is no longer needed. As of Go 1.23, the garbage collector can recover unreferenced tickers, even if they haven’t been stopped. The Stop method is no longer necessary to help the garbage collector. There is no longer any reason to prefer NewTicker when Tick will do.

​ 在 Go 1.23 之前，这段文档警告说，底层的 Ticker 永远不会被垃圾回收器回收，如果效率是一个问题，代码应该使用 NewTicker 并在计时器不再需要时调用 Ticker.Stop。从 Go 1.23 开始，垃圾回收器可以回收未被引用的滴答计时器，即使它们尚未停止。因此，当 Tick 可以满足需求时，不再需要通过调用 Stop 来帮助垃圾回收器，也没有理由偏向 NewTicker。

Tick Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

package main

import (
	"fmt"
	"time"
)

func statusUpdate() string { return "" }

func main() {
	c := time.Tick(5 * time.Second)
	for next := range c {
		fmt.Printf("%v %s\n", next, statusUpdate())
	}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

package main

import (
	"fmt"
	"time"
)

func statusUpdate() string { return "" }

func main() {
	c1 := time.Tick(0)
	fmt.Printf("c1=%v\n", c1)
	time.Sleep(2 * time.Second)
	fmt.Println("slept 2 seconds")
	fmt.Printf("c1=%v\n", c1)
	c2 := time.Tick(-1)
	fmt.Printf("c2=%v\n", c2)
	time.Sleep(2 * time.Second)
	fmt.Println("slept 2 seconds")
	fmt.Printf("c2=%v\n", c2)
}

// Output:
//c1=<nil>
//slept 2 seconds
//c1=<nil>
//c2=<nil>
//slept 2 seconds
//c2=<nil>

类型

type Duration

1

type Duration int64

A Duration represents the elapsed time between two instants as an int64 nanosecond count. The representation limits the largest representable duration to approximately 290 years.

​ Duration类型表示两个时间点之间经过的时间，以 int64 纳秒计数的方式表示。该表示方式将最大可表示的持续时间限制在大约 290 年左右。

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

package main

import (
	"fmt"
	"time"
)

func expensiveCall() {}

func main() {
	t0 := time.Now()
	expensiveCall()
	t1 := time.Now()
	fmt.Printf("The call took %v to run.\n", t1.Sub(t0))
}

func ParseDuration

1

func ParseDuration(s string) (Duration, error)

ParseDuration parses a duration string. A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “-1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

​ ParseDuration 函数解析一个持续时间字符串。持续时间字符串是一个可能带有符号的十进制数序列，每个数字都可以有小数部分和单位后缀，例如 “300ms”、"-1.5h” 或 “2h45m”。有效的时间单位有 “ns”、“us”(或 “µs”)、“ms”、“s”、“m” 和 “h”。

ParseDuration Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package main

import (
	"fmt"
	"time"
)

func main() {
	hours, _ := time.ParseDuration("10h")
	complex, _ := time.ParseDuration("1h10m10s")
	micro, _ := time.ParseDuration("1µs")
	// The package also accepts the incorrect but common prefix u for micro.
	micro2, _ := time.ParseDuration("1us")

	fmt.Println(hours)
	fmt.Println(complex)
	fmt.Printf("There are %.0f seconds in %v.\n", complex.Seconds(), complex)
	fmt.Printf("There are %d nanoseconds in %v.\n", micro.Nanoseconds(), micro)
	fmt.Printf("There are %6.2e seconds in %v.\n", micro2.Seconds(), micro)
}
Output:

10h0m0s
1h10m10s
There are 4210 seconds in 1h10m10s.
There are 1000 nanoseconds in 1µs.
There are 1.00e-06 seconds in 1µs.

func Since

1

func Since(t Time) Duration

Since returns the time elapsed since t. It is shorthand for time.Now().Sub(t).

​ Since 函数返回自 t 以来经过的时间。它相当于 time.Now().Sub(t)。

func Until <- go1.8

1

func Until(t Time) Duration

Until returns the duration until t. It is shorthand for t.Sub(time.Now()).

​ Until 函数返回直到 t 的时间间隔。它相当于 t.Sub(time.Now())。

(Duration) Abs <- go1.19

1

func (d Duration) Abs() Duration

Abs returns the absolute value of d. As a special case, math.MinInt64 is converted to math.MaxInt64.

​ Abs方法返回 d 的绝对值。作为特殊情况，将 math.MinInt64 转换为 math.MaxInt64。

(Duration) Hours

1

func (d Duration) Hours() float64

Hours returns the duration as a floating point number of hours.

​ Hours 方法返回持续时间作为小时数的浮点数。

Hours Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	h, _ := time.ParseDuration("4h30m")
	fmt.Printf("I've got %.1f hours of work left.", h.Hours())
}
Output:

I've got 4.5 hours of work left.

(Duration) Microseconds <- go1.13

1

func (d Duration) Microseconds() int64

Microseconds returns the duration as an integer microsecond count.

​ Microseconds方法返回以整数微秒计算的持续时间。

Microseconds Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	u, _ := time.ParseDuration("1s")
	fmt.Printf("One second is %d microseconds.\n", u.Microseconds())
}
Output:

One second is 1000000 microseconds.

(Duration) Milliseconds <- go1.13

1

func (d Duration) Milliseconds() int64

Milliseconds returns the duration as an integer millisecond count.

​ Milliseconds方法返回以整数毫秒计算的持续时间。

Milliseconds Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	u, _ := time.ParseDuration("1s")
	fmt.Printf("One second is %d milliseconds.\n", u.Milliseconds())
}
Output:

One second is 1000 milliseconds.

(Duration) Minutes

1

func (d Duration) Minutes() float64

Minutes returns the duration as a floating point number of minutes.

​ Minutes方法返回浮点数表示的分钟数持续时间。

Minutes Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	m, _ := time.ParseDuration("1h30m")
	fmt.Printf("The movie is %.0f minutes long.", m.Minutes())
}
Output:

The movie is 90 minutes long.

(Duration) Nanoseconds

1

func (d Duration) Nanoseconds() int64

Nanoseconds returns the duration as an integer nanosecond count.

​ Nanoseconds方法返回以整数纳秒计算的持续时间。

Nanoseconds Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	u, _ := time.ParseDuration("1µs")
	fmt.Printf("One microsecond is %d nanoseconds.\n", u.Nanoseconds())
}
Output:

One microsecond is 1000 nanoseconds.

(Duration) Round <- go1.9

1

func (d Duration) Round(m Duration) Duration

Round returns the result of rounding d to the nearest multiple of m. The rounding behavior for halfway values is to round away from zero. If the result exceeds the maximum (or minimum) value that can be stored in a Duration, Round returns the maximum (or minimum) duration. If m <= 0, Round returns d unchanged.

​ Round方法返回将d四舍五入为m的最近倍数的结果。如果结果超过可以存储在Duration中的最大(或最小)值，则Round返回最大(或最小)持续时间。如果m<=0，则Round返回未更改的d。

Round Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

package main

import (
	"fmt"
	"time"
)

func main() {
	d, err := time.ParseDuration("1h15m30.918273645s")
	if err != nil {
		panic(err)
	}

	round := []time.Duration{
		time.Nanosecond,
		time.Microsecond,
		time.Millisecond,
		time.Second,
		2 * time.Second,
		time.Minute,
		10 * time.Minute,
		time.Hour,
	}

	for _, r := range round {
		fmt.Printf("d.Round(%6s) = %s\n", r, d.Round(r).String())
	}
}
Output:

d.Round(   1ns) = 1h15m30.918273645s
d.Round(   1µs) = 1h15m30.918274s
d.Round(   1ms) = 1h15m30.918s
d.Round(    1s) = 1h15m31s
d.Round(    2s) = 1h15m30s
d.Round(  1m0s) = 1h16m0s
d.Round( 10m0s) = 1h20m0s
d.Round(1h0m0s) = 1h0m0s

(Duration) Seconds

1

func (d Duration) Seconds() float64

Seconds returns the duration as a floating point number of seconds.

​ Seconds方法返回浮点数表示的秒数持续时间。

Seconds Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	m, _ := time.ParseDuration("1m30s")
	fmt.Printf("Take off in t-%.0f seconds.", m.Seconds())
}
Output:

Take off in t-90 seconds.

(Duration) String

1

func (d Duration) String() string

String returns a string representing the duration in the form “72h3m0.5s”. Leading zero units are omitted. As a special case, durations less than one second format use a smaller unit (milli-, micro-, or nanoseconds) to ensure that the leading digit is non-zero. The zero duration formats as 0s.

​ String方法以 “72h3m0.5s” 的形式返回持续时间的字符串表示形式。省略前导零的单位。作为特殊情况，持续时间小于一秒的格式使用更小的单位(毫秒、微秒或纳秒)，以确保前导数字不为零。零持续时间格式化为0s。

String Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

package main

import (
	"fmt"
	"time"
)

func main() {
	fmt.Println(1*time.Hour + 2*time.Minute + 300*time.Millisecond)
	fmt.Println(300 * time.Millisecond)
}
Output:

1h2m0.3s
300ms

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

package main

import (
	"fmt"
	"time"
)

func main() {
	seconds := 10
	fmt.Println(time.Duration(seconds) * time.Second)            // 10s
	fmt.Println((time.Duration(seconds) * time.Second).String()) // 10s

	seconds = -10
	fmt.Println(time.Duration(seconds) * time.Second)            // -10s
	fmt.Println((time.Duration(seconds) * time.Second).String()) // -10s
}

// Output:
//10s
//10s
//-10s
//-10s

(Duration) Truncate <- go1.9

1

func (d Duration) Truncate(m Duration) Duration

Truncate returns the result of rounding d toward zero to a multiple of m. If m <= 0, Truncate returns d unchanged.

​ Truncate方法将 d 向零舍入为 m 的倍数并返回结果。如果 m <= 0，则 Truncate 返回未经更改的 d。

Truncate Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

package main

import (
	"fmt"
	"time"
)

func main() {
	d, err := time.ParseDuration("1h15m30.918273645s")
	if err != nil {
		panic(err)
	}

	trunc := []time.Duration{
		time.Nanosecond,
		time.Microsecond,
		time.Millisecond,
		time.Second,
		2 * time.Second,
		time.Minute,
		10 * time.Minute,
		time.Hour,
	}

	for _, t := range trunc {
		fmt.Printf("d.Truncate(%6s) = %s\n", t, d.Truncate(t).String())
	}
}
Output:

d.Truncate(   1ns) = 1h15m30.918273645s
d.Truncate(   1µs) = 1h15m30.918273s
d.Truncate(   1ms) = 1h15m30.918s
d.Truncate(    1s) = 1h15m30s
d.Truncate(    2s) = 1h15m30s
d.Truncate(  1m0s) = 1h15m0s
d.Truncate( 10m0s) = 1h10m0s
d.Truncate(1h0m0s) = 1h0m0s

type Location

1
2
3

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

A Location maps time instants to the zone in use at that time. Typically, the Location represents the collection of time offsets in use in a geographical area. For many Locations the time offset varies depending on whether daylight savings time is in use at the time instant.

​ Location结构体将时间时刻映射到使用的时区。通常，Location 表示在地理区域中使用的时间偏移集合。对于许多 Location，时间偏移量取决于在时间时刻是否使用夏令时。

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

package main

import (
	"fmt"
	"time"
)

func main() {
	// China doesn't have daylight saving. It uses a fixed 8 hour offset from UTC.
	secondsEastOfUTC := int((8 * time.Hour).Seconds())
	beijing := time.FixedZone("Beijing Time", secondsEastOfUTC)

	// If the system has a timezone database present, it's possible to load a location
	// from that, e.g.:
	//    newYork, err := time.LoadLocation("America/New_York")

	// Creating a time requires a location. Common locations are time.Local and time.UTC.
	timeInUTC := time.Date(2009, 1, 1, 12, 0, 0, 0, time.UTC)
	sameTimeInBeijing := time.Date(2009, 1, 1, 20, 0, 0, 0, beijing)

	// Although the UTC clock time is 1200 and the Beijing clock time is 2000, Beijing is
	// 8 hours ahead so the two dates actually represent the same instant.
	timesAreEqual := timeInUTC.Equal(sameTimeInBeijing)
	fmt.Println(timesAreEqual)

}
Output:

true

1

var Local *Location = &localLoc

Local represents the system’s local time zone. On Unix systems, Local consults the TZ environment variable to find the time zone to use. No TZ means use the system default /etc/localtime. TZ=”" means use UTC. TZ=“foo” means use file foo in the system timezone directory.

​ Local表示系统的本地时区。在 Unix 系统上，Local 会查询 TZ 环境变量以找到要使用的时区。没有 TZ 意味着使用系统默认值 /etc/localtime。TZ="" 表示使用 UTC。TZ=“foo” 表示使用系统时区目录中的文件 foo。

1

var UTC *Location = &utcLoc

UTC represents Universal Coordinated Time (UTC).

​ UTC 表示协调世界时 (UTC)。

func FixedZone

1

func FixedZone(name string, offset int) *Location

FixedZone returns a Location that always uses the given zone name and offset (seconds east of UTC).

​ FixedZone函数返回始终使用给定区域名称和偏移量(相对于 UTC 的秒数)的 Location。

FixedZone Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

package main

import (
	"fmt"
	"time"
)

func main() {
	loc := time.FixedZone("UTC-8", -8*60*60)
	t := time.Date(2009, time.November, 10, 23, 0, 0, 0, loc)
	fmt.Println("The time is:", t.Format(time.RFC822))
}
Output:

The time is: 10 Nov 09 23:00 UTC-8

func LoadLocation

1

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

LoadLocation returns the Location with the given name.

​ LoadLocation函数返回具有给定名称的 Location。

If the name is "" or “UTC”, LoadLocation returns UTC. If the name is “Local”, LoadLocation returns Local.

​ 如果名称为 "" 或 “UTC”，LoadLocation 返回 UTC。如果名称为 “Local”，LoadLocation 返回 Local。

Otherwise, the name is taken to be a location name corresponding to a file in the IANA Time Zone database, such as “America/New_York”.

​ 否则，名称被视为对应于 IANA 时区数据库中的文件的位置名称，例如 “America/New_York”。

LoadLocation looks for the IANA Time Zone database in the following locations in order:

​ LoadLocation 按顺序在以下位置查找 IANA 时区数据库：

• the directory or uncompressed zip file named by the ZONEINFO environment variable
• 由 ZONEINFO 环境变量指定的目录或未压缩的 zip 文件
• on a Unix system, the system standard installation location
• 在 Unix 系统上，是系统标准安装位置
• $GOROOT/lib/time/zoneinfo.zip
• the time/tzdata package, if it was imported
• 如果导入了 time/tzdata 包，它将用于查找时区信息。

LoadLocation Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

package main

import (
	"fmt"
	"time"
)

func main() {
	location, err := time.LoadLocation("America/Los_Angeles")
	if err != nil {
		panic(err)
	}

	timeInUTC := time.Date(2018, 8, 30, 12, 0, 0, 0, time.UTC)
	fmt.Println(timeInUTC.In(location))
}
Output:

2018-08-30 05:00:00 -0700 PDT

func LoadLocationFromTZData <- go1.10

1

func LoadLocationFromTZData(name string, data []byte) (*Location, error)

LoadLocationFromTZData returns a Location with the given name initialized from the IANA Time Zone database-formatted data. The data should be in the format of a standard IANA time zone file (for example, the content of /etc/localtime on Unix systems).

​ LoadLocationFromTZData 函数从 IANA 时区数据库格式的数据中返回一个指定名字的 Location。该数据应该采用标准的 IANA 时区文件格式(例如，在 Unix 系统上的 /etc/localtime 内容)。

(*Location) String

1

func (l *Location) String() string

String returns a descriptive name for the time zone information, corresponding to the name argument to LoadLocation or FixedZone.

​ String 方法返回一个描述性的字符串，表示时区信息，对应于 LoadLocation 或 FixedZone 中的 name 参数。

type Month

1

type Month int

A Month specifies a month of the year (January = 1, …).

​ Month 类型表示一年中的月份(1 代表一月，……)。

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

package main

import (
	"fmt"
	"time"
)

func main() {
	_, month, day := time.Now().Date()
	if month == time.November && day == 10 {
		fmt.Println("Happy Go day!")
	}
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

const (
	January Month = 1 + iota
	February
	March
	April
	May
	June
	July
	August
	September
	October
	November
	December
)

(Month) String

1

func (m Month) String() string

String returns the English name of the month (“January”, “February”, …).

​ String 方法返回该月份的英文名称(“January”、“February” 等)。

type ParseError

1
2
3
4
5
6
7

type ParseError struct {
	Layout     string
	Value      string
	LayoutElem string
	ValueElem  string
	Message    string
}

ParseError describes a problem parsing a time string.

​ ParseError 类型描述解析时间字符串时的问题。

(*ParseError) Error

1

func (e *ParseError) Error() string

Error returns the string representation of a ParseError.

​ Error 方法返回 ParseError 的字符串表示形式。

type Ticker

1
2
3
4

type Ticker struct {
	C <-chan Time // The channel on which the ticks are delivered.
	r runtimeTimer
}

A Ticker holds a channel that delivers “ticks” of a clock at intervals.

​ Ticker 持有一个通道，该通道以时间间隔提供时钟"滴答声"。

func NewTicker

1

func NewTicker(d Duration) *Ticker

NewTicker returns a new Ticker containing a channel that will send the current time on the channel after each tick. The period of the ticks is specified by the duration argument. The ticker will adjust the time interval or drop ticks to make up for slow receivers. The duration d must be greater than zero; if not, NewTicker will panic.

​ NewTicker 返回一个新的 Ticker，其中包含一个通道，该通道将在每次滴答后发送当前时间。滴答的周期由 d 参数指定。滴答器会调整时间间隔或丢弃滴答，以弥补接收速度慢的问题。d 必须大于零，否则 NewTicker 会触发 panic。

Before Go 1.23, the garbage collector did not recover tickers that had not yet expired or been stopped, so code often immediately deferred t.Stop after calling NewTicker, to make the ticker recoverable when it was no longer needed. As of Go 1.23, the garbage collector can recover unreferenced tickers, even if they haven’t been stopped. The Stop method is no longer necessary to help the garbage collector. (Code may of course still want to call Stop to stop the ticker for other reasons.)

​ 在 Go 1.23 之前，垃圾回收器不会回收尚未过期或未停止的滴答器，因此代码通常在调用 NewTicker 后立即使用 defer t.Stop 来确保滴答器在不再需要时可被回收。从 Go 1.23 开始，垃圾回收器可以回收未引用的滴答器，即使它们尚未停止。Stop 方法不再需要用来帮助垃圾回收器。（当然，代码仍可能需要调用 Stop 来出于其他原因停止滴答器。）

NewTicker Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()
	done := make(chan bool)
	go func() {
		time.Sleep(10 * time.Second)
		done <- true
	}()
	for {
		select {
		case <-done:
			fmt.Println("Done!")
			return
		case t := <-ticker.C:
			fmt.Println("Current time: ", t)
		}
	}
}

// Output:
//Current time:  2023-10-22 18:55:09.7151 +0800 CST m=+1.017119601
//Current time:  2023-10-22 18:55:10.710931 +0800 CST m=+2.012950601
//Current time:  2023-10-22 18:55:11.7104022 +0800 CST m=+3.012421801
//Current time:  2023-10-22 18:55:12.7095846 +0800 CST m=+4.011604201
//Current time:  2023-10-22 18:55:13.7084657 +0800 CST m=+5.010485301
//Current time:  2023-10-22 18:55:14.7109187 +0800 CST m=+6.012938301
//Current time:  2023-10-22 18:55:15.7088807 +0800 CST m=+7.010900301
//Current time:  2023-10-22 18:55:16.7066232 +0800 CST m=+8.008642801
//Current time:  2023-10-22 18:55:17.7201499 +0800 CST m=+9.022169501
//Current time:  2023-10-22 18:55:18.7178336 +0800 CST m=+10.019853201
//Done!

(*Ticker) Reset <- go1.15

1

func (t *Ticker) Reset(d Duration)

Reset stops a ticker and resets its period to the specified duration. The next tick will arrive after the new period elapses. The duration d must be greater than zero; if not, Reset will panic.

​ Reset方法停止一个 Ticker 并将其周期重置为指定的时间间隔。下一个 tick 将在新周期过去后到达。时间间隔d 必须大于零；否则，Reset 方法会 panic。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

package main

import (
	"fmt"
	"time"
)

func main() {
	ticker := time.NewTicker(time.Second)
	defer ticker.Stop()
	done := make(chan bool)
	go func() {
		time.Sleep(10 * time.Second)
		done <- true
	}()

	i := 3
	for {
		select {
		case <-done:
			fmt.Println("Done!")
			return
		case t := <-ticker.C:
			i--
			fmt.Println("Current time: ", t)
			if i == 0 {
				ticker.Reset(2 * time.Second)
				fmt.Println("--------After Reset------")
			}
		}
	}
}
// Output:
//Current time:  2023-10-22 19:01:52.641886 +0800 CST m=+1.017594201
//Current time:  2023-10-22 19:01:53.640631 +0800 CST m=+2.016339201
//Current time:  2023-10-22 19:01:54.6396148 +0800 CST m=+3.015323001
//--------After Reset------
//Current time:  2023-10-22 19:01:56.6480269 +0800 CST m=+5.023735101
//Current time:  2023-10-22 19:01:58.6463226 +0800 CST m=+7.022030801
//Current time:  2023-10-22 19:02:00.6546651 +0800 CST m=+9.030373301
//Done!

(*Ticker) Stop

1

func (t *Ticker) Stop()

Stop turns off a ticker. After Stop, no more ticks will be sent. Stop does not close the channel, to prevent a concurrent goroutine reading from the channel from seeing an erroneous “tick”.

​ Stop方法关闭一个 Ticker。Stop 后，将不会再发送任何 tick。Stop 不会关闭通道，以防止并发的 goroutine 从通道中读取到错误的"tick"。

type Time

1
2
3

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

A Time represents an instant in time with nanosecond precision.

​ Time 表示带有纳秒精度的时间点。

Programs using times should typically store and pass them as values, not pointers. That is, time variables and struct fields should be of type time.Time, not *time.Time.

​ 使用时间的程序通常应将其存储和传递为值，而不是指针。也就是说，时间变量和结构字段应为 time.Time 类型，而不是 *time.Time。

A Time value can be used by multiple goroutines simultaneously except that the methods GobDecode, UnmarshalBinary, UnmarshalJSON and UnmarshalText are not concurrency-safe.

​ Time 值可以被多个 goroutine 同时使用，除了 GobDecode、UnmarshalBinary、UnmarshalJSON 和 UnmarshalText 方法之外。这些方法不支持并发安全性。

Time instants can be compared using the Before, After, and Equal methods. The Sub method subtracts two instants, producing a Duration. The Add method adds a Time and a Duration, producing a Time.

​ 时间点可以使用 Before、After 和 Equal 方法进行比较。Sub 方法减去两个时间点，产生一个 Duration。Add 方法将一个时间点和一个 Duration 相加，产生一个时间点。

The zero value of type Time is January 1, year 1, 00:00:00.000000000 UTC. As this time is unlikely to come up in practice, the IsZero method gives a simple way of detecting a time that has not been initialized explicitly.

​ Time 类型的零值是 UTC 时间的 1 年 1 月 1 日 00:00:00.000000000。由于实际使用中不太可能遇到这个时间，IsZero 方法提供了一种简单的方式来检测未明确初始化的时间。

Each Time has associated with it a Location, consulted when computing the presentation form of the time, such as in the Format, Hour, and Year methods. The methods Local, UTC, and In return a Time with a specific location. Changing the location in this way changes only the presentation; it does not change the instant in time being denoted and therefore does not affect the computations described in earlier paragraphs.

​ 每个 Time 都有一个关联的 Location，在计算时间的表示形式时进行查询，例如在 Format、Hour 和 Year 方法中。Local、UTC 和 In 方法返回具有特定位置的时间。以这种方式更改位置只更改表示形式；它不会更改所表示的时间点，因此不会影响前面段落中描述的计算。

Representations of a Time value saved by the GobEncode, MarshalBinary, MarshalJSON, and MarshalText methods store the Time.Location’s offset, but not the location name. They therefore lose information about Daylight Saving Time.

​ 一个保存了 GobEncode，MarshalBinary，MarshalJSON 和 MarshalText 方法的 Time 值的表示形式存储了 Time.Location 的偏移量，但没有存储位置名称，因此它们会丢失关于夏令时的信息。

In addition to the required “wall clock” reading, a Time may contain an optional reading of the current process’s monotonic clock, to provide additional precision for comparison or subtraction. See the “Monotonic Clocks” section in the package documentation for details.

​ 除了必须的"挂钟"读数之外，一个 Time 可能还包含当前进程单调钟的可选读数，以提供比较或减法的额外精度。有关详细信息，请参见包文档中的"单调钟"部分。

Note that the Go == operator compares not just the time instant but also the Location and the monotonic clock reading. Therefore, Time values should not be used as map or database keys without first guaranteeing that the identical Location has been set for all values, which can be achieved through use of the UTC or Local method, and that the monotonic clock reading has been stripped by setting t = t.Round(0). In general, prefer t.Equal(u) to t == u, since t.Equal uses the most accurate comparison available and correctly handles the case when only one of its arguments has a monotonic clock reading.

​ 请注意，Go 的 == 操作符不仅比较时间瞬间，还比较 Location 和单调钟读数。因此，在未保证所有值都已设置相同的 Location 之前，不应将 Time 值用作映射或数据库键，可以通过使用 UTC 或 Local 方法来实现，同时剥离单调钟读数，设置 t = t.Round(0)。通常，优先使用 t.Equal(u) 而不是 t == u，因为 t.Equal 使用可用的最准确的比较，并正确处理仅有一个参数具有单调钟读数的情况。

func Date

1

func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time

Date returns the Time corresponding to yyyy-mm-dd hh:mm:ss + nsec nanoseconds in the appropriate zone for that time in the given location.

​ Date函数返回与给定位置中该时间的适当区域内的"yyyy-mm-dd hh:mm:ss + nsec nanoseconds"相对应的 Time。

The month, day, hour, min, sec, and nsec values may be outside their usual ranges and will be normalized during the conversion. For example, October 32 converts to November 1.

​ 月份，日期，小时，分钟，秒和纳秒的值可能超出其通常范围，并在转换期间进行归一化。例如，10 月 32 日转换为 11 月 1 日。

A daylight savings time transition skips or repeats times. For example, in the United States, March 13, 2011 2:15am never occurred, while November 6, 2011 1:15am occurred twice. In such cases, the choice of time zone, and therefore the time, is not well-defined. Date returns a time that is correct in one of the two zones involved in the transition, but it does not guarantee which.

​ 夏令时转换会跳过或重复时间。例如，在美国，2011 年 3 月 13 日 2:15 上午从未发生过，而在 2011 年 11 月 6 日 1:15 上午则发生了两次。在这种情况下，时区和因此时间的选择并不明确。Date 返回一个在转换涉及的两个区域中一个区域内正确的时间，但不保证是哪一个。

Date panics if loc is nil.

​ 如果 loc 为 nil，Date 将 panic。

Date Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
	fmt.Printf("Go launched at %s\n", t.Local())
}
Output:

Go launched at 2009-11-10 15:00:00 -0800 PST

func Now

1

func Now() Time

Now returns the current local time.

​ Now函数返回当前本地时间。

func Parse

1

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

Parse parses a formatted string and returns the time value it represents. See the documentation for the constant called Layout to see how to represent the format. The second argument must be parseable using the format string (layout) provided as the first argument.

​ Parse函数解析格式化的字符串并返回其代表的时间值。查看名为 Layout 的常量的文档以了解如何表示格式。第二个参数必须可用作第一个参数提供的格式字符串(layout)进行解析。

The example for Time.Format demonstrates the working of the layout string in detail and is a good reference.

​ Time.Format 的示例详细演示了布局字符串的工作原理，并且是一个很好的参考。

When parsing (only), the input may contain a fractional second field immediately after the seconds field, even if the layout does not signify its presence. In that case either a comma or a decimal point followed by a maximal series of digits is parsed as a fractional second. Fractional seconds are truncated to nanosecond precision.

​ 在解析时，输入可能包含紧随秒字段后面的小数秒字段，即使布局没有表示它的存在也是如此。在这种情况下，逗号或点号后跟最大系列的数字将被解析为小数秒。小数秒将被截断为纳秒精度。

Elements omitted from the layout are assumed to be zero or, when zero is impossible, one, so parsing “3:04pm” returns the time corresponding to Jan 1, year 0, 15:04:00 UTC (note that because the year is 0, this time is before the zero Time). Years must be in the range 0000..9999. The day of the week is checked for syntax but it is otherwise ignored.

​ 布局中省略的元素被假定为零或(当零不可能时)为一，因此解析"3:04pm"会返回对应于 0 年 1 月 1 日 15:04:00 UTC 的时间(请注意，因为年份是 0，所以此时间在零时间之前)。年份必须在 0000..9999 范围内。星期几的语法被检查，但是被忽略。

For layouts specifying the two-digit year 06, a value NN >= 69 will be treated as 19NN and a value NN < 69 will be treated as 20NN.

​ 对于指定两位数年份 06 的布局，NN >= 69 的值将被视为 19NN，NN < 69 的值将被视为 20NN。

The remainder of this comment describes the handling of time zones.

​ 此注释的其余部分描述了时区的处理方式。

In the absence of a time zone indicator, Parse returns a time in UTC.

​ 如果没有时区指示符，则 Parse 返回 UTC 时间。

When parsing a time with a zone offset like -0700, if the offset corresponds to a time zone used by the current location (Local), then Parse uses that location and zone in the returned time. Otherwise it records the time as being in a fabricated location with time fixed at the given zone offset.

​ 当解析具有类似于 -0700 的区域偏移量的时间时，如果该偏移量对应于当前位置(Local)使用的时区，则 Parse 使用该位置和区域在返回的时间中。否则，它会将时间记录为处于一个虚构的位置，该位置的时间固定在给定的区域偏移量上。

When parsing a time with a zone abbreviation like MST, if the zone abbreviation has a defined offset in the current location, then that offset is used. The zone abbreviation “UTC” is recognized as UTC regardless of location. If the zone abbreviation is unknown, Parse records the time as being in a fabricated location with the given zone abbreviation and a zero offset. This choice means that such a time can be parsed and reformatted with the same layout losslessly, but the exact instant used in the representation will differ by the actual zone offset. To avoid such problems, prefer time layouts that use a numeric zone offset, or use ParseInLocation.

​ 当解析具有类似于 MST 的区域缩写的时间时，如果该区域缩写在当前位置具有定义的偏移量，则使用该偏移量。无论位置如何，“UTC"区域缩写都被认为是 UTC。如果区域缩写未知，则 Parse 记录该时间处于具有给定区域缩写和零偏移量的虚构位置。此选择意味着可以使用相同的布局无损地解析和重新格式化此类时间，但是表示中使用的确切时刻将与实际区域偏移量不同。为避免此类问题，请使用使用数字区域偏移量的时间布局，或使用 ParseInLocation。

Parse Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

package main

import (
	"fmt"
	"time"
)

func main() {
	// See the example for Time.Format for a thorough description of how
	// to define the layout string to parse a time.Time value; Parse and
	// Format use the same model to describe their input and output.

	// longForm shows by example how the reference time would be represented in
	// the desired layout.
	const longForm = "Jan 2, 2006 at 3:04pm (MST)"
	t, _ := time.Parse(longForm, "Feb 3, 2013 at 7:54pm (PST)")
	fmt.Println(t)

	// shortForm is another way the reference time would be represented
	// in the desired layout; it has no time zone present.
	// Note: without explicit zone, returns time in UTC.
	const shortForm = "2006-Jan-02"
	t, _ = time.Parse(shortForm, "2013-Feb-03")
	fmt.Println(t)

	// Some valid layouts are invalid time values, due to format specifiers
	// such as _ for space padding and Z for zone information.
	// For example the RFC3339 layout 2006-01-02T15:04:05Z07:00
	// contains both Z and a time zone offset in order to handle both valid options:
	// 2006-01-02T15:04:05Z
	// 2006-01-02T15:04:05+07:00
	t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05Z")
	fmt.Println(t)
	t, _ = time.Parse(time.RFC3339, "2006-01-02T15:04:05+07:00")
	fmt.Println(t)
	_, err := time.Parse(time.RFC3339, time.RFC3339)
	fmt.Println("error", err) // Returns an error as the layout is not a valid time value

}
Output:

2013-02-03 19:54:00 -0800 PST
2013-02-03 00:00:00 +0000 UTC
2006-01-02 15:04:05 +0000 UTC
2006-01-02 15:04:05 +0700 +0700
error parsing time "2006-01-02T15:04:05Z07:00": extra text: "07:00"

func ParseInLocation <- go1.1

1

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

ParseInLocation is like Parse but differs in two important ways. First, in the absence of time zone information, Parse interprets a time as UTC; ParseInLocation interprets the time as in the given location. Second, when given a zone offset or abbreviation, Parse tries to match it against the Local location; ParseInLocation uses the given location.

​ ParseInLocation函数与Parse函数类似，但有两个重要区别。首先，在缺少时区信息的情况下，Parse将一个时间解释为UTC；而ParseInLocation则将时间解释为给定时区的时间。其次，当给定时区偏移量或缩写时，Parse会尝试将其与本地时区匹配；而ParseInLocation使用给定时区。

ParseInLocation Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

package main

import (
	"fmt"
	"time"
)

func main() {
	loc, _ := time.LoadLocation("Europe/Berlin")

	// This will look for the name CEST in the Europe/Berlin time zone.
	const longForm = "Jan 2, 2006 at 3:04pm (MST)"
	t, _ := time.ParseInLocation(longForm, "Jul 9, 2012 at 5:02am (CEST)", loc)
	fmt.Println(t)

	// Note: without explicit zone, returns time in given location.
	const shortForm = "2006-Jan-02"
	t, _ = time.ParseInLocation(shortForm, "2012-Jul-09", loc)
	fmt.Println(t)

}
Output:

2012-07-09 05:02:00 +0200 CEST
2012-07-09 00:00:00 +0200 CEST

func Unix

1

func Unix(sec int64, nsec int64) Time

Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC. It is valid to pass nsec outside the range [0, 999999999]. Not all sec values have a corresponding time value. One such value is 1«63-1 (the largest int64 value).

​ Unix函数返回与自1970年1月1日UTC以来的sec秒和nsec纳秒对应的本地时间。传递nsec超出范围[0, 999999999]是有效的。并非所有的sec值都有相应的时间值。其中一个这样的值是1«63-1(最大的int64值)。

Unix Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

package main

import (
	"fmt"
	"time"
)

func main() {
	unixTime := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
	fmt.Println(unixTime.Unix())
	t := time.Unix(unixTime.Unix(), 0).UTC()
	fmt.Println(t)

}
Output:

1257894000
2009-11-10 23:00:00 +0000 UTC

func UnixMicro <- go1.17

1

func UnixMicro(usec int64) Time

UnixMicro returns the local Time corresponding to the given Unix time, usec microseconds since January 1, 1970 UTC.

​ UnixMicro函数返回与自1970年1月1日UTC以来的usec微秒对应的本地时间。

UnixMicro Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

package main

import (
	"fmt"
	"time"
)

func main() {
	umt := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
	fmt.Println(umt.UnixMicro())
	t := time.UnixMicro(umt.UnixMicro()).UTC()
	fmt.Println(t)

}
Output:

1257894000000000
2009-11-10 23:00:00 +0000 UTC

func UnixMilli <- go1.17

1

func UnixMilli(msec int64) Time

UnixMilli returns the local Time corresponding to the given Unix time, msec milliseconds since January 1, 1970 UTC.

​ UnixMilli函数返回与自1970年1月1日UTC以来的msec毫秒对应的本地时间。

UnixMilli Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

package main

import (
	"fmt"
	"time"
)

func main() {
	umt := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
	fmt.Println(umt.UnixMilli())
	t := time.UnixMilli(umt.UnixMilli()).UTC()
	fmt.Println(t)

}
Output:

1257894000000
2009-11-10 23:00:00 +0000 UTC

(Time) Add

1

func (t Time) Add(d Duration) Time

Add returns the time t+d.

​ Add方法返回t+d时间。

Add Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Date(2009, 1, 1, 12, 0, 0, 0, time.UTC)
	afterTenSeconds := start.Add(time.Second * 10)
	afterTenMinutes := start.Add(time.Minute * 10)
	afterTenHours := start.Add(time.Hour * 10)
	afterTenDays := start.Add(time.Hour * 24 * 10)

	fmt.Printf("start = %v\n", start)
	fmt.Printf("start.Add(time.Second * 10) = %v\n", afterTenSeconds)
	fmt.Printf("start.Add(time.Minute * 10) = %v\n", afterTenMinutes)
	fmt.Printf("start.Add(time.Hour * 10) = %v\n", afterTenHours)
	fmt.Printf("start.Add(time.Hour * 24 * 10) = %v\n", afterTenDays)

}
Output:

start = 2009-01-01 12:00:00 +0000 UTC
start.Add(time.Second * 10) = 2009-01-01 12:00:10 +0000 UTC
start.Add(time.Minute * 10) = 2009-01-01 12:10:00 +0000 UTC
start.Add(time.Hour * 10) = 2009-01-01 22:00:00 +0000 UTC
start.Add(time.Hour * 24 * 10) = 2009-01-11 12:00:00 +0000 UTC

(Time) AddDate

1

func (t Time) AddDate(years int, months int, days int) Time

AddDate returns the time corresponding to adding the given number of years, months, and days to t. For example, AddDate(-1, 2, 3) applied to January 1, 2011 returns March 4, 2010.

​ AddDate方法返回添加指定年、月、日后的时间 t。例如，将 AddDate(-1, 2, 3) 应用于 2011 年 1 月 1 日，会返回 2010 年 3 月 4 日。

AddDate normalizes its result in the same way that Date does, so, for example, adding one month to October 31 yields December 1, the normalized form for November 31.

​ AddDate方法会像 Date 方法一样对其结果进行规范化，因此例如将 10 月 31 日加一月会得到规范化后的 11 月 31 日，即 12 月 1 日。

AddDate Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package main

import (
	"fmt"
	"time"
)

func main() {
	start := time.Date(2009, 1, 1, 0, 0, 0, 0, time.UTC)
	oneDayLater := start.AddDate(0, 0, 1)
	oneMonthLater := start.AddDate(0, 1, 0)
	oneYearLater := start.AddDate(1, 0, 0)

	fmt.Printf("oneDayLater: start.AddDate(0, 0, 1) = %v\n", oneDayLater)
	fmt.Printf("oneMonthLater: start.AddDate(0, 1, 0) = %v\n", oneMonthLater)
	fmt.Printf("oneYearLater: start.AddDate(1, 0, 0) = %v\n", oneYearLater)

}
Output:

oneDayLater: start.AddDate(0, 0, 1) = 2009-01-02 00:00:00 +0000 UTC
oneMonthLater: start.AddDate(0, 1, 0) = 2009-02-01 00:00:00 +0000 UTC
oneYearLater: start.AddDate(1, 0, 0) = 2010-01-01 00:00:00 +0000 UTC

(Time) After

1

func (t Time) After(u Time) bool

After reports whether the time instant t is after u.

​ After方法报告时间点 t 是否在 u 之后。

After Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

package main

import (
	"fmt"
	"time"
)

func main() {
	year2000 := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
	year3000 := time.Date(3000, 1, 1, 0, 0, 0, 0, time.UTC)

	isYear3000AfterYear2000 := year3000.After(year2000) // True
	isYear2000AfterYear3000 := year2000.After(year3000) // False

	fmt.Printf("year3000.After(year2000) = %v\n", isYear3000AfterYear2000)
	fmt.Printf("year2000.After(year3000) = %v\n", isYear2000AfterYear3000)

}
Output:

year3000.After(year2000) = true
year2000.After(year3000) = false

(Time) AppendBinary <- 1.24.0

1

func (t Time) AppendBinary(b []byte) ([]byte, error)

AppendBinary implements the encoding.BinaryAppender interface.

(Time) AppendFormat <- go1.5

1

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

AppendFormat is like Format but appends the textual representation to b and returns the extended buffer.

​ AppendFormat方法与 Format方法类似，但将文本表示附加到 b 中并返回扩展缓冲区。

AppendFormat Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

package main

import (
	"fmt"
	"time"
)

func main() {
	t := time.Date(2017, time.November, 4, 11, 0, 0, 0, time.UTC)
	text := []byte("Time: ")

	text = t.AppendFormat(text, time.Kitchen)
	fmt.Println(string(text))

}
Output:

Time: 11:00AM

(Time) AppendText <- 1.24.0

1

func (t Time) AppendText(b []byte) ([]byte, error)

AppendText implements the encoding.TextAppender interface. The time is formatted in RFC 3339 format with sub-second precision. If the timestamp cannot be represented as valid RFC 3339 (e.g., the year is out of range), then an error is returned.

(Time) Before

1

func (t Time) Before(u Time) bool

Before reports whether the time instant t is before u.

​ Before方法报告时间点 t 是否在 u 之前。

Before Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

package main

import (
	"fmt"
	"time"
)

func main() {
	year2000 := time.Date(2000, 1, 1, 0, 0, 0, 0, time.UTC)
	year3000 := time.Date(3000, 1, 1, 0, 0, 0, 0, time.UTC)

	isYear2000BeforeYear3000 := year2000.Before(year3000) // True
	isYear3000BeforeYear2000 := year3000.Before(year2000) // False

	fmt.Printf("year2000.Before(year3000) = %v\n", isYear2000BeforeYear3000)
	fmt.Printf("year3000.Before(year2000) = %v\n", isYear3000BeforeYear2000)

}
Output:

year2000.Before(year3000) = true
year3000.Before(year2000) = false

(Time) Clock

1

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

Clock returns the hour, minute, and second within the day specified by t.

​ Clock方法返回指定 t 的所在日的小时、分钟和秒。

(Time) Compare <- go1.20

1

func (t Time) Compare(u Time) int

Compare compares the time instant t with u. If t is before u, it returns -1; if t is after u, it returns +1; if they’re the same, it returns 0.

​ Compare方法比较时间点 t 和 u。如果 t 在 u 之前，则返回 -1；如果 t 在 u 之后，则返回 +1；如果它们相同，则返回 0。

(Time) Date

1

func (t Time) Date() (year int, month Month, day int)

Date returns the year, month, and day in which t occurs.

​ Date方法返回 t 所代表的年、月、日。

Date Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

package main

import (
	"fmt"
	"time"
)

func main() {
	d := time.Date(2000, 2, 1, 12, 30, 0, 0, time.UTC)
	year, month, day := d.Date()

	fmt.Printf("year = %v\n", year)
	fmt.Printf("month = %v\n", month)
	fmt.Printf("day = %v\n", day)

}
Output:

year = 2000
month = February
day = 1