Go: Compare time instants and normalize map keys
Two time.Time values can describe the same instant and fail a == comparison. The operator compares the stored location and monotonic-clock data as well as the instant. This also affects a map keyed by time.Time.
Set up
Tested on Linux amd64 with Go 1.26.10. Use Bash with Go on your PATH, a text editor, and the mktemp, rm, and rmdir utilities. The example uses only the standard library. Keep the same terminal through cleanup, and stop if setup fails before saving the source.
start_dir="$PWD"
work_dir="$(mktemp -d)" || exit 1
cd -- "$work_dir" || exit 1Run the example
Save as go-time-equal-map-keys.go:
package main
import (
"fmt"
"time"
)
func instantKey(t time.Time) time.Time {
return t.UTC().Round(0)
}
func main() {
utc := time.Date(2026, 11, 18, 0, 0, 0, 123, time.UTC)
local := utc.In(time.FixedZone("UTC+09", 9*60*60))
fmt.Println("same instant:", utc.Equal(local))
fmt.Println("equal structs:", utc == local)
raw := map[time.Time]string{utc: "deployment"}
_, rawFound := raw[local]
fmt.Println("raw map lookup:", rawFound)
canonical := map[time.Time]string{instantKey(utc): "deployment"}
value, found := canonical[instantKey(local)]
fmt.Printf("canonical lookup: found=%t value=%q\n", found, value)
fmt.Println("nanosecond preserved:", instantKey(local).Nanosecond())
fmt.Println("one nanosecond later:", utc.Equal(local.Add(time.Nanosecond)))
if !found || instantKey(local) != instantKey(utc) {
panic("canonical key mismatch")
}
}Run:
go run go-time-equal-map-keys.goObserved output:
same instant: true
equal structs: false
raw map lookup: false
canonical lookup: found=true value="deployment"
nanosecond preserved: 123
one nanosecond later: falseRead the result
The two values differ only in their location representation. Equal recognizes the same instant, but the struct comparison fails, so the raw map lookup misses. The canonical map applies the same conversion when inserting and looking up a key.
UTC puts both values in the same location and strips any monotonic reading. Round(0) also strips a monotonic reading without rounding away fractional seconds; it is explicit but redundant after UTC here. The output retains the 123-nanosecond fraction and distinguishes a value one nanosecond later.
Apply it carefully
Use Equal for ordinary instant comparisons. For map keys, apply one canonicalization rule at every insertion and lookup. This example uses fixed test values with no monotonic reading; the standard-library contract documents how the normalization handles one.
This key represents a wall-clock instant. It intentionally discards location identity and monotonic-clock information, so it is unsuitable when those are part of the key’s meaning. Keep the original value if you need it for local display or elapsed-time measurements. Two readings of a real clock need not be identical just because they describe the same operation; choosing a coarser grouping interval is a separate policy.
See the Time type and comparison guidance, Time.Equal, and Time.Round.
Clean up
Remove the saved source and the empty scratch directory. Go manages its build cache separately. If the directory is not empty, inspect its contents before removing anything else.
rm -- go-time-equal-map-keys.go
cd -- "$start_dir" || exit 1
rmdir -- "$work_dir"
unset start_dir work_dirAcknowledgements
This post was created with assistance from AI.