period

Documentation

Overview

Package period provides functionality for periods of time using ISO-8601 conventions. This deals with years, months, weeks and days. Because of the vagaries of calendar systems, the meaning of year lengths, month lengths and even day lengths depends on context. So a period is not necessarily a fixed duration of time in terms of seconds.

See https://en.wikipedia.org/wiki/ISO_8601#Periods

Example representations:

* "P4D" is four days;

* "P3Y6M4W1D" is three years, 6 months, 4 weeks and one day.

* "P2DT12H" is 2 days and 12 hours.

* "PT30S" is 30 seconds.

* "P2.5Y" is 2.5 years.

Index

• Variables
• type Period
  • func Between(t1, t2 time.Time) Period
  • func MustParse(value string) Period
  • func New(years, months, days, hours, minutes, seconds int) Period
  • func NewHMS(hours, minutes, seconds int) Period
  • func NewOf(duration time.Duration) (p Period, precise bool)
  • func NewYMD(years, months, days int) Period
  • func Parse(period string) (Period, error)
  • func (period Period) Abs() Period
  • func (period Period) Add(that Period) Period
  • func (period Period) Days() int
  • func (period Period) DaysFloat() float32
  • func (period Period) Duration() (time.Duration, bool)
  • func (period Period) Format() string
  • func (period Period) FormatWithPeriodNames(...) string
  • func (period Period) Hours() int
  • func (period Period) HoursFloat() float32
  • func (period Period) IsNegative() bool
  • func (period Period) IsZero() bool
  • func (period Period) MarshalBinary() ([]byte, error)
  • func (period Period) MarshalText() ([]byte, error)
  • func (period Period) Minutes() int
  • func (period Period) MinutesFloat() float32
  • func (period Period) ModuloDays() int
  • func (period Period) Months() int
  • func (period Period) MonthsFloat() float32
  • func (period Period) Negate() Period
  • func (period Period) Normalise(precise bool) Period
  • func (period Period) OnlyHMS() Period
  • func (period Period) OnlyYMD() Period
  • func (period Period) Scale(factor float32) Period
  • func (period Period) Seconds() int
  • func (period Period) SecondsFloat() float32
  • func (period Period) Sign() int
  • func (period Period) String() string
  • func (period Period) TotalDaysApprox() int
  • func (period Period) TotalMonthsApprox() int
  • func (period *Period) UnmarshalBinary(data []byte) error
  • func (period *Period) UnmarshalText(data []byte) (err error)
  • func (period Period) Weeks() int
  • func (period Period) Years() int
  • func (period Period) YearsFloat() float32

Variables

var PeriodDayNames = plural.Plurals{plural.Case{0, "%v days"}, plural.Case{1, "%v day"}, plural.Case{2, "%v days"}}

PeriodDayNames provides the English default format names for the days part of the period. This is a sequence of plurals where the first match is used, otherwise the last one is used. The last one must include a "%v" placeholder for the number.

var PeriodHourNames = plural.Plurals{plural.Case{0, ""}, plural.Case{1, "%v hour"}, plural.Case{2, "%v hours"}}

PeriodHourNames is as for PeriodDayNames but for hours.

var PeriodMinuteNames = plural.Plurals{plural.Case{0, ""}, plural.Case{1, "%v minute"}, plural.Case{2, "%v minutes"}}

PeriodMinuteNames is as for PeriodDayNames but for minutes.

var PeriodMonthNames = plural.Plurals{plural.Case{0, ""}, plural.Case{1, "%v month"}, plural.Case{2, "%g months"}}

PeriodMonthNames is as for PeriodDayNames but for months.

var PeriodSecondNames = plural.Plurals{plural.Case{0, ""}, plural.Case{1, "%v second"}, plural.Case{2, "%v seconds"}}

PeriodSecondNames is as for PeriodDayNames but for seconds.

var PeriodWeekNames = plural.Plurals{plural.Case{0, ""}, plural.Case{1, "%v week"}, plural.Case{2, "%v weeks"}}

PeriodWeekNames is as for PeriodDayNames but for weeks.

var PeriodYearNames = plural.Plurals{plural.Case{0, ""}, plural.Case{1, "%v year"}, plural.Case{2, "%v years"}}

PeriodYearNames is as for PeriodDayNames but for years.

Types

type Period

type Period struct {
	// contains filtered or unexported fields
}

Period holds a period of time and provides conversion to/from ISO-8601 representations. In the ISO representation, decimal fractions are supported, although only the last non-zero component is allowed to have a fraction according to the Standard. For example "P2.5Y" is 2.5 years.

In this implementation, the precision is limited to one decimal place only, by means of integers with fixed point arithmetic. This avoids using float32 in the struct, so there are no problems testing equality using ==.

The implementation limits the range of possible values to ± 2^16 / 10. Note in particular that the range of years is limited to approximately ± 3276.

The concept of weeks exists in string representations of periods, but otherwise weeks are unimportant. The period contains a number of days from which the number of weeks can be calculated when needed.

Note that although fractional weeks can be parsed, they will never be returned via String(). This is because the number of weeks is always inferred from the number of days.

func Between

func Between(t1, t2 time.Time) Period

Between converts the span between two times to a period. Based on the Gregorian conversion algorithms of `time.Time`, the resultant period is precise.

Remember that the resultant period does not retain any knowledge of the calendar, so any subsequent computations applied to the period can only be precise if they concern either the date (year, month, day) part, or the clock (hour, minute, second) part, but not both.

func MustParse

func MustParse(value string) Period

MustParse is as per Parse except that it panics if the string cannot be parsed. This is intended for setup code; don't use it for user inputs.

func New

func New(years, months, days, hours, minutes, seconds int) Period

New creates a simple period without any fractional parts. All the parameters must have the same sign (otherwise a panic occurs).

func NewHMS

func NewHMS(hours, minutes, seconds int) Period

NewHMS creates a simple period without any fractional parts. All the parameters must have the same sign (otherwise a panic occurs).

func NewOf

func NewOf(duration time.Duration) (p Period, precise bool)

NewOf converts a time duration to a Period, and also indicates whether the conversion is precise. Any time duration that spans more than ± 3276 hours will be approximated by assuming that there are 24 hours per day, 30.4375 per month and 365.25 days per year.

func NewYMD

func NewYMD(years, months, days int) Period

NewYMD creates a simple period without any fractional parts. All the parameters must have the same sign (otherwise a panic occurs).

func Parse

func Parse(period string) (Period, error)

Parse parses strings that specify periods using ISO-8601 rules.

In addition, a plus or minus sign can precede the period, e.g. "-P10D"

The zero value can be represented in several ways: all of the following are equivalent: "P0Y", "P0M", "P0W", "P0D", "PT0H", PT0M", PT0S", and "P0". The canonical zero is "P0D".

func (Period) Abs

func (period Period) Abs() Period

Abs converts a negative period to a positive one.

func (Period) Add

func (period Period) Add(that Period) Period

Add adds two periods together.

func (Period) Days

func (period Period) Days() int

Days gets the whole number of days in the period. This includes the implied number of weeks but excludes the specified years and months.

func (Period) DaysFloat

func (period Period) DaysFloat() float32

DaysFloat gets the number of days in the period. This includes the implied number of weeks.

func (Period) Duration

func (period Period) Duration() (time.Duration, bool)

Duration converts a period to the equivalent duration in nanoseconds. A flag is also returned that is true when the conversion was precise and false otherwise. When the period specifies years, months and days, it is impossible to be precise, so the duration is calculated on the basis of a year being 365.25 days and a month being 1/12 of a that; days are all 24 hours long.

func (Period) Format

func (period Period) Format() string

Format converts the period to human-readable form using the default localisation.

func (Period) FormatWithPeriodNames

func (period Period) FormatWithPeriodNames(yearNames, monthNames, weekNames, dayNames, hourNames, minNames, secNames plural.Plurals) string

FormatWithPeriodNames converts the period to human-readable form in a localisable way.

func (Period) Hours

func (period Period) Hours() int

Hours gets the whole number of hours in the period. The result does not include any other field.

func (Period) HoursFloat

func (period Period) HoursFloat() float32

HoursFloat gets the number of hours in the period. The result does not include any other field.

func (Period) IsNegative

func (period Period) IsNegative() bool

IsNegative returns true if any field is negative. By design, this implies that all the fields are negative.

func (Period) IsZero

func (period Period) IsZero() bool

IsZero returns true if applied to a zero-length period.

func (Period) MarshalBinary

func (period Period) MarshalBinary() ([]byte, error)

MarshalBinary implements the encoding.BinaryMarshaler interface. This also provides support for gob encoding.

func (Period) MarshalText

func (period Period) MarshalText() ([]byte, error)

MarshalText implements the encoding.TextMarshaler interface for Periods.

func (Period) Minutes

func (period Period) Minutes() int

Minutes gets the whole number of minutes in the period. The result does not include any other field.

func (Period) MinutesFloat

func (period Period) MinutesFloat() float32

MinutesFloat gets the number of minutes in the period. The result does not include any other field.

func (Period) ModuloDays

func (period Period) ModuloDays() int

ModuloDays calculates the whole number of days remaining after the whole number of weeks has been excluded.

func (Period) Months

func (period Period) Months() int

Months gets the whole number of months in the period. The result does not include any other field.

func (Period) MonthsFloat

func (period Period) MonthsFloat() float32

MonthsFloat gets the number of months in the period. The result does not include any other field.

func (Period) Negate

func (period Period) Negate() Period

Negate changes the sign of the period.

func (Period) Normalise

func (period Period) Normalise(precise bool) Period

Normalise attempts to simplify the fields. It operates in either precise or imprecise mode.

In precise mode: Multiples of 60 seconds become minutes. Multiples of 60 minutes become hours. Multiples of 12 months become years.

Additionally, in imprecise mode: Multiples of 24 hours become days. Multiples of 30.4 days become months.

func (Period) OnlyHMS

func (period Period) OnlyHMS() Period

OnlyHMS returns a new Period with only the hour, minute and second fields. The year, month and day fields are zeroed.

func (Period) OnlyYMD

func (period Period) OnlyYMD() Period

OnlyYMD returns a new Period with only the year, month and day fields. The hour, minute and second fields are zeroed.

func (Period) Scale

func (period Period) Scale(factor float32) Period

Scale a period by a multiplication factor. Obviously, this can both enlarge and shrink it, and change the sign if negative. Bear in mind that the internal representation is limited by fixed-point arithmetic with one decimal place; each field is only int16.

func (Period) Seconds

func (period Period) Seconds() int

Seconds gets the whole number of seconds in the period. The result does not include any other field.

func (Period) SecondsFloat

func (period Period) SecondsFloat() float32

SecondsFloat gets the number of seconds in the period. The result does not include any other field.

func (Period) Sign

func (period Period) Sign() int

Sign returns +1 for positive periods and -1 for negative periods.

func (Period) String

func (period Period) String() string

String converts the period to -8601 form.

func (Period) TotalDaysApprox

func (period Period) TotalDaysApprox() int

TotalDaysApprox gets the approximate total number of days in the period. The approximation assumes a year is 365.25 days and a month is 1/12 of that. Whole multiples of 24 hours are also included in the calculation.

func (Period) TotalMonthsApprox

func (period Period) TotalMonthsApprox() int

TotalMonthsApprox gets the approximate total number of months in the period. The days component is included by approximately assumes a year is 365.25 days and a month is 1/12 of that. Whole multiples of 24 hours are also included in the calculation.

func (*Period) UnmarshalBinary

func (period *Period) UnmarshalBinary(data []byte) error

UnmarshalBinary implements the encoding.BinaryUnmarshaler interface. This also provides support for gob encoding.

func (*Period) UnmarshalText

func (period *Period) UnmarshalText(data []byte) (err error)

UnmarshalText implements the encoding.TextUnmarshaler interface for Periods.

func (Period) Weeks

func (period Period) Weeks() int

Weeks calculates the number of whole weeks from the number of days. If the result would contain a fraction, it is truncated.

func (Period) Years

func (period Period) Years() int

Years gets the whole number of years in the period. The result does not include any other field.

func (Period) YearsFloat

func (period Period) YearsFloat() float32

YearsFloat gets the number of years in the period, including a fraction if any is present. The result does not include any other field.