package time · Go 標準庫中文參考

# package time `import "time"` time包提供了時間的顯示和測量用的函數。日歷的計算采用的是公歷。 ## Index * [Constants](#pkg-constants) * [type ParseError](#ParseError) * [func (e \*ParseError) Error() string](#ParseError.Error) * [type Weekday](#Weekday) * [func (d Weekday) String() string](#Weekday.String) * [type Month](#Month) * [func (m Month) String() string](#Month.String) * [type Location](#Location) * [func LoadLocation(name string) (\*Location, error)](#LoadLocation) * [func FixedZone(name string, offset int) \*Location](#FixedZone) * [func (l \*Location) String() string](#Location.String) * [type Time](#Time) * [func Date(year int, month Month, day, hour, min, sec, nsec int, loc \*Location) Time](#Date) * [func Parse(layout, value string) (Time, error)](#Parse) * [func ParseInLocation(layout, value string, loc \*Location) (Time, error)](#ParseInLocation) * [func Now() Time](#Now) * [func Unix(sec int64, nsec int64) Time](#Unix) * [func (t Time) Location() \*Location](#Time.Location) * [func (t Time) Zone() (name string, offset int)](#Time.Zone) * [func (t Time) IsZero() bool](#Time.IsZero) * [func (t Time) Local() Time](#Time.Local) * [func (t Time) UTC() Time](#Time.UTC) * [func (t Time) In(loc \*Location) Time](#Time.In) * [func (t Time) Unix() int64](#Time.Unix) * [func (t Time) UnixNano() int64](#Time.UnixNano) * [func (t Time) Equal(u Time) bool](#Time.Equal) * [func (t Time) Before(u Time) bool](#Time.Before) * [func (t Time) After(u Time) bool](#Time.After) * [func (t Time) Date() (year int, month Month, day int)](#Time.Date) * [func (t Time) Clock() (hour, min, sec int)](#Time.Clock) * [func (t Time) Year() int](#Time.Year) * [func (t Time) Month() Month](#Time.Month) * [func (t Time) ISOWeek() (year, week int)](#Time.ISOWeek) * [func (t Time) YearDay() int](#Time.YearDay) * [func (t Time) Day() int](#Time.Day) * [func (t Time) Weekday() Weekday](#Time.Weekday) * [func (t Time) Hour() int](#Time.Hour) * [func (t Time) Minute() int](#Time.Minute) * [func (t Time) Second() int](#Time.Second) * [func (t Time) Nanosecond() int](#Time.Nanosecond) * [func (t Time) Add(d Duration) Time](#Time.Add) * [func (t Time) AddDate(years int, months int, days int) Time](#Time.AddDate) * [func (t Time) Sub(u Time) Duration](#Time.Sub) * [func (t Time) Round(d Duration) Time](#Time.Round) * [func (t Time) Truncate(d Duration) Time](#Time.Truncate) * [func (t Time) Format(layout string) string](#Time.Format) * [func (t Time) String() string](#Time.String) * [func (t Time) GobEncode() ([]byte, error)](#Time.GobEncode) * [func (t \*Time) GobDecode(data []byte) error](#Time.GobDecode) * [func (t Time) MarshalBinary() ([]byte, error)](#Time.MarshalBinary) * [func (t \*Time) UnmarshalBinary(data []byte) error](#Time.UnmarshalBinary) * [func (t Time) MarshalJSON() ([]byte, error)](#Time.MarshalJSON) * [func (t \*Time) UnmarshalJSON(data []byte) error](#Time.UnmarshalJSON) * [func (t Time) MarshalText() ([]byte, error)](#Time.MarshalText) * [func (t \*Time) UnmarshalText(data []byte) error](#Time.UnmarshalText) * [type Duration](#Duration) * [func ParseDuration(s string) (Duration, error)](#ParseDuration) * [func Since(t Time) Duration](#Since) * [func (d Duration) Hours() float64](#Duration.Hours) * [func (d Duration) Minutes() float64](#Duration.Minutes) * [func (d Duration) Seconds() float64](#Duration.Seconds) * [func (d Duration) Nanoseconds() int64](#Duration.Nanoseconds) * [func (d Duration) String() string](#Duration.String) * [type Timer](#Timer) * [func NewTimer(d Duration) \*Timer](#NewTimer) * [func AfterFunc(d Duration, f func()) \*Timer](#AfterFunc) * [func (t \*Timer) Reset(d Duration) bool](#Timer.Reset) * [func (t \*Timer) Stop() bool](#Timer.Stop) * [type Ticker](#Ticker) * [func NewTicker(d Duration) \*Ticker](#NewTicker) * [func (t \*Ticker) Stop()](#Ticker.Stop) * [func Sleep(d Duration)](#Sleep) * [func After(d Duration) <-chan Time](#After) * [func Tick(d Duration) <-chan Time](#Tick) ### Examples * [After](#example-After) * [Date](#example-Date) * [Duration](#example-Duration) * [Month](#example-Month) * [Parse](#example-Parse) * [ParseInLocation](#example-ParseInLocation) * [Sleep](#example-Sleep) * [Tick](#example-Tick) * [Time.Format](#example-Time-Format) * [Time.Round](#example-Time-Round) * [Time.Truncate](#example-Time-Truncate) ## Constants ``` const ( 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 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 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" ) ``` 這些預定義的版式用于Time.Format和Time.Parse函數。用在版式中的參考時間是： ``` Mon Jan 2 15:04:05 MST 2006 ``` 對應的Unix時間是1136239445。因為MST的時區是GMT-0700，參考時間也可以表示為如下： ``` 01/02 03:04:05PM '06 -0700 ``` 要定義你自己的格式，寫下該參考時間應用于你的格式的情況；例子請參見ANSIC、StampMicro或Kitchen等常數的值。該模型是為了演示參考時間的格式化效果，如此一來Format和Parse方法可以將相同的轉換規則用于一個普通的時間值。在格式字符串中，用前置的'0'表示一個可以被可以被數字替換的'0'（如果它后面的數字有兩位）；使用下劃線表示一個可以被數字替換的空格（如果它后面的數字有兩位）；以便兼容Unix定長時間格式。小數點后跟0到多個'0'，表示秒數的小數部分，輸出時會生成和'0'一樣多的小數位；小數點后跟0到多個'9'，表示秒數的小數部分，輸出時會生成和'9'一樣多的小數位但會將拖尾的'0'去掉。（只有）解析時，輸入可以在秒字段后面緊跟一個小數部分，即使格式字符串里沒有指明該部分。此時，小數點及其后全部的數字都會成為秒的小數部分。數字表示的時區格式如下： ``` -0700 ±hhmm -07:00 ±hh:mm ``` 將格式字符串中的負號替換為Z會觸發ISO 8601行為（當時區是UTC時，輸出Z而不是時區偏移量），這樣： ``` Z0700 Z or ±hhmm Z07:00 Z or ±hh:mm ``` ## type [ParseError](https://github.com/golang/go/blob/master/src/time/format.go#L598 "View Source") ``` type ParseError struct { Layout string Value string LayoutElem string ValueElem string Message string } ``` ParseError描述解析時間字符串時出現的錯誤。 ### func (\*ParseError) [Error](https://github.com/golang/go/blob/master/src/time/format.go#L611 "View Source") ``` func (e *ParseError) Error() string ``` Error返回ParseError的字符串表示。 ## type [Weekday](https://github.com/golang/go/blob/master/src/time/time.go#L115 "View Source") ``` type Weekday int ``` Weekday代表一周的某一天。 ``` const ( Sunday Weekday = iota Monday Tuesday Wednesday Thursday Friday Saturday ) ``` ### func (Weekday) [String](https://github.com/golang/go/blob/master/src/time/time.go#L138 "View Source") ``` func (d Weekday) String() string ``` String返回該日（周幾）的英文名（"Sunday"、"Monday"，……） ## type [Month](https://github.com/golang/go/blob/master/src/time/time.go#L79 "View Source") ``` type Month int ``` Month代表一年的某個月。 ``` const ( January Month = 1 + iota February March April May June July August September October November December ) ``` Example ``` _, month, day := time.Now().Date() if month == time.November && day == 10 { fmt.Println("Happy Go day!") } ``` ### func (Month) [String](https://github.com/golang/go/blob/master/src/time/time.go#L112 "View Source") ``` func (m Month) String() string ``` String返回月份的英文名（"January"，"February"，……） ## type [Location](https://github.com/golang/go/blob/master/src/time/zoneinfo.go#L15 "View Source") ``` type Location struct { // 內含隱藏或非導出字段 } ``` Location代表一個（關聯到某個時間點的）地點，以及該地點所在的時區。 ``` var Local *Location = &localLoc ``` Local代表系統本地，對應本地時區。 ``` var UTC *Location = &utcLoc ``` UTC代表通用協調時間，對應零時區。 ### func [LoadLocation](https://github.com/golang/go/blob/master/src/time/zoneinfo.go#L273 "View Source") ``` func LoadLocation(name string) (*Location, error) ``` LoadLocation返回使用給定的名字創建的Location。如果name是""或"UTC"，返回UTC；如果name是"Local"，返回Local；否則name應該是IANA時區數據庫里有記錄的地點名（該數據庫記錄了地點和對應的時區），如"America/New_York"。 LoadLocation函數需要的時區數據庫可能不是所有系統都提供，特別是非Unix系統。此時LoadLocation會查找環境變量ZONEINFO指定目錄或解壓該變量指定的zip文件（如果有該環境變量）；然后查找Unix系統的慣例時區數據安裝位置，最后查找$GOROOT/lib/time/zoneinfo.zip。 ### func [FixedZone](https://github.com/golang/go/blob/master/src/time/zoneinfo.go#L89 "View Source") ``` func FixedZone(name string, offset int) *Location ``` FixedZone使用給定的地點名name和時間偏移量offset（單位秒）創建并返回一個Location ### func (\*Location) [String](https://github.com/golang/go/blob/master/src/time/zoneinfo.go#L83 "View Source") ``` func (l *Location) String() string ``` String返回對時區信息的描述，返回值綁定為LoadLocation或FixedZone函數創建l時的name參數。 ## type [Time](https://github.com/golang/go/blob/master/src/time/time.go#L34 "View Source") ``` type Time struct { // 內含隱藏或非導出字段 } ``` Time代表一個納秒精度的時間點。程序中應使用Time類型值來保存和傳遞時間，而不能用指針。就是說，表示時間的變量和字段，應為time.Time類型，而不是\*time.Time.類型。一個Time類型值可以被多個go程同時使用。時間點可以使用Before、After和Equal方法進行比較。Sub方法讓兩個時間點相減，生成一個Duration類型值（代表時間段）。Add方法給一個時間點加上一個時間段，生成一個新的Time類型時間點。 Time零值代表時間點January 1, year 1, 00:00:00.000000000 UTC。因為本時間點一般不會出現在使用中，IsZero方法提供了檢驗時間是否顯式初始化的一個簡單途徑。每一個時間都具有一個地點信息（及對應地點的時區信息），當計算時間的表示格式時，如Format、Hour和Year等方法，都會考慮該信息。Local、UTC和In方法返回一個指定時區（但指向同一時間點）的Time。修改地點/時區信息只是會改變其表示；不會修改被表示的時間點，因此也不會影響其計算。 ### func [Date](https://github.com/golang/go/blob/master/src/time/time.go#L1022 "View Source") ``` func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time ``` Date返回一個時區為loc、當地時間為： ``` year-month-day hour:min:sec + nsec nanoseconds ``` 的時間點。 month、day、hour、min、sec和nsec的值可能會超出它們的正常范圍，在轉換前函數會自動將之規范化。如October 32被修正為November 1。夏時制的時區切換會跳過或重復時間。如，在美國，March 13, 2011 2:15am從來不會出現，而November 6, 2011 1:15am?會出現兩次。此時，時區的選擇和時間是沒有良好定義的。Date會返回在時區切換的兩個時區其中一個時區正確的時間，但本函數不會保證在哪一個時區正確。如果loc為nil會panic。 Example ``` 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](https://github.com/golang/go/blob/master/src/time/time.go#L784 "View Source") ``` func Now() Time ``` Now返回當前本地時間。 ### func [Parse](https://github.com/golang/go/blob/master/src/time/format.go#L711 "View Source") ``` func Parse(layout, value string) (Time, error) ``` Parse解析一個格式化的時間字符串并返回它代表的時間。layout定義了參考時間： ``` Mon Jan 2 15:04:05 -0700 MST 2006 ``` 在輸入格式下的字符串表示，作為輸入的格式的示例。同樣的格式規則會被用于輸入字符串。預定義的ANSIC、UnixDate、RFC3339和其他版式描述了參考時間的標準或便捷表示。要獲得更多參考時間的定義和格式，參見本包的ANSIC和其他版式常量。 value中漏掉的元素會被視為0；如果不能是0，會被視為1。因此，解析"3:04pm"會返回對應時間點：Jan 1, year 0, 15:04:00 UTC的Time（注意因為year為0，該時間在Time零值之前）。年份必須在0000..9999范圍內。周幾會被檢查其語法，但是會被忽略。如果缺少表示時區的信息，Parse會將時區設置為UTC。當解析具有時區偏移量的時間字符串時，如果該時區偏移量和本地時區相同，Parse會在返回值中將Location設置為本地和本地時區。否則，它會將Location設置為一個虛構的具有該時區偏移量的值。當解析具有時區縮寫的時間字符串時，如果該時區縮寫具有已定義的時間偏移量，會使用該偏移量。如果時區縮寫是"UTC"，會將該時間視為UTC時間，不考慮Location。如果時區縮寫是未知的，Parse會將Location設置為一個虛構的地點為時區縮寫，時間偏移量為0的值。這種做法是為了讓一個時間可以在同一版式下不丟失信息的被解析和重新格式化；但字符串表示和具體表示的時間點會因為實際時區偏移量而不同。為了避免這些問題，請使用數字表示的時區偏移量，或者使用ParseInLocation函數。 Example ``` // 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) ``` Output: ``` 2013-02-03 19:54:00 -0800 PST 2013-02-03 00:00:00 +0000 UTC ``` ### func [ParseInLocation](https://github.com/golang/go/blob/master/src/time/format.go#L720 "View Source") ``` func ParseInLocation(layout, value string, loc *Location) (Time, error) ``` ParseInLocation類似Parse但有兩個重要的不同之處。第一，當缺少時區信息時，Parse將時間解釋為UTC時間，而ParseInLocation將返回值的Location設置為loc；第二，當時間字符串提供了時區偏移量信息時，Parse會嘗試去匹配本地時區，而ParseInLocation會去匹配loc。 Example ``` loc, _ := time.LoadLocation("Europe/Berlin") 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](https://github.com/golang/go/blob/master/src/time/time.go#L972 "View Source") ``` func Unix(sec int64, nsec int64) Time ``` Unix創建一個本地時間，對應sec和nsec表示的Unix時間（從January 1, 1970 UTC至該時間的秒數和納秒數）。 nsec的值在[0, 999999999]范圍外是合法的。 ### func (Time) [Location](https://github.com/golang/go/blob/master/src/time/time.go#L813 "View Source") ``` func (t Time) Location() *Location ``` Location返回t的地點和時區信息。 ### func (Time) [Zone](https://github.com/golang/go/blob/master/src/time/time.go#L823 "View Source") ``` func (t Time) Zone() (name string, offset int) ``` Zone計算t所在的時區，返回該時區的規范名（如"CET"）和該時區相對于UTC的時間偏移量（單位秒）。 ### func (Time) [IsZero](https://github.com/golang/go/blob/master/src/time/time.go#L243 "View Source") ``` func (t Time) IsZero() bool ``` IsZero報告t是否代表Time零值的時間點，January 1, year 1, 00:00:00 UTC。 ### func (Time) [Local](https://github.com/golang/go/blob/master/src/time/time.go#L796 "View Source") ``` func (t Time) Local() Time ``` Local返回采用本地和本地時區，但指向同一時間點的Time。 ### func (Time) [UTC](https://github.com/golang/go/blob/master/src/time/time.go#L790 "View Source") ``` func (t Time) UTC() Time ``` UTC返回采用UTC和零時區，但指向同一時間點的Time。 ### func (Time) [In](https://github.com/golang/go/blob/master/src/time/time.go#L804 "View Source") ``` func (t Time) In(loc *Location) Time ``` In返回采用loc指定的地點和時區，但指向同一時間點的Time。如果loc為nil會panic。 ### func (Time) [Unix](https://github.com/golang/go/blob/master/src/time/time.go#L830 "View Source") ``` func (t Time) Unix() int64 ``` Unix將t表示為Unix時間，即從時間點January 1, 1970 UTC到時間點t所經過的時間（單位秒）。 ### func (Time) [UnixNano](https://github.com/golang/go/blob/master/src/time/time.go#L838 "View Source") ``` func (t Time) UnixNano() int64 ``` UnixNano將t表示為Unix時間，即從時間點January 1, 1970 UTC到時間點t所經過的時間（單位納秒）。如果納秒為單位的unix時間超出了int64能表示的范圍，結果是未定義的。注意這就意味著Time零值調用UnixNano方法的話，結果是未定義的。 ### func (Time) [Equal](https://github.com/golang/go/blob/master/src/time/time.go#L74 "View Source") ``` func (t Time) Equal(u Time) bool ``` 判斷兩個時間是否相同，會考慮時區的影響，因此不同時區標準的時間也可以正確比較。本方法和用t==u不同，這種方法還會比較地點和時區信息。 ### func (Time) [Before](https://github.com/golang/go/blob/master/src/time/time.go#L65 "View Source") ``` func (t Time) Before(u Time) bool ``` 如果t代表的時間點在u之前，返回真；否則返回假。 ### func (Time) [After](https://github.com/golang/go/blob/master/src/time/time.go#L60 "View Source") ``` func (t Time) After(u Time) bool ``` 如果t代表的時間點在u之后，返回真；否則返回假。 ### func (Time) [Date](https://github.com/golang/go/blob/master/src/time/time.go#L292 "View Source") ``` func (t Time) Date() (year int, month Month, day int) ``` 返回時間點t對應的年、月、日。 ### func (Time) [Clock](https://github.com/golang/go/blob/master/src/time/time.go#L387 "View Source") ``` func (t Time) Clock() (hour, min, sec int) ``` 返回t對應的那一天的時、分、秒。 ### func (Time) [Year](https://github.com/golang/go/blob/master/src/time/time.go#L298 "View Source") ``` func (t Time) Year() int ``` 返回時間點t對應的年份。 ### func (Time) [Month](https://github.com/golang/go/blob/master/src/time/time.go#L304 "View Source") ``` func (t Time) Month() Month ``` 返回時間點t對應那一年的第幾月。 ### func (Time) [ISOWeek](https://github.com/golang/go/blob/master/src/time/time.go#L331 "View Source") ``` func (t Time) ISOWeek() (year, week int) ``` 返回時間點t對應的ISO 9601標準下的年份和星期編號。星期編號范圍[1,53]，1月1號到1月3號可能屬于上一年的最后一周，12月29號到12月31號可能屬于下一年的第一周。 ### func (Time) [YearDay](https://github.com/golang/go/blob/master/src/time/time.go#L424 "View Source") ``` func (t Time) YearDay() int ``` 返回時間點t對應的那一年的第幾天，平年的返回值范圍[1,365]，閏年[1,366]。 ### func (Time) [Day](https://github.com/golang/go/blob/master/src/time/time.go#L310 "View Source") ``` func (t Time) Day() int ``` 返回時間點t對應那一月的第幾日。 ### func (Time) [Weekday](https://github.com/golang/go/blob/master/src/time/time.go#L316 "View Source") ``` func (t Time) Weekday() Weekday ``` 返回時間點t對應的那一周的周幾。 ### func (Time) [Hour](https://github.com/golang/go/blob/master/src/time/time.go#L402 "View Source") ``` func (t Time) Hour() int ``` 返回t對應的那一天的第幾小時，范圍[0, 23]。 ### func (Time) [Minute](https://github.com/golang/go/blob/master/src/time/time.go#L407 "View Source") ``` func (t Time) Minute() int ``` 返回t對應的那一小時的第幾分種，范圍[0, 59]。 ### func (Time) [Second](https://github.com/golang/go/blob/master/src/time/time.go#L412 "View Source") ``` func (t Time) Second() int ``` 返回t對應的那一分鐘的第幾秒，范圍[0, 59]。 ### func (Time) [Nanosecond](https://github.com/golang/go/blob/master/src/time/time.go#L418 "View Source") ``` func (t Time) Nanosecond() int ``` 返回t對應的那一秒內的納秒偏移量，范圍[0, 999999999]。 ### func (Time) [Add](https://github.com/golang/go/blob/master/src/time/time.go#L613 "View Source") ``` func (t Time) Add(d Duration) Time ``` Add返回時間點t+d。 ### func (Time) [AddDate](https://github.com/golang/go/blob/master/src/time/time.go#L658 "View Source") ``` func (t Time) AddDate(years int, months int, days int) Time ``` AddDate返回增加了給出的年份、月份和天數的時間點Time。例如，時間點January 1, 2011調用AddDate(-1, 2, 3)會返回March 4, 2010。 AddDate會將結果規范化，類似Date函數的做法。因此，舉個例子，給時間點October 31添加一個月，會生成時間點December 1。（從時間點November 31規范化而來） ### func (Time) [Sub](https://github.com/golang/go/blob/master/src/time/time.go#L631 "View Source") ``` func (t Time) Sub(u Time) Duration ``` 返回一個時間段t-u。如果結果超出了Duration可以表示的最大值/最小值，將返回最大值/最小值。要獲取時間點t-d（d為Duration），可以使用t.Add(-d)。 ### func (Time) [Round](https://github.com/golang/go/blob/master/src/time/time.go#L1107 "View Source") ``` func (t Time) Round(d Duration) Time ``` 返回距離t最近的時間點，該時間點應該滿足從Time零值到該時間點的時間段能整除d；如果有兩個滿足要求的時間點，距離t相同，會向上舍入；如果d <= 0，會返回t的拷貝。 Example ``` t := time.Date(0, 0, 0, 12, 15, 30, 918273645, time.UTC) round := []time.Duration{ time.Nanosecond, time.Microsecond, time.Millisecond, time.Second, 2 * time.Second, time.Minute, 10 * time.Minute, time.Hour, } for _, d := range round { fmt.Printf("t.Round(%6s) = %s\n", d, t.Round(d).Format("15:04:05.999999999")) } ``` Output: ``` t.Round( 1ns) = 12:15:30.918273645 t.Round( 1us) = 12:15:30.918274 t.Round( 1ms) = 12:15:30.918 t.Round( 1s) = 12:15:31 t.Round( 2s) = 12:15:30 t.Round( 1m0s) = 12:16:00 t.Round( 10m0s) = 12:20:00 t.Round(1h0m0s) = 12:00:00 ``` ### func (Time) [Truncate](https://github.com/golang/go/blob/master/src/time/time.go#L1096 "View Source") ``` func (t Time) Truncate(d Duration) Time ``` 類似Round，但是返回的是最接近但早于t的時間點；如果d <= 0，會返回t的拷貝。 Example ``` t, _ := time.Parse("2006 Jan 02 15:04:05", "2012 Dec 07 12:15:30.918273645") trunc := []time.Duration{ time.Nanosecond, time.Microsecond, time.Millisecond, time.Second, 2 * time.Second, time.Minute, 10 * time.Minute, time.Hour, } for _, d := range trunc { fmt.Printf("t.Truncate(%6s) = %s\n", d, t.Truncate(d).Format("15:04:05.999999999")) } ``` Output: ``` t.Truncate( 1ns) = 12:15:30.918273645 t.Truncate( 1us) = 12:15:30.918273 t.Truncate( 1ms) = 12:15:30.918 t.Truncate( 1s) = 12:15:30 t.Truncate( 2s) = 12:15:30 t.Truncate( 1m0s) = 12:15:00 t.Truncate( 10m0s) = 12:10:00 t.Truncate(1h0m0s) = 12:00:00 ``` ### func (Time) [Format](https://github.com/golang/go/blob/master/src/time/format.go#L414 "View Source") ``` func (t Time) Format(layout string) string ``` Format根據layout指定的格式返回t代表的時間點的格式化文本表示。layout定義了參考時間： ``` Mon Jan 2 15:04:05 -0700 MST 2006 ``` 格式化后的字符串表示，它作為期望輸出的例子。同樣的格式規則會被用于格式化時間。預定義的ANSIC、UnixDate、RFC3339和其他版式描述了參考時間的標準或便捷表示。要獲得更多參考時間的定義和格式，參見本包的ANSIC和其他版式常量。 Example ``` // layout shows by example how the reference time should be represented. const layout = "Jan 2, 2006 at 3:04pm (MST)" t := time.Date(2009, time.November, 10, 15, 0, 0, 0, time.Local) fmt.Println(t.Format(layout)) fmt.Println(t.UTC().Format(layout)) ``` Output: ``` Nov 10, 2009 at 3:00pm (PST) Nov 10, 2009 at 11:00pm (UTC) ``` ### func (Time) [String](https://github.com/golang/go/blob/master/src/time/format.go#L399 "View Source") ``` func (t Time) String() string ``` String返回采用如下格式字符串的格式化時間。 ``` "2006-01-02 15:04:05.999999999 -0700 MST" ``` ### func (Time) [GobEncode](https://github.com/golang/go/blob/master/src/time/time.go#L924 "View Source") ``` func (t Time) GobEncode() ([]byte, error) ``` GobEncode實現了gob.GobEncoder接口。 ### func (\*Time) [GobDecode](https://github.com/golang/go/blob/master/src/time/time.go#L929 "View Source") ``` func (t *Time) GobDecode(data []byte) error ``` GobEncode實現了gob.GobDecoder接口。 ### func (Time) [MarshalBinary](https://github.com/golang/go/blob/master/src/time/time.go#L845 "View Source") ``` func (t Time) MarshalBinary() ([]byte, error) ``` MarshalBinary實現了encoding.BinaryMarshaler接口。 ### func (\*Time) [UnmarshalBinary](https://github.com/golang/go/blob/master/src/time/time.go#L884 "View Source") ``` func (t *Time) UnmarshalBinary(data []byte) error ``` UnmarshalBinary實現了encoding.BinaryUnmarshaler接口。 ### func (Time) [MarshalJSON](https://github.com/golang/go/blob/master/src/time/time.go#L935 "View Source") ``` func (t Time) MarshalJSON() ([]byte, error) ``` MarshalJSON實現了json.Marshaler接口。返回值是用雙引號括起來的采用[RFC 3339](http://tools.ietf.org/html/rfc3339)格式進行格式化的時間表示，如果需要會提供小于秒的精度。 ### func (\*Time) [UnmarshalJSON](https://github.com/golang/go/blob/master/src/time/time.go#L946 "View Source") ``` func (t *Time) UnmarshalJSON(data []byte) (err error) ``` UnmarshalJSON實現了json.Unmarshaler接口。時間被期望是雙引號括起來的[RFC 3339](http://tools.ietf.org/html/rfc3339)格式。 ### func (Time) [MarshalText](https://github.com/golang/go/blob/master/src/time/time.go#L954 "View Source") ``` func (t Time) MarshalText() ([]byte, error) ``` MarshalText實現了encoding.TextMarshaler接口。返回值是采用[RFC 3339](http://tools.ietf.org/html/rfc3339)格式進行格式化的時間表示，如果需要會提供小于秒的精度。 ### func (\*Time) [UnmarshalText](https://github.com/golang/go/blob/master/src/time/time.go#L963 "View Source") ``` func (t *Time) UnmarshalText(data []byte) (err error) ``` UnmarshalText實現了encoding.TextUnmarshaler接口。時間被期望采用[RFC 3339](http://tools.ietf.org/html/rfc3339)格式。 ## type [Duration](https://github.com/golang/go/blob/master/src/time/time.go#L432 "View Source") ``` type Duration int64 ``` Duration類型代表兩個時間點之間經過的時間，以納秒為單位。可表示的最長時間段大約290年。 ``` const ( Nanosecond Duration = 1 Microsecond = 1000 * Nanosecond Millisecond = 1000 * Microsecond Second = 1000 * Millisecond Minute = 60 * Second Hour = 60 * Minute ) ``` 常用的時間段。沒有定義一天或超過一天的單元，以避免夏時制的時區切換的混亂。要將Duration類型值表示為某時間單元的個數，用除法： ``` second := time.Second fmt.Print(int64(second/time.Millisecond)) // prints 1000 ``` 要將整數個某時間單元表示為Duration類型值，用乘法： ``` seconds := 10 fmt.Print(time.Duration(seconds)*time.Second) // prints 10s ``` Example ``` t0 := time.Now() expensiveCall() t1 := time.Now() fmt.Printf("The call took %v to run.\n", t1.Sub(t0)) ``` ### func [ParseDuration](https://github.com/golang/go/blob/master/src/time/format.go#L1158 "View Source") ``` func ParseDuration(s string) (Duration, error) ``` ParseDuration解析一個時間段字符串。一個時間段字符串是一個序列，每個片段包含可選的正負號、十進制數、可選的小數部分和單位后綴，如"300ms"、"-1.5h"、"2h45m"。合法的單位有"ns"、"us" /"μs"、"ms"、"s"、"m"、"h"。 ### func [Since](https://github.com/golang/go/blob/master/src/time/time.go#L646 "View Source") ``` func Since(t Time) Duration ``` Since返回從t到現在經過的時間，等價于time.Now().Sub(t)。 ### func (Duration) [Hours](https://github.com/golang/go/blob/master/src/time/time.go#L606 "View Source") ``` func (d Duration) Hours() float64 ``` Hours將時間段表示為float64類型的小時數。 ### func (Duration) [Minutes](https://github.com/golang/go/blob/master/src/time/time.go#L599 "View Source") ``` func (d Duration) Minutes() float64 ``` Hours將時間段表示為float64類型的分鐘數。 ### func (Duration) [Seconds](https://github.com/golang/go/blob/master/src/time/time.go#L592 "View Source") ``` func (d Duration) Seconds() float64 ``` Hours將時間段表示為float64類型的秒數。 ### func (Duration) [Nanoseconds](https://github.com/golang/go/blob/master/src/time/time.go#L580 "View Source") ``` func (d Duration) Nanoseconds() int64 ``` Hours將時間段表示為int64類型的納秒數，等價于int64(d)。 ### func (Duration) [String](https://github.com/golang/go/blob/master/src/time/time.go#L464 "View Source") ``` func (d Duration) String() string ``` 返回時間段采用"72h3m0.5s"格式的字符串表示。最前面可以有符號，數字+單位為一個單元，開始部分的0值單元會被省略；如果時間段<1s，會使用"ms"、"us"、"ns"來保證第一個單元的數字不是0；如果時間段為0，會返回"0"。 ## type [Timer](https://github.com/golang/go/blob/master/src/time/sleep.go#L45 "View Source") ``` type Timer struct { C <-chan Time // 內含隱藏或非導出字段 } ``` Timer類型代表單次時間事件。當Timer到期時，當時的時間會被發送給C，除非Timer是被AfterFunc函數創建的。 ### func [NewTimer](https://github.com/golang/go/blob/master/src/time/sleep.go#L61 "View Source") ``` func NewTimer(d Duration) *Timer ``` NewTimer創建一個Timer，它會在最少過去時間段d后到期，向其自身的C字段發送當時的時間。 ### func [AfterFunc](https://github.com/golang/go/blob/master/src/time/sleep.go#L108 "View Source") ``` func AfterFunc(d Duration, f func()) *Timer ``` AfterFunc另起一個go程等待時間段d過去，然后調用f。它返回一個Timer，可以通過調用其Stop方法來取消等待和對f的調用。 ### func (\*Timer) [Reset](https://github.com/golang/go/blob/master/src/time/sleep.go#L78 "View Source") ``` func (t *Timer) Reset(d Duration) bool ``` Reset使t重新開始計時，（本方法返回后再）等待時間段d過去后到期。如果調用時t還在等待中會返回真；如果t已經到期或者被停止了會返回假。 ### func (\*Timer) [Stop](https://github.com/golang/go/blob/master/src/time/sleep.go#L55 "View Source") ``` func (t *Timer) Stop() bool ``` Stop停止Timer的執行。如果停止了t會返回真；如果t已經被停止或者過期了會返回假。Stop不會關閉通道t.C，以避免從該通道的讀取不正確的成功。 ## type [Ticker](https://github.com/golang/go/blob/master/src/time/tick.go#L11 "View Source") ``` type Ticker struct { C <-chan Time // 周期性傳遞時間信息的通道 // 內含隱藏或非導出字段 } ``` Ticker保管一個通道，并每隔一段時間向其傳遞"tick"。 ### func [NewTicker](https://github.com/golang/go/blob/master/src/time/tick.go#L21 "View Source") ``` func NewTicker(d Duration) *Ticker ``` NewTicker返回一個新的Ticker，該Ticker包含一個通道字段，并會每隔時間段d就向該通道發送當時的時間。它會調整時間間隔或者丟棄tick信息以適應反應慢的接收者。如果d<=0會panic。關閉該Ticker可以釋放相關資源。 ### func (\*Ticker) [Stop](https://github.com/golang/go/blob/master/src/time/tick.go#L45 "View Source") ``` func (t *Ticker) Stop() ``` Stop關閉一個Ticker。在關閉后，將不會發送更多的tick信息。Stop不會關閉通道t.C，以避免從該通道的讀取不正確的成功。 ## func [Sleep](https://github.com/golang/go/blob/master/src/time/sleep.go#L9 "View Source") ``` func Sleep(d Duration) ``` Sleep阻塞當前go程至少d代表的時間段。d<=0時，Sleep會立刻返回。 Example ``` time.Sleep(100 * time.Millisecond) ``` ## func [After](https://github.com/golang/go/blob/master/src/time/sleep.go#L101 "View Source") ``` func After(d Duration) <-chan Time ``` After會在另一線程經過時間段d后向返回值發送當時的時間。等價于NewTimer(d).C。 Example ``` select { case m := <-c: handle(m) case <-time.After(5 * time.Minute): fmt.Println("timed out") } ``` ## func [Tick](https://github.com/golang/go/blob/master/src/time/tick.go#L51 "View Source") ``` func Tick(d Duration) <-chan Time ``` Tick是NewTicker的封裝，只提供對Ticker的通道的訪問。如果不需要關閉Ticker，本函數就很方便。 Example ``` c := time.Tick(1 * time.Minute) for now := range c { fmt.Printf("%v %s\n", now, statusUpdate()) } ```