period

package
v1.21.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 24, 2024 License: BSD-3-Clause Imports: 8 Imported by: 98

Documentation

Overview

Package period provides functionality for periods of time using ISO-8601 conventions. This deals with years, months, weeks/days, hours, minutes and seconds.

*** Warning: this package is the subject of many issues, so a replacement is under development. Please see https://github.com/rickb777/period.

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:

* "P2Y" is two years;

* "P6M" is six months;

* "P4D" is four days;

* "P1W" is one week (seven days);

* "PT3H" is three hours.

* "PT20M" is twenty minutes.

* "PT30S" is thirty seconds.

These can be combined, for example:

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

* "P2DT12H" is 2 days and 12 hours.

Also, decimal fractions are supported to one decimal place. To comply with the standard, only the last non-zero component is allowed to have a fraction. For example

* "P2.5Y" is 2.5 years.

* "PT12M7.5S" is 12 minutes and 7.5 seconds.

Index

Constants

View Source 
const (
	Year  ymdDesignator = 'Y'
	Month ymdDesignator = 'M'
	Week  ymdDesignator = 'W'
	Day   ymdDesignator = 'D'

	Hour   hmsDesignator = 'H'
	Minute hmsDesignator = 'M'
	Second hmsDesignator = 'S'
)
View Source 
const (
	Unready itemState = iota
	Armed
	Set
)

Variables

View Source 
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.

View Source 
var PeriodHourNames = plural.FromZero("", "%v hour", "%v hours")

PeriodHourNames is as for PeriodDayNames but for hours.

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

PeriodMinuteNames is as for PeriodDayNames but for minutes.

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

PeriodMonthNames is as for PeriodDayNames but for months.

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

PeriodSecondNames is as for PeriodDayNames but for seconds.

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

PeriodWeekNames is as for PeriodDayNames but for weeks.

View Source 
var PeriodYearNames = plural.FromZero("", "%v year", "%v years")

PeriodYearNames is as for PeriodDayNames but for years.

Functions

This section is empty.

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.

To improve precision, result is not always fully normalised; for time differences less than 3276 hours (about 4.5 months), it will contain zero in the years, months and days fields but the number of hours may be up to 3275; this reduces errors arising from the variable lengths of months. For larger time differences (greater than 3276 hours) the days, 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, normalise ...bool) 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. By default, the value is normalised. Normalisation can be disabled using the optional flag.

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). Because this implementation uses int16 internally, the paramters must be within the range ± 2^16 / 10.

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, 365.2425 days per year (as per Gregorian calendar rules), and a month being 1/12 of that (approximately 30.4369 days).

The result is not always fully normalised; for time differences less than 3276 hours (about 4.5 months), it will contain zero in the years, months and days 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 hours, the days, months and years fields are used as well.

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). Because this implementation uses int16 internally, the paramters must be within the range ± 2^16 / 10.

func Parse 

func Parse(period string, normalise ...bool) (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"

By default, the value is normalised, e.g. multiple of 12 months become years so "P24M" is the same as "P2Y". However, this is done without loss of precision, so for example whole numbers of days do not contribute to the months tally because the number of days per month is variable.

Normalisation can be disabled using the optional flag.

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 ParseWithNormalise added in v1.13.0 

func ParseWithNormalise(period string, normalise bool) (Period, error)

ParseWithNormalise parses strings that specify periods using ISO-8601 rules with an option to specify whether to normalise parsed period components.

This method is deprecated and should not be used. It may be removed in a future version.

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) AddTo added in v1.8.0 

func (period Period) AddTo(t time.Time) (time.Time, bool)

AddTo adds the period to a time, returning the result. 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. Also, when the period specifies whole years, months and days (i.e. without fractions), the result is precise. However, when years, months or days contains fractions, the result is only an approximation (it assumes that all days are 24 hours and every year is 365.2425 days, as per Gregorian calendar rules).

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.2425 days as per Gregorian calendar rules) and a month being 1/12 of a that; days are all assumed to be 24 hours long.

func (Period) DurationApprox added in v1.4.0 

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.2425 days (as per Gregorian calendar rules) 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. Multiples of 7 days are shown as weeks.

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) FormatWithoutWeeks added in v1.14.0 

func (period Period) FormatWithoutWeeks() string

FormatWithoutWeeks converts the period to human-readable form using the default localisation. Multiples of 7 days are not shown as weeks.

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 other fields are negative or zero.

func (Period) IsPositive added in v1.8.0 

func (period Period) IsPositive() bool

IsPositive returns true if any field is greater than zero. By design, this also implies that all the other fields are greater than or equal to 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. This also provides support for JSON encoding.

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.

Note that after normalisation, whole multiple of 60 minutes are added to the number of hours, so the number of minutes will be reduced correspondingly.

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.

Note that after normalisation, whole multiple of 60 minutes are added to the number of hours, so the number of minutes will be reduced correspondingly.

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.

Note that after normalisation, whole multiple of 12 months are added to the number of years, so the number of months will be reduced correspondingly.

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.

Note that after normalisation, whole multiple of 12 months are added to the number of years, so the number of months will be reduced correspondingly.

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 to or from the days element, or to transfer days to or from the months 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.

Note that leap seconds are disregarded: every minute is assumed to have 60 seconds.

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, but integer overflows are silently ignored.

Bear in mind that the internal representation is limited by fixed-point arithmetic with two decimal places; 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) ScaleWithOverflowCheck added in v1.14.0 

func (period Period) ScaleWithOverflowCheck(factor float32) (Period, error)

ScaleWithOverflowCheck a period by a multiplication factor. Obviously, this can both enlarge and shrink it, and change the sign if negative. The result is normalised. An error is returned if integer overflow happened.

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) Scan added in v1.15.0 

func (period *Period) Scan(value interface{}) (err error)

Scan parses some value, which can be either string or []byte. It implements sql.Scanner, https://golang.org/pkg/database/sql/#Scanner

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.

Note that after normalisation, whole multiple of 60 seconds are added to the number of minutes, so the number of seconds will be reduced correspondingly.

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.

Note that after normalisation, whole multiple of 60 seconds are added to the number of minutes, so the number of seconds will be reduced correspondingly.

func (*Period) Set added in v1.14.3 

func (period *Period) Set(p string) error

Set enables use of Period by the flag API.

func (Period) Sign 

func (period Period) Sign() int

Sign returns +1 for positive periods and -1 for negative periods. If the period is zero, it returns zero.

func (Period) Simplify added in v1.14.0 

func (period Period) Simplify(precise bool, th ...int) Period

Simplify applies some heuristic simplifications with the objective of reducing the number of non-zero fields and thus making the rendered form simpler. It should be applied to a normalised period, otherwise the results may be unpredictable.

Note that months and days are never combined, due to the variability of month lengths. Days and hours are only combined when imprecise behaviour is selected; this is due to daylight savings transitions, during which there are more than or fewer than 24 hours per day.

The following transformation rules are applied in order:

* P1YnM becomes 12+n months for 0 < n <= 6 * P1DTnH becomes 24+n hours for 0 < n <= 6 (unless precise is true) * PT1HnM becomes 60+n minutes for 0 < n <= 10 * PT1MnS becomes 60+n seconds for 0 < n <= 10

At each step, if a fraction exists and would affect the calculation, the transformations stop. Also, when not precise,

* for periods of at least ten years, month proper fractions are discarded * for periods of at least a year, day proper fractions are discarded * for periods of at least a month, hour proper fractions are discarded * for periods of at least a day, minute proper fractions are discarded * for periods of at least an hour, second proper fractions are discarded

The thresholds can be set using the varargs th parameter. By default, the thresholds a, b, c, d are 6 months, 6 hours, 10 minutes, 10 seconds respectively as listed in the rules above.

* No thresholds is equivalent to 6, 6, 10, 10. * A single threshold a is equivalent to a, a, a, a. * Two thresholds a, b are equivalent to a, a, b, b. * Three thresholds a, b, c are equivalent to a, b, c, c. * Four thresholds a, b, c, d are used as provided.

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.2425 days as per Gregorian calendar rules) 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 approximation, assuming a year is 365.2425 days (as per Gregorian calendar rules) and a month is 1/12 of that. Whole multiples of 24 hours are also included in the calculation.

func (Period) Type added in v1.14.3 

func (period Period) Type() string

Type is for compatibility with the spf13/pflag library.

func (*Period) UnmarshalBinary 

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

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

func (*Period) UnmarshalText 

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

UnmarshalText implements the encoding.TextUnmarshaler interface for Periods. This also provides support for JSON decoding.

func (Period) Value added in v1.15.0 

func (period Period) Value() (driver.Value, error)

Value converts the period to a string. It implements driver.Valuer, https://golang.org/pkg/database/sql/driver/#Valuer

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.

Note that weeks are synthetic: they are internally represented using days. See ModuloDays(), which returns the number of days excluding whole weeks.

func (Period) WeeksFloat added in v1.4.0 

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.