skip to content

Why can two time.Time values for the same instant differ under ==, and when must you use Equal?

level: middleimportance: should knowfreq 52%

answer

  1. a struct compares its fields
  2. three fields, only one is the instant
  3. same instant, two different values
  4. a pointer to a location takes part
  5. prefer the method to the operator

basics

~20 s

== compares a time.Time's whole representation: its wall reading, its monotonic reading and its location pointer. Two values for the same instant differ if one still carries a monotonic reading or sits in another location. Equal compares only the instant.

solid answer

~40 s

`time.Time` is a struct, so `==` compares everything in it: the wall-clock reading, the monotonic reading, and the `*time.Location` pointer. Two values that denote exactly the same instant can therefore be unequal — the classic case is a value straight from `time.Now()`, which carries a monotonic reading, versus the same instant after a round trip through encoding or `t.Round(0)`, which does not. Different locations do it too: the same instant as `time.UTC` and as a loaded zone are not `==`. `t.Equal(u)` compares the instants, using the monotonic readings when both have them and the wall readings otherwise, which is almost always what you meant. The same trap bites `reflect.DeepEqual` in tests and `time.Time` used as a map key; normalise with `t.UTC().Round(0)` if you truly need `==` semantics.

code

go · 5 lines
go
t := time.Now()
u := t.Round(0) // same instant, monotonic reading stripped

fmt.Println(t == u)     // false: the representations differ
fmt.Println(t.Equal(u)) // true: the instants are the same

go deeper

for a junior

Remember the rule: compare two time.Time values with t.Equal(u), not with ==, because == can say false for two values that mean the same moment.

for a middle

Explain what == actually compares — wall reading, monotonic reading, location pointer — and name the situations that make identical instants unequal.

for a senior

Show where this bites in real systems: flaky DeepEqual assertions, missed map lookups after a reload, and the normalisation you apply at the boundary to prevent both.

for a principal

Take a position on convention: whether timestamps in comparable structs are allowed at all, or whether your codebase normalises at construction so nobody has to remember this rule under pressure.

## What == actually compares `time.Time` is a struct value, and Go's `==` on a struct compares its fields. A `time.Time` holds three things: a packed wall-clock reading, a monotonic reading (which may be absent), and a pointer to a `time.Location`. So `t == u` is asking "are these two values identical in representation?", not "do these two values denote the same instant?" Those two questions have different answers surprisingly often. ## The three ways two equal instants become unequal values **1. One carries a monotonic reading and the other does not.** `time.Now()` produces a value with one. Encoding and decoding it, or calling `t.Round(0)`, `t.UTC()`, `t.Truncate(d)` or `t.AddDate(…)`, produces a value without one. Same instant, different representation, so `==` is false. **2. Both carry monotonic readings, but different ones.** Two calls to `time.Now()` a nanosecond apart obviously differ, but so can two values you would expect to match after independent arithmetic. **3. The location pointers differ.** The same instant expressed with `time.UTC` and with a location loaded from the time-zone database is one instant with two `*time.Location` values, and `==` compares the pointers. ## What Equal does instead `t.Equal(u)` answers the question you almost always meant: do these represent the same instant? It ignores the location entirely, and it follows the same rule as `Sub`, `Before` and `After` — if both values carry monotonic readings, it compares those; otherwise it compares wall-clock readings. The `time` package documentation is explicit that you should prefer `t.Equal(u)` to `t == u`. ## Where the trap actually fires You rarely write `t == u` by hand; the trap arrives indirectly. - **Tests.** `reflect.DeepEqual` on two structs containing `time.Time` fields compares them field by field, exactly like `==`. A test that builds an expected value with a literal timestamp and compares it against one that came from `time.Now()` fails for reasons that have nothing to do with the code under test. Compare timestamps explicitly with `Equal`, or normalise both sides first. - **Map keys.** A `time.Time` is comparable, so the compiler happily accepts it as a map key. Store with a value from `time.Now()` and look up with the same instant reconstructed from storage, and the lookup misses — different representation, different key. The documented remedy is to guarantee an identical location for all keys (via `UTC` or `Local`) and to strip the monotonic reading with `Round(0)` before using the value as a key. - **Struct comparison and set membership.** Any code that leans on `==` for a struct containing a timestamp inherits the same behaviour. ## The normalisation recipe When you genuinely need `==` semantics — a key, a set, a struct compared as a whole — normalise both the location and the monotonic reading: ```go key := t.UTC().Round(0) ``` `UTC` pins the location pointer to the single shared `time.UTC` value (and, as a side effect, already strips the monotonic reading), and `Round(0)` is the documented, explicit strip. Writing both makes the intent obvious to the next reader rather than relying on a side effect. ## The mental model Think of `==` as identity of the *value* and `Equal` as identity of the *instant*. Go could have hidden this by making `time.Time` non-comparable, but then it could not be a map key at all. Instead it is comparable, `==` is honest about what it compares, and the standard library gives you `Equal` for the question you meant to ask. The cost of that choice is exactly this class of bug, which is why the rule is worth carrying as a reflex: for `time.Time`, reach for `Equal` unless you have thought specifically about representation.

  • How would you make a time.Time safe to use as a map key?
    Normalise every key the same way before inserting or looking up: pin the location with `t.UTC()` so the location pointers match, and strip the monotonic reading with `Round(0)`. Then `==`, which is what map lookup uses, compares only the instant. Skipping either step gives you keys that never match on lookup.
  • A test compares two structs containing time.Time fields with reflect.DeepEqual and fails, yet the timestamps print identically. What is going on?
    DeepEqual compares those fields the way `==` does, so a monotonic reading on one side or a different location pointer makes it fail while the printed wall-clock text matches — the printed form omits the location identity and you may not have looked for the `m=` suffix. Compare the timestamps with `Equal`, or normalise both sides with `UTC().Round(0)` first.
  • Does Equal ignore the time zone as well as the monotonic reading?
    Yes. `Equal` asks only whether the two values denote the same instant, so the same moment expressed in two different locations is equal. That is usually what you want; if you also care that two values are in the same location you have to check that separately, for instance by comparing `t.Location().String()`.

Two photographs of the same clock face are pictures of one moment, but the files are not byte-identical. == compares the files; Equal compares the moment.

saying these in an interview costs you the question

  • Says == on time.Time compares only the instant
  • Thinks time.Time is not comparable and == will not compile
  • Assumes two values printing the same text must be ==
  • Uses reflect.DeepEqual on structs with timestamps without normalising
  • Believes Equal and == differ only when the time zones differ