Stage 1 · Code
Standard Library Toolkit
Make Time Behave
Clocks, delays, deadlines, and timestamps all look simple until a real program has to handle them exactly. This lesson turns Go's `time` package from something strange into something predictable.
Instants and Durations
It helps to separate two ideas that beginners often blur together. An instant is a point on the calendar, like '2026-07-20 at 9:15 AM in Pune.' A duration is an amount of elapsed time, like '90 minutes' or '250 milliseconds.' One answers 'when?'. The other answers 'how long?'.
Go keeps those ideas separate on purpose. time.Time represents an instant. time.Duration represents a length of time. Once that mental split clicks, a lot of the package stops feeling magical.
If time.Time is a pin stuck into a wall calendar, time.Duration is a stopwatch reading. You can add a stopwatch reading to a calendar pin, or subtract two calendar pins to get a stopwatch reading back.
Formatting and Parsing Time
This is the part of Go that surprises almost everyone: formatting does not use codes like %Y or %m. Instead, you write a sample timestamp using one specific reference time: Mon Jan 2 15:04:05 MST 2006.
Why would Go do that? Because the layout string is meant to show the final shape directly. Instead of memorizing a dictionary of symbols, you rearrange an example date until it looks like the output you want. Month is written with the month part of the reference time. Day is written with the day part. Hour is written with the hour part. The layout is not a format code language. It is a stencil built from one known timestamp.
- Start with the reference time:
Mon Jan 2 15:04:05 MST 2006. - Keep only the pieces you want. For
2026-07-20, you need year, month, and day. - Arrange those pieces in the target order:
2006-01-02. - Add separators exactly where you want them. Hyphens, spaces, colons, and
Tare literal characters. - Use the same layout both to format and to parse strings with that exact shape.
| Need | Go layout | What it means |
|---|---|---|
| Date only | 2006-01-02 | Year-month-day, like 2026-07-20 |
| Clock only | 15:04:05 | 24-hour time with seconds |
| 12-hour clock | 03:04 PM | 12-hour time with AM or PM |
| Zone offset | -0700 | Numeric offset such as +0530 |
| RFC3339 | time.RFC3339 | A predefined layout constant from the package |
A useful rule is this: if you are inventing a layout, build it by starting with the full reference time and deleting pieces until only your target shape remains. That is much easier than trying to remember the whole thing as trivia.
Timers and Tickers
Sometimes time is data. Other times time is a trigger. You are not just storing timestamps; you are waiting for something to happen later. That is where timers and tickers enter.
| Tool | Best for | What it gives you |
|---|---|---|
time.After | A one-off delay in simple code | A channel that receives a value once the wait is over |
time.NewTimer | A one-off delay you may need to stop or reset | A timer object plus its channel |
time.NewTicker | Repeated work on an interval | A channel that receives a new tick over and over |
When you create a Timer or Ticker, stop it when you are done. That is both tidy and practical, especially for tickers that would otherwise keep firing forever.
Common Time Pitfalls
Time bugs feel creepy because the code can look perfectly reasonable. The danger is usually not syntax. The danger is hidden assumptions.
- Time zones matter.
2026-07-20 09:15in UTC is not the same instant as2026-07-20 09:15in Asia/Kolkata. - Use
t1.Equal(t2)when you mean 'same instant'. Avoidt1 == t2for normal comparisons, because==also considers location and monotonic clock details. - Parsing without a zone can be ambiguous. If the input has no zone information, decide which location should be applied instead of guessing.
- Durations are exact lengths. Calendar concepts like 'one month from now' are trickier, because months do not all have the same number of days.
Quiz
What does `time.Duration` represent?
Practice
Write a function `ReformatTimestamp(raw string) (string, error)` that parses timestamps shaped like `2026-07-20 09:15:30 +0530` and returns them in RFC3339 form, such as `2026-07-20T09:15:30+05:30`.
Summary
time.Timeis an instant;time.Durationis an elapsed length.- Go formats time by rearranging a specific reference timestamp, not by using
%codes. time.Afteris convenient for a simple one-shot wait, whileNewTimerandNewTickergive you more control.- Time zones are part of the meaning of a timestamp, not decorative metadata.
- Use
.Equal()when you mean 'same instant'.
Mark this lesson complete to store local progress and unlock a cleaner resume path the next time you visit.