Package time provides functionality for measuring and displaying time. The calendrical calculations always assume a Gregorian calendar, with no leap seconds.
Time Type
Represents an instant in time with nanosecond precision. Programs should typically store and pass Time values, not pointers.type Time struct {
// contains filtered or unexported fields
}
Getting Current Time
Returns the current local time.now := time.Now()
fmt.Println("Current time:", now)
Date
func Date(year int, month Month, day, hour, min, sec, nsec int, loc *Location) Time
Returns the Time corresponding to the specified date and time in the given location.t := time.Date(2024, time.March, 15, 14, 30, 0, 0, time.UTC)
fmt.Println(t) // 2024-03-15 14:30:00 +0000 UTC
Unix
func Unix(sec int64, nsec int64) Time
Returns the local Time corresponding to the given Unix time (seconds since January 1, 1970 UTC).t := time.Unix(1609459200, 0) // 2021-01-01 00:00:00 UTC
Time Methods
Returns the year in which t occurs.
Time.Month
func (t Time) Month() Month
Returns the month of the year specified by t.
Returns the day of the month specified by t.
Returns the hour within the day specified by t, in the range [0, 23].
Time.Minute
func (t Time) Minute() int
Returns the minute offset within the hour specified by t, in the range [0, 59].
Time.Second
func (t Time) Second() int
Returns the second offset within the minute specified by t, in the range [0, 59].
Time.Unix
func (t Time) Unix() int64
Returns t as a Unix time, the number of seconds elapsed since January 1, 1970 UTC.timestamp := time.Now().Unix()
fmt.Println("Unix timestamp:", timestamp)
Time Comparison
Time.Before
func (t Time) Before(u Time) bool
Reports whether the time instant t is before u.t1 := time.Now()
time.Sleep(time.Second)
t2 := time.Now()
fmt.Println(t1.Before(t2)) // true
Time.After
func (t Time) After(u Time) bool
Reports whether the time instant t is after u.fmt.Println(t2.After(t1)) // true
Time.Equal
func (t Time) Equal(u Time) bool
Reports whether t and u represent the same time instant.if t1.Equal(t2) {
fmt.Println("Same time")
}
Time.Compare
func (t Time) Compare(u Time) int
Compares the time instant t with u. Returns -1 if t is before u, 0 if they’re the same, +1 if t is after u.
Duration Type
Represents the elapsed time between two instants as an int64 nanosecond count.Common duration constants:const (
Nanosecond Duration = 1
Microsecond = 1000 * Nanosecond
Millisecond = 1000 * Microsecond
Second = 1000 * Millisecond
Minute = 60 * Second
Hour = 60 * Minute
)
ParseDuration
func ParseDuration(s string) (Duration, error)
Parses a duration string. Valid time units are “ns”, “us”, “ms”, “s”, “m”, “h”.d, err := time.ParseDuration("2h45m")
fmt.Println(d) // 2h45m0s
d2, _ := time.ParseDuration("300ms")
fmt.Println(d2) // 300ms
Time Arithmetic
Time.Add
func (t Time) Add(d Duration) Time
Returns the time t + d.now := time.Now()
later := now.Add(2 * time.Hour)
fmt.Println("2 hours from now:", later)
Time.Sub
func (t Time) Sub(u Time) Duration
Returns the duration t - u.start := time.Now()
// ... do work ...
duration := time.Since(start)
fmt.Println("Elapsed:", duration)
Since
func Since(t Time) Duration
Returns the time elapsed since t. Shorthand for time.Now().Sub(t).start := time.Now()
time.Sleep(100 * time.Millisecond)
fmt.Println("Elapsed:", time.Since(start))
Until
func Until(t Time) Duration
Returns the duration until t. Shorthand for t.Sub(time.Now()).deadline := time.Now().Add(5 * time.Second)
fmt.Println("Time until deadline:", time.Until(deadline))
Time.AddDate
func (t Time) AddDate(years int, months int, days int) Time
Returns the time corresponding to adding the given number of years, months, and days to t.now := time.Now()
nextYear := now.AddDate(1, 0, 0)
nextMonth := now.AddDate(0, 1, 0)
tomorrow := now.AddDate(0, 0, 1)
Time.Format
func (t Time) Format(layout string) string
Returns a textual representation of the time value formatted according to layout. The layout is defined by showing how the reference time would be displayed.Reference time: Mon Jan 2 15:04:05 MST 2006now := time.Now()
fmt.Println(now.Format("2006-01-02")) // 2024-03-15
fmt.Println(now.Format("Jan 02, 2006")) // Mar 15, 2024
fmt.Println(now.Format("15:04:05")) // 14:30:45
fmt.Println(now.Format("2006-01-02 15:04:05 MST")) // 2024-03-15 14:30:45 UTC
Parse
func Parse(layout, value string) (Time, error)
Parses a formatted string and returns the time value it represents.t, err := time.Parse("2006-01-02", "2024-03-15")
if err != nil {
log.Fatal(err)
}
fmt.Println(t)
Common Layout Constants
const (
Layout = "01/02 03:04:05PM '06 -0700" // The reference time
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"
RFC850 = "Monday, 02-Jan-06 15:04:05 MST"
RFC1123 = "Mon, 02 Jan 2006 15:04:05 MST"
RFC3339 = "2006-01-02T15:04:05Z07:00"
Kitchen = "3:04PM"
DateTime = "2006-01-02 15:04:05"
DateOnly = "2006-01-02"
TimeOnly = "15:04:05"
)
Timers and Tickers
Pauses the current goroutine for at least the duration d.fmt.Println("Waiting...")
time.Sleep(2 * time.Second)
fmt.Println("Done!")
After
func After(d Duration) <-chan Time
Waits for the duration to elapse and then sends the current time on the returned channel.select {
case <-time.After(5 * time.Second):
fmt.Println("Timeout!")
}
NewTimer
func NewTimer(d Duration) *Timer
Creates a new Timer that will send the current time on its channel after at least duration d.timer := time.NewTimer(2 * time.Second)
<-timer.C
fmt.Println("Timer expired")
NewTicker
func NewTicker(d Duration) *Ticker
Returns a new Ticker containing a channel that will send the time with a period specified by the duration argument.ticker := time.NewTicker(1 * time.Second)
defer ticker.Stop()
for t := range ticker.C {
fmt.Println("Tick at", t)
}
Locations and Timezones
Time.In
func (t Time) In(loc *Location) Time
Returns t with the location set to loc.now := time.Now()
tokyo, _ := time.LoadLocation("Asia/Tokyo")
tokyoTime := now.In(tokyo)
fmt.Println("Tokyo time:", tokyoTime)
LoadLocation
func LoadLocation(name string) (*Location, error)
Returns the Location with the given name.loc, err := time.LoadLocation("America/New_York")
if err != nil {
log.Fatal(err)
}
Represents UTC (Universal Coordinated Time).utcTime := time.Now().UTC()
Represents the system’s local time zone.localTime := time.Now().Local()
Examples
Measuring Elapsed Time
package main
import (
"fmt"
"time"
)
func main() {
start := time.Now()
// Simulate work
time.Sleep(2 * time.Second)
elapsed := time.Since(start)
fmt.Printf("Operation took %s\n", elapsed)
}
package main
import (
"fmt"
"time"
)
func main() {
now := time.Now()
// Various formats
fmt.Println(now.Format(time.RFC3339)) // 2024-03-15T14:30:45Z
fmt.Println(now.Format("2006-01-02")) // 2024-03-15
fmt.Println(now.Format("January 2, 2006")) // March 15, 2024
fmt.Println(now.Format("3:04 PM")) // 2:30 PM
fmt.Println(now.Format("Mon, 02 Jan 2006")) // Fri, 15 Mar 2024
}
Using Timers
package main
import (
"fmt"
"time"
)
func main() {
// One-shot timer
timer := time.NewTimer(2 * time.Second)
fmt.Println("Waiting...")
<-timer.C
fmt.Println("Timer expired!")
// Repeating ticker
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()
count := 0
for t := range ticker.C {
count++
fmt.Printf("Tick %d at %v\n", count, t)
if count >= 5 {
break
}
}
}
Timeout Pattern
package main
import (
"fmt"
"time"
)
func doWork() <-chan string {
ch := make(chan string)
go func() {
time.Sleep(2 * time.Second)
ch <- "Work completed"
}()
return ch
}
func main() {
select {
case result := <-doWork():
fmt.Println(result)
case <-time.After(1 * time.Second):
fmt.Println("Timeout!")
}
}