SyntaxPilot
Courses/Go Programming/Lesson 36
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Go Programming · Lesson 36 of 89

Working with time

time.Timetime.Nowtime.Durationduration constantsarithmetic (Add, Sub, Since, Until)formatting with the reference layout (2006-01-02 15:04:05)time.Parsetime zones and time.LoadLocationUTCmonotonic clockcomparing times (Before, After, Equal)Unix timestamps

These are the notes for Go episode 36. Raju promises every order in 30 minutes. With the hour and minute stored as plain ints, an order at 23:50 is due at "24:20", and a trip from 22:40 to 01:10 lasts "-1290 minutes". Clocks wrap at midnight, months have different lengths, and every country has its own clock, so you invent instants and durations: Go's time.Time and time.Duration. You do clock maths with Add, Sub, Since and Until, meet the int × Duration compile error and the time.Sleep(2) bug, learn Go's unusual reference-time layouts (2006-01-02 15:04:05) for Format and time.Parse, handle time zones with time.LoadLocation, In and UTC, compare times with Equal, Before and After (never ==), and finish with the monotonic clock and Unix timestamps.

Every program here runs as-is in the SyntaxPilot compiler (language: Go) with go run main.go. All outputs and errors are from real runs (Go 1.24.7, linux/amd64). Programs that read the current time print different values on every run, so they print checks (true/false) instead of the time itself.

Facts and sources

From the standard library documentation shipped with Go 1.24.7 (go doc time):

  • The layout constants are written with the reference time 01/02 03:04:05PM '06 -0700, "The reference time, in numerical order." In words: Monday, January 2, 15:04:05, 2006, zone MST (-0700). Ready-made layouts include time.RFC3339 = "2006-01-02T15:04:05Z07:00", time.Kitchen = "3:04PM" and time.DateOnly = "2006-01-02".
  • "Note that the Go == operator compares not just the time instant but also the Location and the monotonic clock reading. ... In general, prefer t.Equal(u) to t == u."
  • A time.Time "can contain an optional reading of the current process's monotonic clock". "Operating systems provide both a wall clock, which is subject to changes for clock synchronization, and a monotonic clock, which is not." t.Round(0) strips the monotonic reading.
  • time.Unix(sec, nsec) "returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC."
  • "A Duration represents the elapsed time between two instants as an int64 nanosecond count."
  • time.Parse: "In the absence of a time zone indicator, Parse returns a time in UTC."

The problem: clock maths with ints

package main

import "fmt"

func main() {
    // order placed at 23:50, delivery promised in 30 minutes
    hour, minute := 23, 50
    minute += 30
    if minute >= 60 {
        hour, minute = hour+1, minute-60
    }
    fmt.Printf("deliver by %02d:%02d\n", hour, minute)

    // and how long from 22:40 to 01:10?
    fmt.Println("minutes:", (1*60+10)-(22*60+40))
}

Output:

deliver by 24:20
minutes: -1290
  • 24:20 doesn't exist: after 23:59 comes 00:00 of the next day.
  • -1290 minutes: the trip crossed midnight, so subtracting clock readings goes negative.
  • Patching with more ifs never ends: month lengths (28 to 31 days), leap years, time zones, daylight saving time. We need types that understand the calendar.

Instants, durations and zones: the train timetable

At the railway station In Go Meaning
"Departs 23:50, 6 Nov" time.Time an instant: one point in time (date + clock + zone)
"Journey: 2 h 30 min" time.Duration a length of time, with no date
"Clock in Delhi vs London" *time.Location a time zone: how a place shows an instant

Instant + duration = a new instant (Add). Instant − instant = a duration (Sub).

time.Time and time.Date

package main

import (
    "fmt"
    "time"
)

func main() {
    ist, _ := time.LoadLocation("Asia/Kolkata")
    placed := time.Date(2026, time.November, 6, 23, 50, 0, 0, ist)
    deliver := placed.Add(30 * time.Minute)
    fmt.Println("placed: ", placed)
    fmt.Println("deliver:", deliver)

    start := time.Date(2026, 11, 6, 22, 40, 0, 0, ist)
    end := time.Date(2026, 11, 7, 1, 10, 0, 0, ist)
    fmt.Println("took:", end.Sub(start))
    fmt.Println(deliver.Weekday(), deliver.YearDay(), deliver.Month())
}

Output:

placed:  2026-11-06 23:50:00 +0530 IST
deliver: 2026-11-07 00:20:00 +0530 IST
took: 2h30m0s
Saturday 311 November
  • time.LoadLocation(name) finds a time zone in the IANA time zone database (also called tzdata or the Olson database), the list of the world's zones that operating systems use. Names look like Area/City: Asia/Kolkata, America/New_York, Europe/London.
  • time.Date(year, month, day, hour, min, sec, nsec, loc) builds an instant. The month can be a constant (time.November) or a number (11). Out-of-range values roll over: day 32 of October is 1 November.
  • t.Add(d) adds a duration; the date rolls over by itself. t.Sub(u) returns the duration between two instants.
  • t.AddDate(years, months, days) adds calendar units (e.g. "same date next month").
  • A Time knows its parts: Year(), Month(), Day(), Hour(), Weekday(), YearDay() (day of the year, 1 to 366).
  • time.Now() returns the current instant in the computer's local zone.
  • IST is India Standard Time, +0530: five and a half hours ahead of UTC.

time.Duration

package main

import (
    "fmt"
    "time"
)

func main() {
    d := 90 * time.Minute // a Duration is an int64 of nanoseconds
    fmt.Println(d, int64(d))
    fmt.Println(d.Hours(), d.Minutes())
    fmt.Println(1500*time.Millisecond, 2*time.Hour+15*time.Second)

    p, err := time.ParseDuration("1h45m")
    fmt.Println(p, err)
}

Output:

1h30m0s 5400000000000
1.5 90
1.5s 2h0m15s
1h45m0s <nil>
  • A Duration is a defined type (episode 19) whose underlying type is int64, counting nanoseconds (billionths of a second). So 90 * time.Minute is 5,400,000,000,000.
  • Constants: time.Nanosecond, time.Microsecond, time.Millisecond, time.Second, time.Minute, time.Hour. There's no Day: days can be 23 or 25 hours long when clocks change for daylight saving time.
  • Durations print readably (1h30m0s), and convert with Hours(), Minutes(), Seconds() (as float64) and Milliseconds() (as int64).
  • time.ParseDuration("1h45m") reads text with the units ns, us (or µs), ms, s, m, h.

When the number is an int variable, the multiplication doesn't compile:

package main

import (
    "fmt"
    "time"
)

func main() {
    delay := 30 // minutes, read from a settings file
    fmt.Println(delay * time.Minute)
}

Output:

# command-line-arguments
./main.go:10:17: invalid operation: delay * time.Minute (mismatched types int and time.Duration)
  • Go never converts between types silently (episode 4). 90 * time.Minute worked only because 90 is an untyped constant (episode 5), which takes the type it needs.
  • Fix: time.Duration(delay) * time.Minute.

Since, Until and Sleep

package main

import (
    "fmt"
    "time"
)

func main() {
    delay := 30
    fmt.Println(time.Duration(delay) * time.Minute) // convert first

    start := time.Now()
    time.Sleep(2) // BUG: 2 nanoseconds, not 2 seconds!
    fmt.Println("slept 2?", time.Since(start) < time.Millisecond)

    start = time.Now()
    time.Sleep(200 * time.Millisecond)
    el := time.Since(start) // same as time.Now().Sub(start)
    fmt.Println("slept ~200ms:", el.Round(100*time.Millisecond))

    deadline := start.Add(time.Hour)
    fmt.Println("left:", time.Until(deadline).Round(time.Minute))
}

Output:

30m0s
slept 2? true
slept ~200ms: 200ms
left: 1h0m0s
  • time.Sleep(d) pauses the current goroutine for d. time.Sleep(2) is 2 nanoseconds: always write a unit (2 * time.Second).
  • time.Since(t) = time.Now().Sub(t): how much time has passed. Great for measuring how long code takes.
  • time.Until(t) = t.Sub(time.Now()): how much is left before a deadline.
  • d.Round(m) and d.Truncate(m) tidy a duration to a multiple of m.

Formatting: the reference time

Other languages use letter codes like DD/MM/YYYY. Go doesn't:

package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Date(2026, 11, 6, 23, 50, 7, 0, time.UTC)
    fmt.Println(t.Format("DD/MM/YYYY hh:mm"))  // other languages' style
    fmt.Println(t.Format("2006-02-01"))        // month and day swapped
}

Output:

DD/MM/YYYY hh:mm
2026-06-11
  • The letters were printed as they are. 2006-02-01 put the day where the month goes: 6 November became 2026-06-11, June 11th. No error: just a wrong date.

Go's rule: write one special moment, the reference time, exactly the way you want your output to look.

Mon Jan 2 15:04:05 MST 2006
 │   │  │  │  │  │   │    └─ year       2006 (or 06)
 │   │  │  │  │  │   └────── zone       MST, -0700, Z07:00
 │   │  │  │  │  └────────── second     05
 │   │  │  │  └───────────── minute     04
 │   │  │  └──────────────── hour       15 (24-hour) or 3 / 03 (12-hour) + PM
 │   │  └─────────────────── day        2 or 02 (_2 = space-padded)
 │   └────────────────────── month      Jan, January, 1 or 01
 └────────────────────────── weekday    Mon or Monday

Why those numbers? In order they count 1 2 3 4 5 6 7: month 01, day 02, hour 03 PM (15), minute 04, second 05, year (20)06, zone -0700.

package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Date(2026, 11, 6, 23, 50, 7, 0, time.UTC)
    // the reference time: Mon Jan 2 15:04:05 MST 2006
    fmt.Println(t.Format("02/01/2006 15:04"))
    fmt.Println(t.Format("Mon, 2 Jan 2006 3:04 PM"))
    fmt.Println(t.Format("2006-01-02T15:04:05Z07:00"))
    fmt.Println(t.Format(time.RFC3339))
    fmt.Println(t.Format(time.Kitchen), t.Format(time.DateOnly))
}

Output:

06/11/2026 23:50
Fri, 6 Nov 2026 11:50 PM
2026-11-06T23:50:07Z
2026-11-06T23:50:07Z
11:50PM 2026-11-06
Want Layout Example output
Indian date 02/01/2006 06/11/2026
ISO date 2006-01-02 (time.DateOnly) 2026-11-06
24-hour clock 15:04:05 (time.TimeOnly) 23:50:07
12-hour clock 3:04 PM 11:50 PM
weekday and month names Mon, 2 Jan 2006 Fri, 6 Nov 2026
machines, JSON, APIs time.RFC3339 2026-11-06T23:50:07Z
  • RFC 3339 is an internet standard for dates and times; a trailing Z means UTC. It's what json.Marshal (episode 35) uses for a time.Time.
  • .000 adds milliseconds: 15:04:05.000.

time.Parse and time.ParseInLocation

package main

import (
    "fmt"
    "time"
)

func main() {
    t, err := time.Parse("02/01/2006 15:04", "06/11/2026 23:50")
    fmt.Println(t, err)

    _, err = time.Parse(time.DateOnly, "2026-13-01")
    fmt.Println("err:", err)
    _, err = time.Parse(time.DateOnly, "6 Nov 2026")
    fmt.Println("err:", err)

    ist, _ := time.LoadLocation("Asia/Kolkata")
    t2, _ := time.ParseInLocation("02/01/2006 15:04", "06/11/2026 23:50", ist)
    fmt.Println(t2)
    fmt.Println("same instant?", t.Equal(t2))
}

Output:

2026-11-06 23:50:00 +0000 UTC <nil>
err: parsing time "2026-13-01": month out of range
err: parsing time "6 Nov 2026" as "2006-01-02": cannot parse "6 Nov 2026" as "2006"
2026-11-06 23:50:00 +0530 IST
same instant? false
  • time.Parse(layout, text) uses the same layouts as Format.
  • Errors are precise: month out of range; cannot parse "6 Nov 2026" as "2006" (the text doesn't match the layout).
  • With no zone in the text, Parse assumes UTC. Text typed by a person in India usually means India time: use time.ParseInLocation(layout, text, loc).
  • The two results show the same clock time but are different instants, 5 hours 30 minutes apart, so Equal is false.

Time zones and UTC

package main

import (
    "fmt"
    "time"
)

func main() {
    ist, _ := time.LoadLocation("Asia/Kolkata")
    ny, _ := time.LoadLocation("America/New_York")
    call := time.Date(2026, 11, 6, 20, 30, 0, 0, ist) // 8:30 PM in India

    fmt.Println("India:   ", call)
    fmt.Println("New York:", call.In(ny))
    fmt.Println("UTC:     ", call.UTC())

    _, err := time.LoadLocation("India/Delhi")
    fmt.Println("err:", err)
}

Output:

India:    2026-11-06 20:30:00 +0530 IST
New York: 2026-11-06 10:00:00 -0500 EST
UTC:      2026-11-06 15:00:00 +0000 UTC
err: unknown time zone India/Delhi
  • UTC (Coordinated Universal Time) is the world's reference clock; every zone is an offset from it (+0530, -0500).
  • t.In(loc) shows the same instant in another zone; t.UTC() and t.Local() are shortcuts.
  • Daylight saving time (DST): some places move their clocks one hour in summer. New York is -0400 (EDT) in summer and -0500 (EST) in winter; the database knows the dates. India doesn't use DST.
  • Unknown names fail: unknown time zone India/Delhi. India's IANA name is Asia/Kolkata.
  • Store and send times in UTC; convert to local time only to show people.
  • If a computer has no zone database installed, import _ "time/tzdata" builds a copy into your program.

Comparing times

package main

import (
    "fmt"
    "time"
)

func main() {
    ist, _ := time.LoadLocation("Asia/Kolkata")
    a := time.Date(2026, 11, 6, 20, 30, 0, 0, ist)
    b := a.UTC() // the same instant, shown in UTC

    fmt.Println("a == b:   ", a == b) // compares the struct, zone too
    fmt.Println("a.Equal(b):", a.Equal(b))
    later := a.Add(time.Minute)
    fmt.Println(a.Before(later), a.After(later), later.Compare(a))

    var zero time.Time
    fmt.Println(zero, zero.IsZero())
}

Output:

a == b:    false
a.Equal(b): true
true false 1
0001-01-01 00:00:00 +0000 UTC true
  • == compares the whole Time struct, including the location and the monotonic reading, so the same instant in two zones is "not equal".
  • a.Equal(b) compares instants. a.Before(b), a.After(b), and a.Compare(b) (−1, 0 or +1; Go 1.20) do ordering.
  • The zero value of time.Time is 0001-01-01 00:00:00 UTC; t.IsZero() checks for "never set".
  • Don't use Time as a map key unless you've normalised it (e.g. t.UTC().Round(0)), for the same reason.

The monotonic clock

package main

import (
    "fmt"
    "strings"
    "time"
)

func main() {
    now := time.Now()
    fmt.Println(now.Location(), now.Year() >= 2026)
    fmt.Println(strings.Contains(now.String(), "m=+")) // monotonic reading
    fmt.Println(strings.Contains(now.Round(0).String(), "m=+"))

    start := time.Now()
    for i := 0; i < 1_000_000; i++ {
    }
    fmt.Println("measured:", time.Since(start) > 0)
}

Output:

Local true
true
false
measured: true
  • The wall clock tells the time of day, but it can jump: when the system corrects itself over the internet (NTP, Network Time Protocol), when someone changes it, or at a leap second.
  • The monotonic clock only moves forward, from some arbitrary starting point. It can't tell the time of day, but it's right for measuring.
  • time.Now() records both. Its String() shows the monotonic reading as m=+0.000012345; t.Round(0) removes it.
  • Sub, Since, Until, Before and After use the monotonic readings when both times have one, so measured durations never go negative even if the wall clock jumps.

Unix timestamps

package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Date(2026, 11, 6, 18, 20, 0, 0, time.UTC)
    fmt.Println(t.Unix())      // seconds since 1 Jan 1970 UTC
    fmt.Println(t.UnixMilli()) // milliseconds, as JavaScript uses

    back := time.Unix(1793989200, 0).UTC()
    fmt.Println(back)
    fmt.Println(time.Unix(0, 0).UTC())
    fmt.Println(time.UnixMilli(1793989200000).UTC().Format(time.RFC3339))
}

Output:

1793989200
1793989200000
2026-11-06 18:20:00 +0000 UTC
1970-01-01 00:00:00 +0000 UTC
2026-11-06T18:20:00Z
  • A Unix timestamp is the number of seconds since 1 January 1970, 00:00 UTC, the Unix epoch. It has no zone, so it's easy to store, sort and compare.
  • t.Unix() gives seconds, t.UnixMilli() milliseconds (what JavaScript's Date.now() uses), t.UnixNano() nanoseconds.
  • time.Unix(sec, nsec) and time.UnixMilli(ms) go back; they return local time, so add .UTC() to see UTC.

Mini project: delivery tracker

  1. Parse the order time 06/11/2026 23:50 in Asia/Kolkata with ParseInLocation.
  2. Deliver-by = placed + 30 minutes; print it as Mon 3:04 PM.
  3. Was the delivery at 07/11/2026 00:34 late? By how long?
  4. Save the deliver-by time as RFC 3339 in UTC, and show it in New York time.
Solution
package main

import (
    "fmt"
    "time"
)

const layout = "02/01/2006 15:04"

func main() {
    ist, err := time.LoadLocation("Asia/Kolkata")
    if err != nil {
        fmt.Println("zone:", err)
        return
    }
    ny, _ := time.LoadLocation("America/New_York")

    placed, err := time.ParseInLocation(layout, "06/11/2026 23:50", ist)
    if err != nil {
        fmt.Println("parse:", err)
        return
    }
    promise := 30 * time.Minute
    deliverBy := placed.Add(promise)
    fmt.Println("deliver by:", deliverBy.Format("Mon 3:04 PM"))

    delivered, _ := time.ParseInLocation(layout, "07/11/2026 00:34", ist)
    if delivered.After(deliverBy) {
        fmt.Println("late by", delivered.Sub(deliverBy))
    } else {
        fmt.Println("on time, with", deliverBy.Sub(delivered), "to spare")
    }

    fmt.Println("saved:", deliverBy.UTC().Format(time.RFC3339))
    fmt.Println("New York:", deliverBy.In(ny).Format("Mon 3:04 PM MST"))
}

Output:

deliver by: Sat 12:20 AM
late by 14m0s
saved: 2026-11-06T18:50:00Z
New York: Fri 1:50 PM EST

Common mistakes (and the real messages)

Mistake Real message / result Why Fix
hour and minute as ints + 30 deliver by 24:20 clocks and dates wrap time.Time + Add
subtracting clock readings across midnight -1290 minutes the date changed end.Sub(start)
delay * time.Minute with an int invalid operation: delay * time.Minute (mismatched types int and time.Duration) no implicit conversion time.Duration(delay) * time.Minute
time.Sleep(2) sleeps 2 nanoseconds Duration counts ns time.Sleep(2 * time.Second)
t.Format("DD/MM/YYYY") prints DD/MM/YYYY Go uses the reference time t.Format("02/01/2006")
"2006-02-01" 2026-06-11 for 6 November month and day swapped "2006-01-02"
time.Parse on local input the result is in UTC no zone in the text time.ParseInLocation
a month of 13 parsing time "2026-13-01": month out of range invalid date validate the input
time.LoadLocation("India/Delhi") unknown time zone India/Delhi not an IANA name "Asia/Kolkata"
a == b for times false for the same instant == also compares the zone a.Equal(b)
ignoring LoadLocation's error nil-pointer surprises later no zone database check the error; import _ "time/tzdata"

Practice

  1. (Homework) Build the delivery tracker (solution: the mini project).
  2. (Homework) Print today in three layouts.
  3. (Homework) Show one meeting time in three time zones.
  4. (Homework) Time a loop with time.Since.
  5. How many days are there from 6 November 2026 to 26 January 2027?
Solution 2
package main

import (
    "fmt"
    "time"
)

func main() {
    t := time.Now()
    layouts := []string{"02/01/2006", "Monday, 2 January 2006", time.RFC3339}
    for _, l := range layouts {
        _, err := time.Parse(l, t.Format(l)) // format, then parse back
        fmt.Printf("%-24q round-trips: %v\n", l, err == nil)
    }
}

Output:

"02/01/2006"             round-trips: true
"Monday, 2 January 2006" round-trips: true
"2006-01-02T15:04:05Z07:00" round-trips: true

(It prints a check rather than today's date so the output is the same on every run; replace the Printf with fmt.Println(t.Format(l)) to see the dates.)

Solution 3
package main

import (
    "fmt"
    "time"
)

func main() {
    ist, _ := time.LoadLocation("Asia/Kolkata")
    meet := time.Date(2026, 11, 10, 19, 0, 0, 0, ist)
    for _, name := range []string{"Asia/Kolkata", "Europe/London", "Asia/Tokyo"} {
        loc, err := time.LoadLocation(name)
        if err != nil {
            fmt.Println(err)
            continue
        }
        fmt.Printf("%-14s %s\n", name, meet.In(loc).Format("Mon 2 Jan 15:04 MST"))
    }
}

Output:

Asia/Kolkata   Tue 10 Nov 19:00 IST
Europe/London  Tue 10 Nov 13:30 GMT
Asia/Tokyo     Tue 10 Nov 22:30 JST
Solution 4
package main

import (
    "fmt"
    "time"
)

func main() {
    start := time.Now()
    sum := 0
    for i := 0; i < 10_000_000; i++ {
        sum += i
    }
    took := time.Since(start)
    fmt.Println("sum:", sum)
    fmt.Println("took less than 1s:", took < time.Second)
}

Output:

sum: 49999995000000
took less than 1s: true
Solution 5
package main

import (
    "fmt"
    "time"
)

func main() {
    a := time.Date(2026, 11, 6, 0, 0, 0, 0, time.UTC)
    b := time.Date(2027, 1, 26, 0, 0, 0, 0, time.UTC)
    fmt.Println(b.Sub(a).Hours()/24, "days")
}

Output:

81 days

Using UTC avoids a 23- or 25-hour day where clocks change.

Quick quiz

1. What does this print? (From the video.)

t := time.Date(2026, 1, 31, 9, 0, 0, 0,
    time.UTC)
later := t.Add(48 * time.Hour)
fmt.Println(later.Format("02 Jan"))

A. 02 Feb · B. 33 Jan · C. 01 Feb · D. 31 Jan

Answer

A. 48 hours after 31 January is 2 February; 02 is the day and Jan the short month name. Real output: 02 Feb.

2. What layout prints 23:50 for 11:50 PM?

Answer

"15:04".

3. a is 20:30 IST and b := a.UTC(). What are a == b and a.Equal(b)?

Answer

false and true: same instant, different location.

4. What is time.Duration(1500) * time.Millisecond when printed?

Answer

1.5s.

Interview questions

  1. How does Go format dates? With layouts written as the reference time Mon Jan 2 15:04:05 MST 2006 (1 2 3 4 5 6 7), not letter codes.
  2. What is a time.Duration? An int64 count of nanoseconds, with constants like time.Second and methods like Hours().
  3. Why prefer Equal to ==? == also compares the location and the monotonic reading; Equal compares only the instant.
  4. What does time.Parse do with no zone in the input? It returns UTC. Use ParseInLocation for local input.
  5. What is the monotonic clock and why does Go use it? A clock that only moves forward; time.Now records it so Sub/Since measure correctly even if the wall clock is adjusted.
  6. How should a backend store times? In UTC (or as Unix timestamps), converting to the user's zone only for display.
  7. Why is there no time.Day constant? A calendar day isn't always 24 hours (daylight saving changes); use AddDate for calendar maths.
  8. What's a Unix timestamp? Seconds since 1970-01-01 00:00 UTC; t.Unix(), time.Unix(sec, 0).
  9. How do you make time zones work on a machine without tzdata? import _ "time/tzdata" embeds the database in the binary.

Glossary

Term Meaning Example
time package Go's package for instants, durations, zones and formatting import "time"
Instant one point in time 6 Nov 2026, 23:50 IST
time.Time Go's type for an instant (date, clock, zone) time.Now()
time.Now the current instant, in the local zone start := time.Now()
time.Date build an instant from its parts time.Date(2026, 11, 6, 23, 50, 0, 0, ist)
Duration a length of time between two instants 2 h 30 min
time.Duration int64 nanoseconds 90 * time.Minute
Nanosecond one billionth of a second time.Nanosecond
Duration constants Nanosecond … Hour time.Second
ParseDuration read text like 1h45m time.ParseDuration("1h45m")
Untyped constant a constant that takes the type it needs (episode 5) 90 in 90 * time.Minute
Add / Sub instant + duration / instant − instant t.Add(30*time.Minute)
AddDate add years, months, days t.AddDate(0, 1, 0)
time.Since / time.Until time passed since / left until an instant time.Since(start)
time.Sleep pause for a duration time.Sleep(2 * time.Second)
Layout a pattern written as the reference time "02/01/2006 15:04"
Reference time Mon Jan 2 15:04:05 MST 2006 (1 2 3 4 5 6 7) used by Format and Parse
Format turn a Time into text using a layout t.Format(time.RFC3339)
time.Parse read text into a Time using a layout (UTC if no zone) time.Parse("2006-01-02", s)
time.ParseInLocation parse text as a time in a given zone time.ParseInLocation(l, s, ist)
RFC 3339 internet standard date-time format 2026-11-06T23:50:07Z
Z "Zulu": the UTC zone in RFC 3339 ...07Z
time.Kitchen, time.DateOnly ready-made layouts 11:50PM, 2026-11-06
Time zone how a region shows an instant; an offset from UTC IST +0530
*time.Location Go's type for a time zone ist
IANA time zone database the world's list of zones and their rules (tzdata) Asia/Kolkata
time.LoadLocation look up a zone by IANA name time.LoadLocation("America/New_York")
UTC Coordinated Universal Time: the world reference clock +0000 UTC
Offset difference from UTC +0530, -0500
IST / EST India Standard Time / Eastern Standard Time (US) +0530 / -0500
Daylight saving time moving clocks one hour in summer New York EDT -0400
In / UTC / Local show the same instant in another zone t.In(ny)
Local the computer's own zone time.Local
Equal same instant? a.Equal(b)
Before / After / Compare ordering of instants a.Before(b)
Zero time the zero value of Time: year 1, UTC t.IsZero()
Wall clock the time-of-day clock; can jump NTP corrections
Monotonic clock a clock that only moves forward; for measuring m=+0.000012
Round(0) strip the monotonic reading t.Round(0)
NTP Network Time Protocol: computers correcting their clocks over the internet wall-clock jumps
Unix timestamp seconds since 1 January 1970 UTC 1793989200
Unix epoch 1970-01-01 00:00:00 UTC time.Unix(0, 0)
Unix / UnixMilli seconds / milliseconds since the epoch t.UnixMilli()

Summary

  • Clock maths with plain ints breaks at midnight, month ends and zones.
  • time.Time is an instant; time.Duration is int64 nanoseconds between instants.
  • Add, Sub, AddDate, Since and Until do the maths; convert ints with time.Duration(n), and always give Sleep a unit.
  • Format and Parse use the reference time Mon Jan 2 15:04:05 MST 2006; time.RFC3339 for machines.
  • Parse assumes UTC; use ParseInLocation for local input.
  • LoadLocation + In show one instant in any zone; store UTC, show local.
  • Compare with Equal, Before, After, never ==; IsZero checks the zero time.
  • time.Now carries a monotonic reading, so Since measures correctly; Unix timestamps count seconds since 1970 UTC.

Next episode: Standard library tour: strconv, sort.Slice, slices.SortFunc, math, math/big, math/rand/v2, crypto/rand, regexp, text/template, html/template and the container packages.