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#Durations

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) (p 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) DurationApprox() time.Duration
  • 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) WeeksFloat() float32
  • func (period Period) Years() int
  • func (period Period) YearsFloat() float32

Variables

var PeriodDayNames = plural.FromZero("%v days", "%v day", "%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.FromZero("", "%v hour", "%v hours")

PeriodHourNames is as for PeriodDayNames but for hours.

var PeriodMinuteNames = plural.FromZero("", "%v minute", "%v minutes")

PeriodMinuteNames is as for PeriodDayNames but for minutes.

var PeriodMonthNames = plural.FromZero("", "%v month", "%v months")

PeriodMonthNames is as for PeriodDayNames but for months.

var PeriodSecondNames = plural.FromZero("", "%v second", "%v seconds")

PeriodSecondNames is as for PeriodDayNames but for seconds.

var PeriodWeekNames = plural.FromZero("", "%v week", "%v weeks")

PeriodWeekNames is as for PeriodDayNames but for weeks.

var PeriodYearNames = plural.FromZero("", "%v year", "%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. Therefore there are six fields: years, months, days, hours, minutes, and seconds.

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.

However, 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 in each field. 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) (p 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.

The result is not normalised; for time differences less than 3276 days, it will contain zero in the years and months fields but the number of days may be up to 3275; this reduces errors arising from the variable lengths of months. For larger time differences, greater than 3276 days, the months and years fields are used as well.

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. The fields are initialised verbatim without any normalisation; e.g. 120 seconds will not become 2 minutes. Use the Normalise method if you need to.

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. The fields are initialised verbatim without any normalisation; e.g. 120 seconds will not become 2 minutes. Use the Normalise method if you need to.

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. The fields are initialised verbatim without any normalisation; e.g. 12 months will not become 1 year. Use the Normalise method if you need to.

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. Use this method along with Negate in order to subtract periods.

The result is not normalised and may overflow arithmetically (to make this unlikely, use Normalise on the inputs before adding them).

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 does not include any other field.

func (Period) DaysFloat

func (period Period) DaysFloat() float32

DaysFloat gets the number of days in the period. This includes the implied number of weeks but does not include any other field.

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 hours, minutes and seconds only, the result is precise. however, when the period specifies years, months and days, it is impossible to be precise because the result may depend on knowing date and timezone information, so the duration is estimated on the basis of a year being 365.25 days and a month being 1/12 of a that; days are all assumed to be 24 hours long.

func (Period) DurationApprox

func (period Period) DurationApprox() time.Duration

DurationApprox converts a period to the equivalent duration in nanoseconds. When the period specifies hours, minutes and seconds only, the result is precise. however, when the period specifies years, months and days, it is impossible to be precise because the result may depend on knowing date and timezone information, so the duration is estimated on the basis of a year being 365.25 days and a month being 1/12 of a that; days are all assumed to be 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 is the number of hours and 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 is the number of hours and 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 also implies that all the fields are negative or zero.

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 is the number of minutes and 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 is the number of minutes and 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 is the number of months and 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 is the number of months and 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.

Because the number of hours per day is imprecise (due to daylight savings etc), and because the number of days per month is variable in the Gregorian calendar, there is a reluctance to transfer time too or from the days element. To give control over this, there are two modes.

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 approx. 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. The result is normalised.

Bear in mind that the internal representation is limited by fixed-point arithmetic with one decimal place; each field is only int16.

Known issue: scaling by a large reduction factor (i.e. much less than one) doesn't work properly.

func (Period) Seconds

func (period Period) Seconds() int

Seconds gets the whole number of seconds in the period. The result is the number of seconds and 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 is the number of seconds and 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 ISO-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. The result is the number of weeks and does not include any other field.

func (Period) WeeksFloat

func (period Period) WeeksFloat() float32

WeeksFloat calculates the number of weeks from the number of days. The result is the number of weeks and does not include any other field.

func (Period) Years

func (period Period) Years() int

Years gets the whole number of years in the period. The result is the number of years and 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 is the number of years and does not include any other field.