duration

Documentation

Index

• Constants
• 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
• func Truncate(d time.Duration, r time.Duration) time.Duration
• type Duration
  • func Age(lhs, rhs time.Time) Duration
  • func Decode(sortNanos int64, months int64, days int64) (Duration, error)
  • func DecodeDuration(months, days, nanos int64) Duration
  • func FromBigInt(src *apd.BigInt) (Duration, bool)
  • func FromFloat64(x float64) Duration
  • func FromInt64(x int64) Duration
  • func MakeDuration(nanos, days, months int64) Duration
  • func MakeDurationJustifyHours(nanos, days, months int64) Duration
  • func (d Duration) Add(x Duration) Duration
  • func (d Duration) AsBigInt(dst *apd.BigInt)
  • func (d Duration) AsFloat64() float64
  • func (d Duration) AsInt64() (int64, bool)
  • 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) FormatWithStyle(buf *bytes.Buffer, style IntervalStyle)
  • func (d Duration) ISO8601String() string
  • func (d Duration) Mul(x int64) Duration
  • func (d Duration) MulFloat(x float64) Duration
  • func (d Duration) Nanos() int64
  • func (d *Duration) SetNanos(nanos int64)
  • func (d Duration) String() string
  • func (d Duration) StringNanos() string
  • func (d Duration) Sub(x Duration) Duration
• type IntervalStyle
  • func (IntervalStyle) EnumDescriptor() ([]byte, []int)
  • func (x IntervalStyle) String() string

Constants

const (
	// MicrosPerMilli is the amount of microseconds in a millisecond.
	MicrosPerMilli = 1000
	// MillisPerSec is the amount of milliseconds in a second.
	MillisPerSec = 1000
	// MicrosPerSec is the amount of microseconds in a second.
	MicrosPerSec = MicrosPerMilli * MillisPerSec
	// SecsPerMinute is the amount of seconds in a minute.
	SecsPerMinute = 60
	// SecsPerHour is the amount of seconds in an hour.
	SecsPerHour = 3600
	// SecsPerDay is the amount of seconds in a day.
	SecsPerDay = 86400
	// MinsPerHour is the amount of minutes in an hour.
	MinsPerHour = 60
	// HoursPerDay is the number of hours in a day.
	HoursPerDay = 24
	// DaysPerMonth is the assumed amount of days in a month.
	// is always evaluated to 30, as it is in postgres.
	DaysPerMonth = 30
	// DaysPerYear is the number of days in a year.
	// It is assumed to include a quarter day to account for the leap year.
	// Matches DAYS_PER_YEAR in postgres.
	DaysPerYear = 365.25
	// MonthsPerYear is the amount of months in the year.
	MonthsPerYear = 12
)

Variables

var IntervalStyle_name = map[int32]string{
	0: "POSTGRES",
	1: "ISO_8601",
	2: "SQL_STANDARD",
}

var IntervalStyle_value = map[string]int32{
	"POSTGRES":     0,
	"ISO_8601":     1,
	"SQL_STANDARD": 2,
}

Functions

func Add

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

Add returns the time t+d, using a configurable mode.

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.

func Truncate

func Truncate(d time.Duration, r time.Duration) time.Duration

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.

Types

type Duration

type Duration struct {
	Months int64
	Days   int64
	// contains filtered or unexported fields
}

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.

func Age

func Age(lhs, rhs time.Time) Duration

Age returns a Duration rounded to the nearest microsecond from the time difference of (lhs - rhs).

Note that we cannot use time.Time's sub, as time.Duration does not give an accurate picture of day/month differences.

This is lifted from Postgres' timestamptz_age. The following comment applies: Note that this does not result in an accurate absolute time span since year and month are out of context once the arithmetic is done.

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 DecodeDuration

func DecodeDuration(months, days, nanos int64) Duration

DecodeDuration returns a Duration without rounding nanos.

func FromBigInt

func FromBigInt(src *apd.BigInt) (Duration, bool)

FromBigInt converts an apd.BigInt number of nanoseconds to a duration. Inverse conversion of AsBigInt. Boolean false if the result overflows.

func FromFloat64

func FromFloat64(x float64) Duration

FromFloat64 converts a float64 number of seconds to a duration. Inverse conversion of AsFloat64.

func FromInt64

func FromInt64(x int64) Duration

FromInt64 converts an int64 number of seconds to a duration. Inverse conversion of AsInt64.

func MakeDuration

func MakeDuration(nanos, days, months int64) Duration

MakeDuration returns a Duration rounded to the nearest microsecond.

func MakeDurationJustifyHours

func MakeDurationJustifyHours(nanos, days, months int64) Duration

MakeDurationJustifyHours returns a duration where hours are moved to days if the number of hours exceeds 24.

func (Duration) Add

func (d Duration) Add(x Duration) Duration

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

func (Duration) AsBigInt

func (d Duration) AsBigInt(dst *apd.BigInt)

AsBigInt converts a duration to an apd.BigInt with the number of nanoseconds.

func (Duration) AsFloat64

func (d Duration) AsFloat64() float64

AsFloat64 converts a duration to a float64 number of seconds.

func (Duration) AsInt64

func (d Duration) AsInt64() (int64, bool)

AsInt64 converts a duration to an int64 number of seconds. The conversion may overflow, in which case the boolean return value is false.

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 truncated to microseconds.

func (Duration) FormatWithStyle

func (d Duration) FormatWithStyle(buf *bytes.Buffer, style IntervalStyle)

FormatWithStyle emits a string representation of a Duration to a Buffer truncated to microseconds with a given style.

func (Duration) ISO8601String

func (d Duration) ISO8601String() string

ISO8601String returns an ISO 8601 representation ('P1Y2M3DT4H') of a Duration.

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) Nanos

func (d Duration) Nanos() int64

Nanos returns the nanos of d.

func (*Duration) SetNanos

func (d *Duration) SetNanos(nanos int64)

SetNanos rounds and sets nanos.

func (Duration) String

func (d Duration) String() string

String returns a string representation of a Duration.

func (Duration) StringNanos

func (d Duration) StringNanos() string

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. The encoded value is expected to be in "postgres" interval style format.

func (Duration) Sub

func (d Duration) Sub(x Duration) Duration

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

type IntervalStyle

type IntervalStyle int32

IntervalStyle matches the PostgreSQL IntervalStyle session parameter.

const (
	IntervalStyle_POSTGRES     IntervalStyle = 0
	IntervalStyle_ISO_8601     IntervalStyle = 1
	IntervalStyle_SQL_STANDARD IntervalStyle = 2
)

func (IntervalStyle) EnumDescriptor

func (IntervalStyle) EnumDescriptor() ([]byte, []int)

func (IntervalStyle) String

func (x IntervalStyle) String() string