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 includetime.RFC3339 = "2006-01-02T15:04:05Z07:00",time.Kitchen = "3:04PM"andtime.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:20doesn't exist: after 23:59 comes 00:00 of the next day.-1290minutes: 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 likeArea/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
Timeknows 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
Durationis a defined type (episode 19) whose underlying type isint64, counting nanoseconds (billionths of a second). So90 * time.Minuteis 5,400,000,000,000. - Constants:
time.Nanosecond,time.Microsecond,time.Millisecond,time.Second,time.Minute,time.Hour. There's noDay: days can be 23 or 25 hours long when clocks change for daylight saving time. - Durations print readably (
1h30m0s), and convert withHours(),Minutes(),Seconds()(asfloat64) andMilliseconds()(asint64). time.ParseDuration("1h45m")reads text with the unitsns,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.Minuteworked only because90is 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 ford.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)andd.Truncate(m)tidy a duration to a multiple ofm.
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-01put the day where the month goes: 6 November became2026-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
Zmeans UTC. It's whatjson.Marshal(episode 35) uses for atime.Time. .000adds 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 asFormat.- 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,
Parseassumes UTC. Text typed by a person in India usually means India time: usetime.ParseInLocation(layout, text, loc). - The two results show the same clock time but are different instants, 5 hours 30 minutes apart, so
Equalis 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()andt.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 isAsia/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 wholeTimestruct, 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), anda.Compare(b)(−1, 0 or +1; Go 1.20) do ordering.- The zero value of
time.Timeis0001-01-01 00:00:00 UTC;t.IsZero()checks for "never set". - Don't use
Timeas 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. ItsString()shows the monotonic reading asm=+0.000012345;t.Round(0)removes it.Sub,Since,Until,BeforeandAfteruse 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'sDate.now()uses),t.UnixNano()nanoseconds.time.Unix(sec, nsec)andtime.UnixMilli(ms)go back; they return local time, so add.UTC()to see UTC.
Mini project: delivery tracker
- Parse the order time
06/11/2026 23:50inAsia/KolkatawithParseInLocation. - Deliver-by = placed + 30 minutes; print it as
Mon 3:04 PM. - Was the delivery at
07/11/2026 00:34late? By how long? - 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
- (Homework) Build the delivery tracker (solution: the mini project).
- (Homework) Print today in three layouts.
- (Homework) Show one meeting time in three time zones.
- (Homework) Time a loop with
time.Since. - 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
- 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. - What is a
time.Duration? Anint64count of nanoseconds, with constants liketime.Secondand methods likeHours(). - Why prefer
Equalto==?==also compares the location and the monotonic reading;Equalcompares only the instant. - What does
time.Parsedo with no zone in the input? It returns UTC. UseParseInLocationfor local input. - What is the monotonic clock and why does Go use it? A clock that only moves forward;
time.Nowrecords it soSub/Sincemeasure correctly even if the wall clock is adjusted. - How should a backend store times? In UTC (or as Unix timestamps), converting to the user's zone only for display.
- Why is there no
time.Dayconstant? A calendar day isn't always 24 hours (daylight saving changes); useAddDatefor calendar maths. - What's a Unix timestamp? Seconds since 1970-01-01 00:00 UTC;
t.Unix(),time.Unix(sec, 0). - 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.Timeis an instant;time.Durationisint64nanoseconds between instants.Add,Sub,AddDate,SinceandUntildo the maths; convert ints withtime.Duration(n), and always giveSleepa unit.FormatandParseuse the reference timeMon Jan 2 15:04:05 MST 2006;time.RFC3339for machines.Parseassumes UTC; useParseInLocationfor local input.LoadLocation+Inshow one instant in any zone; store UTC, show local.- Compare with
Equal,Before,After, never==;IsZerochecks the zero time. time.Nowcarries a monotonic reading, soSincemeasures 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.