duration

Documentation

Index

• Variables
• func Add(t time.Time, d Duration) time.Time
• func AddMicros(t time.Time, d int64) time.Time
• func DiffMicros(t1, t2 time.Time) int64
• type Duration
  • func Decode(sortNanos int64, months int64, days int64) (Duration, error)
  • func (d Duration) Add(x Duration) Duration
  • func (d Duration) Compare(x Duration) int
  • func (d Duration) Div(x int64) Duration
  • func (d Duration) DivFloat(x float64) Duration
  • func (d Duration) Encode() (sortNanos int64, months int64, days int64, err error)
  • func (d Duration) EncodeBigInt() (sortNanos *big.Int, months int64, days int64)
  • func (d Duration) Format(buf *bytes.Buffer)
  • func (d Duration) Mul(x int64) Duration
  • func (d Duration) MulFloat(x float64) Duration
  • func (d Duration) String() string
  • func (d Duration) Sub(x Duration) Duration

Variables

var ErrEncodeOverflow = errors.New("overflow during Encode")

ErrEncodeOverflow is returned by Encode when the sortNanos returned would have overflowed or underflowed.

Functions

func Add

func Add(t time.Time, d Duration) time.Time

Add returns the time t+d.

func AddMicros

func AddMicros(t time.Time, d int64) time.Time

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.

func DiffMicros

func DiffMicros(t1, t2 time.Time) int64

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.

Types

type Duration

type Duration struct {
	Months int64
	Days   int64
	Nanos  int64
}

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.

TODO(dan): Until the overflow and underflow handling is fixed, this is only useful for durations of < 292 years.

func Decode

func Decode(sortNanos int64, months int64, days int64) (Duration, error)

Decode reverses the three integers returned from Encode and produces an equal Duration to the original.

func (Duration) Add

func (d Duration) Add(x Duration) Duration

Add returns a Duration representing a time length of d+x.

func (Duration) Compare

func (d Duration) Compare(x Duration) int

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.

func (Duration) Div

func (d Duration) Div(x int64) Duration

Div returns a Duration representing a time length of d/x.

func (Duration) DivFloat

func (d Duration) DivFloat(x float64) Duration

DivFloat returns a Duration representing a time length of d/x.

func (Duration) Encode

func (d Duration) Encode() (sortNanos int64, months int64, days int64, err error)

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.

func (Duration) EncodeBigInt

func (d Duration) EncodeBigInt() (sortNanos *big.Int, months int64, days int64)

EncodeBigInt is the same as Encode, except that it always returns successfully and is slower.

func (Duration) Format

func (d Duration) Format(buf *bytes.Buffer)

Format emits a string representation of a Duration to a Buffer.

func (Duration) Mul

func (d Duration) Mul(x int64) Duration

Mul returns a Duration representing a time length of d*x.

func (Duration) MulFloat

func (d Duration) MulFloat(x float64) Duration

MulFloat returns a Duration representing a time length of d*x.

func (Duration) String

func (d Duration) String() string

String returns a string representation of a Duration.

func (Duration) Sub

func (d Duration) Sub(x Duration) Duration

Sub returns a Duration representing a time length of d-x.