Skip to content
Go: Compare time instants and normalize map keys

Go: Compare time instants and normalize map keys

November 18, 2026

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 1

Run 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.go

Observed output:

same instant: true
equal structs: false
raw map lookup: false
canonical lookup: found=true value="deployment"
nanosecond preserved: 123
one nanosecond later: false

Read 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_dir

Acknowledgements

This post was created with assistance from AI.

Last updated on