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.
timeout := 2*time.Minute + 30*time.Second fmt.Println(timeout) // 2m30s
Try it
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.
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
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. Write100 * time.Millisecond. - Variables need a conversion:
time.Duration(n) * time.Second. Multiplying twoDurationvalues (d * time.Secondwheredis 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.AddDatefor calendar arithmetic. - Float conversions lose precision:
Seconds()returns afloat64; for exact comparisons keep values asDuration. - Overflow wraps silently in plain arithmetic, so
math.MaxInt64 * time.Nanosecond-style products need care.Time.Subsaturates, but+and*do not. - Config files: flags (
flag.Duration), environment values and JSON strings can all useParseDurationtext like30s. JSON encodes a rawDurationas 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.Sorthandles[]time.Duration. %vand%sprint the string form;%dprints nanoseconds.