Skip to content
Tutorials Center
My learning

Topics

Go Reference ยท Time, Math and Randomness

Go time.Duration type

Reference for Go time.Duration: nanosecond int64 type, Second/Minute/Hour constants, ParseDuration, Round, Truncate, Seconds(), String and common mistakes.

time.Duration is an amount of elapsed time. It is defined as type Duration int64 and counts nanoseconds, so it can represent about 292 years either side of zero. Because it is an ordinary integer type you can add, subtract, compare and multiply durations like numbers.

The package provides the unit constants Nanosecond, Microsecond, Millisecond, Second, Minute and Hour. To build a duration, multiply a constant by a count: 5 * time.Second. A Duration prints in a readable form such as 1h30m0s or 250ms.

Go
timeout := 2*time.Minute + 30*time.Second
fmt.Println(timeout) // 2m30s

Try it

Go Constants, arithmetic and printing

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Go ParseDuration and common mistakes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with bufio.Scanner or fmt.Scan), it gets the next line from this box.

Syntax

Go
type Duration int64

const (
	Nanosecond  Duration = 1
	Microsecond          = 1000 * Nanosecond
	Millisecond          = 1000 * Microsecond
	Second               = 1000 * Millisecond
	Minute               = 60 * Second
	Hour                 = 60 * Minute
)

func ParseDuration(s string) (Duration, error)
Method Returns
String() Text like 72h3m0.5s; 0s for zero; sub-second values use ms, ยตs, ns.
Hours(), Minutes(), Seconds() The duration as a float64 count of that unit.
Milliseconds(), Microseconds(), Nanoseconds() Whole int64 counts (truncated toward zero).
Round(m) Rounded to the nearest multiple of m, halves away from zero.
Truncate(m) Rounded toward zero to a multiple of m.
Abs() Absolute value (Go 1.19); MinInt64 becomes the max value.

ParseDuration accepts a signed sequence of decimal numbers, each with a unit suffix: ns, us (or ยตs), ms, s, m, h. Examples: "300ms", "-1.5h", "2h45m".

Errors: ParseDuration returns an error (messages start with time:) for empty text, a missing unit ("10" is invalid, except exactly "0"), an unknown unit ("1d", "5 minutes") and values that overflow. Round and Truncate with m <= 0 return d unchanged.

Usage notes

  • Always multiply by a unit constant. time.Sleep(100) sleeps 100 nanoseconds. Write 100 * time.Millisecond.
  • Variables need a conversion: time.Duration(n) * time.Second. Multiplying two Duration values (d * time.Second where d is already a duration) compiles but is almost always a bug, giving nanoseconds-squared.
  • No days, weeks, months or years. Those vary with calendars and daylight-saving time; use Time.AddDate for calendar arithmetic.
  • Float conversions lose precision: Seconds() returns a float64; for exact comparisons keep values as Duration.
  • Overflow wraps silently in plain arithmetic, so math.MaxInt64 * time.Nanosecond-style products need care. Time.Sub saturates, but + and * do not.
  • Config files: flags (flag.Duration), environment values and JSON strings can all use ParseDuration text like 30s. JSON encodes a raw Duration as a number of nanoseconds, which is rarely what you want; store a string or seconds explicitly.
  • Formatting for humans: d.Round(time.Millisecond) or .Round(time.Second) makes output tidy before printing.
  • Comparison and sorting work with the normal operators, and slices.Sort handles []time.Duration.
  • %v and %s print the string form; %d prints nanoseconds.