Add returns the time t+d, using a configurable mode.
AddMicros adds the microsecond delta to the provided time value. The reason this function is necessary even though time.Add(duration) exists is that time.Duration can only hold values up to ~290 years, because it stores duration at the nanosecond resolution. This function makes it possible to add more than 290 years to a time.Time, at the tradeoff of working on a microsecond resolution.
DiffMicros computes the microsecond difference between two time values. The reason this function is necessary even though time.Sub(time) exists is that time.Duration can only hold values up to ~290 years, because it stores duration at the nanosecond resolution. This function should be used if a difference of more than 290 years is possible between time values, and a microsecond resolution is acceptable.
Truncate returns a new duration obtained from the first argument by discarding the portions at finer resolution than that given by the second argument. Example: Truncate(time.Second+1, time.Second) == time.Second.
AdditionMode controls date normalization behaviors in Add().
const ( // AdditionModeCompatible applies a date-normalization strategy // which produces results which are more compatible with // PostgreSQL in which adding a month "rounds down" to the last // day of a month instead of producing a value in the following // month. // // See PostgreSQL 10.5: src/backend/utils/adt/timestamp.c timestamp_pl_interval(). AdditionModeCompatible AdditionMode = false // AdditionModeLegacy delegates to time.Time.AddDate() for // performing Time+Duration math. AdditionModeLegacy AdditionMode = true )
GetAdditionMode allows an AdditionMode to be used as its own context.
Context is used to prevent a package-dependency cycle via tree.EvalContext.
A Duration represents a length of time.
A duration of "1 month" cannot be represented as a fixed number of nanoseconds because the length of months vary. The same is true for days because of leap seconds. Given a begin or end time to anchor a duration, the nanosecond count can be calculated, but it's useful to represent durations such as "1 year 3 months" without an anchor. Duration allows this.
For the purposes of Compare and Encode, 1 month is considered equivalent to 30 days and 1 day is equivalent to 24 * 60 * 60 * 1E9 nanoseconds.
Although the Nanos field is a number of nanoseconds, all operations round to the nearest microsecond. Any setting of this field should avoid setting with precision below microseconds. The only exceptions are the encode/decode operations.
TODO(dan): Until the overflow and underflow handling is fixed, this is only useful for durations of < 292 years.
Decode reverses the three integers returned from Encode and produces an equal Duration to the original.
DecodeDuration returns a Duration without rounding nanos.
FromBigInt converts a big.Int number of nanoseconds to a duration. Inverse conversion of AsBigInt. Boolean false if the result overflows.
FromFloat64 converts a float64 number of seconds to a duration. Inverse conversion of AsFloat64.
FromInt64 converts an int64 number of seconds to a duration. Inverse conversion of AsInt64.
MakeDuration returns a Duration rounded to the nearest microsecond.
Add returns a Duration representing a time length of d+x.
AsBigInt converts a duration to a big.Int with the number of nanoseconds.
AsFloat64 converts a duration to a float64 number of seconds.
AsInt64 converts a duration to an int64 number of seconds. The conversion may overflow, in which case the boolean return value is false.
Compare returns an integer representing the relative length of two Durations. The result will be 0 if d==x, -1 if d < x, and +1 if d > x.
Div returns a Duration representing a time length of d/x.
DivFloat returns a Duration representing a time length of d/x.
Encode returns three integers such that the original Duration is recoverable (using Decode) and the first int will approximately sort a collection of encoded Durations.
EncodeBigInt is the same as Encode, except that it always returns successfully and is slower.
Format emits a string representation of a Duration to a Buffer truncated to microseconds.
Mul returns a Duration representing a time length of d*x.
MulFloat returns a Duration representing a time length of d*x.
Nanos returns the nanos of d.
SetNanos rounds and sets nanos.
String returns a string representation of a Duration.
StringNanos returns a string representation of a Duration including its hidden nanoseconds value. To be used only by the encoding/decoding packages for pretty printing of on-disk values.
Sub returns a Duration representing a time length of d-x.