Time & Dates

The time package represents an instant as a time.Time and a span as a time.Duration , and its distinctive reference-layout ( 2006-01-02 15:04:05 ) drives all formatting and parsing.

Learn Time & Dates in our free Go course — an interactive lesson with runnable examples, a practice exercise and a quick reference.

Part of the free Go course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

What You'll Learn in This Lesson

1️⃣ Creating & Inspecting a Time

In real code you'd call time.Now() , but for reproducible examples we build a fixed instant with time.Date(year, month, day, hour, min, sec, nsec, loc) . From a time.Time you can read every field — Year() , Month() , Day() , Weekday() — and get the Unix timestamp with Unix() .

2️⃣ Durations & Comparing Times

A time.Duration is a length of time built from constants like time.Hour . Add one with t.Add(...) , and subtract two times with later.Sub(t) to get the duration between them (convert with .Hours() ). Compare instants with Before , After , and Equal ; shift by calendar units (months, years) with AddDate .

3️⃣ Formatting & Parsing with the Reference Layout

Go's signature feature: instead of letter codes, you describe a format by writing the reference date Mon Jan 2 15:04:05 MST 2006 the way you want the output to look. 2006 is the year, 01 the month, 02 the day, 15 the 24-hour clock, and so on. The same layout drives time.Parse , which reads a string back into a time.Time .

🎯 Your Turn

Format the fixed time as 2026-07-04 09:05 using the reference layout. Fill in the blank.

Compute the number of days between two fixed dates: subtract to get a Duration , divide its Hours() by 24, and print with one decimal. Also print the end date as "Mon, 02 Jan 2006" .

Practice quiz

Which reference layout formats a date as 2026-07-04?

  • YYYY-MM-DD
  • 2020-12-31
  • 2006-01-02
  • 01-02-2006

Answer: 2006-01-02. Go uses the reference time Mon Jan 2 15:04:05 MST 2006 as the layout.

In the reference layout, what does 15 represent?

  • The hour on a 24-hour clock
  • The day of the month
  • The minute
  • The 12-hour hour

Answer: The hour on a 24-hour clock. 15 is the 24-hour clock; 04 is the minute, 05 the second.

Which constructor builds a fixed, deterministic instant?

  • time.Now()
  • time.Fixed(...)
  • time.New(...)
  • time.Date(year, month, day, hour, min, sec, nsec, loc)

Answer: time.Date(year, month, day, hour, min, sec, nsec, loc). time.Now() depends on the wall clock; time.Date gives reproducible output.

How do you get the duration between two times?

  • later - earlier
  • later.Sub(earlier)
  • time.Diff(later, earlier)
  • later.Minus(earlier)

Answer: later.Sub(earlier). Sub returns a time.Duration; later.Sub(t).Hours() converts it to hours.

Which shifts a time by calendar units like one year?

  • t.AddDate(1, 0, 0)
  • t.Add(1 * time.Year)
  • t.AddYear(1)
  • t.Add(365 * time.Hour)

Answer: t.AddDate(1, 0, 0). AddDate respects month lengths and leap years; there is no time.Year constant.

How should you test whether two times are the same instant?

  • a == b
  • a.Same(b)
  • a.Equal(b)
  • a.Compare(b) only

Answer: a.Equal(b). Use Equal; == can differ on monotonic-clock or location data.

What does t.Add(48*time.Hour + 30*time.Minute) add to t?

  • 48 minutes and 30 seconds
  • 48 hours and 30 minutes
  • 78 minutes
  • 48.5 minutes

Answer: 48 hours and 30 minutes. Duration constants combine: that is a 48h30m shift, i.e. 48.5 hours.

What does time.Parse use to read a string into a time.Time?

  • A locale setting
  • Automatic detection
  • A regular expression
  • The same reference layout you format with

Answer: The same reference layout you format with. Parse and Format share the 2006-01-02 style layout.

What does time.Since(t) return?

  • The instant t formatted
  • The elapsed duration since t (time.Now().Sub(t))
  • A boolean for whether t is past
  • The Unix timestamp of t

Answer: The elapsed duration since t (time.Now().Sub(t)). Since(t) is shorthand for time.Now().Sub(t).

What does t.Unix() return?

  • Nanoseconds since midnight
  • The weekday number
  • Seconds since 1970-01-01 UTC
  • Milliseconds since the program started

Answer: Seconds since 1970-01-01 UTC. Unix() is the Unix timestamp in seconds.