timespan

package
v1.20.6 Latest Latest
Warning

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

 Go to latest Published: Feb 17, 2024 License: BSD-3-Clause Imports: 5 Imported by: 10

Documentation

Overview

Package timespan provides spans of time (TimeSpan), and ranges of dates (DateRange). Both are half-open intervals for which the start is included and the end is excluded. This allows for empty spans and also facilitates aggregating spans together.

Index

Constants

View Source 
const RFC5545DateTimeLayout = "20060102T150405"

RFC5545DateTimeLayout is the format string used by iCalendar (RFC5545). Note that "Z" is to be appended when the time is UTC.

View Source 
const RFC5545DateTimeZulu = RFC5545DateTimeLayout + "Z"

RFC5545DateTimeZulu is the UTC format string used by iCalendar (RFC5545). Note that this cannot be used for parsing with time.Parse.

View Source 
const TimestampFormat = "2006-01-02 15:04:05"

TimestampFormat is a simple format for date & time, "2006-01-02 15:04:05".

Variables

This section is empty.

Functions

This section is empty.

Types

type DateRange 

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

DateRange carries a date and a number of days and describes a range between two dates.

func DayRange added in v1.3.0 

func DayRange(day date.Date, n date.PeriodOfDays) DateRange

DayRange constructs a range of n days.

Note that n can be negative. In this case, the specified day will be the end day, which is outside of the half-open range; the last day will be the day before the day specified.

func EmptyRange 

func EmptyRange(day date.Date) DateRange

EmptyRange constructs an empty range. This is often a useful basis for further operations but note that the end date is undefined.

func NewDateRange 

func NewDateRange(start, end date.Date) DateRange

NewDateRange assembles a new date range from two dates. These are half-open, so if start and end are the same, the range spans zero (not one) day. Similarly, if they are on subsequent days, the range is one date (not two). The result is normalised.

func NewDateRangeOf 

func NewDateRangeOf(start time.Time, duration time.Duration) DateRange

NewDateRangeOf assembles a new date range from a start time and a duration, discarding the precise time-of-day information. The start time includes a location, which is not necessarily UTC. The duration can be negative.

func NewMonthOf 

func NewMonthOf(year int, month time.Month) DateRange

NewMonthOf constructs the range encompassing the whole month specified for a given year. It handles leap years correctly.

func NewYearOf 

func NewYearOf(year int) DateRange

NewYearOf constructs the range encompassing the whole year specified.

func OneDayRange 

func OneDayRange(day date.Date) DateRange

OneDayRange constructs a range of exactly one day. This is often a useful basis for further operations. Note that the last date is the same as the start date.

func (DateRange) Contains 

func (dateRange DateRange) Contains(d date.Date) bool

Contains tests whether the date range contains a specified date. Empty date ranges (i.e. zero days) never contain anything.

func (DateRange) ContainsTime 

func (dateRange DateRange) ContainsTime(t time.Time) bool

ContainsTime tests whether a given local time is within the date range. The time range is from midnight on the start day to one nanosecond before midnight on the day after the end date. Empty date ranges (i.e. zero days) never contain anything.

If a calculation needs to be 'half-open' (i.e. the end date is exclusive), simply use the expression 'dateRange.ExtendBy(-1).ContainsTime(t)'

func (DateRange) Days 

func (dateRange DateRange) Days() date.PeriodOfDays

Days returns the period represented by this range. This will never be negative.

func (DateRange) Duration 

func (dateRange DateRange) Duration() time.Duration

Duration computes the duration (in nanoseconds) from midnight at the start of the date range up to and including the very last nanosecond before midnight on the end day. The calculation is for UTC, which does not have daylight saving and every day has 24 hours.

If the range is greater than approximately 290 years, the result will hard-limit to the minimum or maximum possible duration (see time.Sub(t)).

func (DateRange) DurationIn 

func (dateRange DateRange) DurationIn(loc *time.Location) time.Duration

DurationIn computes the duration (in nanoseconds) from midnight at the start of the date range up to and including the very last nanosecond before midnight on the end day. The calculation is for the specified location, which may have daylight saving, so not every day necessarily has 24 hours. If the date range spans the day the clocks are changed, this is taken into account.

If the range is greater than approximately 290 years, the result will hard-limit to the minimum or maximum possible duration (see time.Sub(t)).

func (DateRange) End 

func (dateRange DateRange) End() date.Date

End returns the date following the last date of the range. End can be considered to be the exclusive end, i.e. the final value of a half-open range.

If the range is empty (i.e. has zero days), then the start date is returned, this being also the (half-open) end value in that case. This is more useful than the undefined result returned by Last() for empty ranges.

func (DateRange) EndTimeIn 

func (dateRange DateRange) EndTimeIn(loc *time.Location) time.Time

EndTimeIn returns the nanosecond after the end time in a specified location. Along with StartTimeIn, this gives a 'half-open' range where the start is inclusive and the end is exclusive.

func (DateRange) EndUTC 

func (dateRange DateRange) EndUTC() time.Time

EndUTC assumes that the end date is a UTC date and returns the time a nanosecond after the end time in a specified location. Along with StartUTC, this gives a 'half-open' range where the start is inclusive and the end is exclusive.

func (DateRange) ExtendBy 

func (dateRange DateRange) ExtendBy(days date.PeriodOfDays) DateRange

ExtendBy extends (or reduces) the date range by moving the end date. A negative parameter is allowed and this may cause the range to become inverted (i.e. the mark date becomes the end date instead of the start date).

func (DateRange) ExtendByPeriod 

func (dateRange DateRange) ExtendByPeriod(delta period.Period) DateRange

ExtendByPeriod extends (or reduces) the date range by moving the end date. A negative parameter is allowed and this may cause the range to become inverted (i.e. the mark date becomes the end date instead of the start date).

func (DateRange) IsEmpty 

func (dateRange DateRange) IsEmpty() bool

IsEmpty returns true if this has a starting date but the range is empty (zero days).

func (DateRange) IsZero 

func (dateRange DateRange) IsZero() bool

IsZero returns true if this has a zero start date and the the range is empty. Usually this is because the range was created via the zero value.

func (DateRange) Last 

func (dateRange DateRange) Last() date.Date

Last returns the last date (inclusive) represented by this range. Be careful because if the range is empty (i.e. has zero days), then the last is undefined so an empty date is returned. Therefore it is often more useful to use End() instead of Last(). See also IsEmpty().

func (DateRange) Merge 

func (dateRange DateRange) Merge(otherRange DateRange) DateRange

Merge combines two date ranges by calculating a date range that just encompasses them both. There are two special cases.

Firstly, if one range is entirely contained within the other range, the larger of the two is returned. Otherwise, the result is from the start of the earlier one to the end of the later one, even if the two ranges don't overlap.

Secondly, if either range is the zero value (see IsZero), it is excluded from the merge and the other range is returned unchanged.

func (DateRange) Normalise 

func (dateRange DateRange) Normalise() DateRange

Normalise ensures that the number of days is zero or positive. The normalised date range is returned; in this value, the mark date is the same as the start date.

func (DateRange) ShiftBy 

func (dateRange DateRange) ShiftBy(days date.PeriodOfDays) DateRange

ShiftBy moves the date range by moving both the start and end dates similarly. A negative parameter is allowed.

func (DateRange) ShiftByPeriod 

func (dateRange DateRange) ShiftByPeriod(delta period.Period) DateRange

ShiftByPeriod moves the date range by moving both the start and end dates similarly. A negative parameter is allowed.

Any time component is ignored. Therefore, be careful with periods containing more that 24 hours in the hours/minutes/seconds fields. These will not be normalised for you; if you want this behaviour, call delta.Normalise(false) on the input parameter.

For example, PT24H adds nothing, whereas P1D adds one day as expected. To convert a period such as PT24H to its equivalent P1D, use delta.Normalise(false) as the input.

func (DateRange) Start 

func (dateRange DateRange) Start() date.Date

Start returns the earliest date represented by this range.

func (DateRange) StartTimeIn 

func (dateRange DateRange) StartTimeIn(loc *time.Location) time.Time

StartTimeIn returns the start time in a specified location.

func (DateRange) StartUTC 

func (dateRange DateRange) StartUTC() time.Time

StartUTC assumes that the start date is a UTC date and gets the start time of that date, as UTC. It returns midnight on the first day of the range.

func (DateRange) String 

func (dateRange DateRange) String() string

String describes the date range in human-readable form.

func (DateRange) TimeSpanIn 

func (dateRange DateRange) TimeSpanIn(loc *time.Location) TimeSpan

TimeSpanIn obtains the time span corresponding to the date range in a specified location. The result is normalised.

type TimeSpan 

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

TimeSpan holds a span of time between two instants with a 1 nanosecond resolution. It is implemented using a time.Duration, therefore is limited to a maximum span of 290 years.

func NewTimeSpan 

func NewTimeSpan(t1, t2 time.Time) TimeSpan

NewTimeSpan creates a new time span from two times. The start and end can be in either order; the result will be normalised. The inputs are half-open: the start is included and the end is excluded.

func ParseRFC5545InLocation added in v1.3.0 

func ParseRFC5545InLocation(text string, loc *time.Location) (TimeSpan, error)

ParseRFC5545InLocation parses a string as a timespan. The string must contain either of 

time "/" time
time "/" period

If the input time(s) ends in "Z", the location is UTC (as per RFC5545). Otherwise, the specified location will be used for the resulting times; this behaves the same as time.ParseInLocation.

func TimeSpanOf added in v1.3.0 

func TimeSpanOf(start time.Time, d time.Duration) TimeSpan

TimeSpanOf creates a new time span at a specified time and duration.

func ZeroTimeSpan 

func ZeroTimeSpan(start time.Time) TimeSpan

ZeroTimeSpan creates a new zero-duration time span at a specified time.

func (TimeSpan) Contains 

func (ts TimeSpan) Contains(t time.Time) bool

Contains tests whether a given moment of time is enclosed within the time span. The start time is inclusive; the end time is exclusive. If t has a different locality to the time-span, it is adjusted accordingly.

func (TimeSpan) DateRangeIn 

func (ts TimeSpan) DateRangeIn(loc *time.Location) DateRange

DateRangeIn obtains the date range corresponding to the time span in a specified location. The result is normalised.

func (TimeSpan) Duration 

func (ts TimeSpan) Duration() time.Duration

Duration gets the duration of the time span.

func (TimeSpan) End 

func (ts TimeSpan) End() time.Time

End gets the end time of the time span. Strictly, this is one nanosecond after the range of time included in the time span; this implements the half-open model.

func (TimeSpan) Equal added in v1.3.0 

func (ts TimeSpan) Equal(us TimeSpan) bool

Equal reports whether ts and us represent the same time start and duration. Two times can be equal even if they are in different locations. For example, 6:00 +0200 CEST and 4:00 UTC are Equal.

func (TimeSpan) ExtendBy 

func (ts TimeSpan) ExtendBy(d time.Duration) TimeSpan

ExtendBy lengthens the time span by a specified amount. The parameter may be negative, in which case it is possible that the end of the time span will appear to be before the start. However, the result is normalised so that the resulting start is the lesser value.

func (TimeSpan) ExtendWithoutWrapping 

func (ts TimeSpan) ExtendWithoutWrapping(d time.Duration) TimeSpan

ExtendWithoutWrapping lengthens the time span by a specified amount. The parameter may be negative, but if its magnitude is large than the time span's duration, it will be truncated so that the result has zero duration in that case. The start time is never altered.

func (TimeSpan) Format added in v1.3.0 

func (ts TimeSpan) Format(layout, separator string, useDuration bool) string

Format returns a textual representation of the time value formatted according to layout. It produces a string containing the start and end time. Or, if useDuration is true, it returns a string containing the start time and the duration.

The layout string is as specified for time.Format. If it doesn't have a timezone element ("07" or "Z") and the times in the timespan are UTC, the "Z" zulu indicator is added. This is as required by iCalendar (RFC5545).

Also, if the layout is blank, it defaults to RFC5545DateTimeLayout.

The separator between the two parts of the result would be "/" for RFC5545, but can be anything.

func (TimeSpan) FormatRFC5545 added in v1.3.0 

func (ts TimeSpan) FormatRFC5545(useDuration bool) string

FormatRFC5545 formats the timespan as a string containing the start time and end time, or the start time and duration, if useDuration is true. The two parts are separated by slash. The time(s) is expressed as UTC zulu. This is as required by iCalendar (RFC5545).

func (TimeSpan) In 

func (ts TimeSpan) In(loc *time.Location) TimeSpan

In returns a TimeSpan adjusted from its current location to a new location. Because location is considered to be a presentational attribute, the actual time itself is not altered by this function. This matches the behaviour of time.Time.In(loc).

func (TimeSpan) IsEmpty 

func (ts TimeSpan) IsEmpty() bool

IsEmpty returns true if this is an empty time span (zero duration).

func (TimeSpan) MarshalText added in v1.3.0 

func (ts TimeSpan) MarshalText() (text []byte, err error)

MarshalText formats the timespan as a string using, using RFC5545 layout. This implements the encoding.TextMarshaler interface.

func (TimeSpan) Merge 

func (ts TimeSpan) Merge(other TimeSpan) TimeSpan

Merge combines two time spans by calculating a time span that just encompasses them both. As a special case, if one span is entirely contained within the other span, the larger of the two is returned. Otherwise, the result is the start of the earlier one to the end of the later one, even if the two spans don't overlap.

func (TimeSpan) Normalise 

func (ts TimeSpan) Normalise() TimeSpan

Normalise ensures that the mark time is at the start time and the duration is positive. The normalised time span is returned.

func (TimeSpan) ShiftBy 

func (ts TimeSpan) ShiftBy(d time.Duration) TimeSpan

ShiftBy moves the time span by moving both the start and end times similarly. A negative parameter is allowed.

func (TimeSpan) Start 

func (ts TimeSpan) Start() time.Time

Start gets the end time of the time span.

func (TimeSpan) String 

func (ts TimeSpan) String() string

String produces a human-readable description of a time span.

func (*TimeSpan) UnmarshalText added in v1.3.0 

func (ts *TimeSpan) UnmarshalText(text []byte) (err error)

UnmarshalText parses a string as a timespan. It expects RFC5545 layout.

If the receiver timespan is non-nil and has a time with a location, this location is used for parsing. Otherwise time.Local is used.

This implements the encoding.TextUnmarshaler interface.

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.