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
- type DateRange
- func BetweenDates(start, end date.Date) DateRange
- func DayRange(day date.Date, n PeriodOfDays) DateRange
- func EmptyRange(day date.Date) DateRange
- func NewDateRangeOf(start time.Time, duration time.Duration) DateRange
- func NewDateRangePeriod(start time.Time, p period.Period) DateRange
- func NewMonthOf(year int, month time.Month) DateRange
- func NewYearOf(year int) DateRange
- func OneDayRange(day date.Date) DateRange
- func (dateRange DateRange) Contains(d date.Date) bool
- func (dateRange DateRange) ContainsTime(t time.Time) bool
- func (dateRange DateRange) Days() PeriodOfDays
- func (dateRange DateRange) Duration() time.Duration
- func (dateRange DateRange) DurationIn(loc *time.Location) time.Duration
- func (dateRange DateRange) End() date.Date
- func (dateRange DateRange) EndTimeIn(loc *time.Location) time.Time
- func (dateRange DateRange) EndUTC() time.Time
- func (dateRange DateRange) ExtendBy(days PeriodOfDays) DateRange
- func (dateRange DateRange) ExtendByPeriod(delta period.Period) DateRange
- func (dateRange DateRange) IsEmpty() bool
- func (dateRange DateRange) IsZero() bool
- func (dateRange DateRange) Last() date.Date
- func (dateRange DateRange) Merge(otherRange DateRange) DateRange
- func (dateRange DateRange) ShiftBy(days PeriodOfDays) DateRange
- func (dateRange DateRange) ShiftByPeriod(delta period.Period) DateRange
- func (dateRange DateRange) Start() date.Date
- func (dateRange DateRange) StartTimeIn(loc *time.Location) time.Time
- func (dateRange DateRange) StartUTC() time.Time
- func (dateRange DateRange) String() string
- func (dateRange DateRange) TimeSpanIn(loc *time.Location) TimeSpan
- type PeriodOfDays
- type TimeSpan
- func (ts TimeSpan) Contains(t time.Time) bool
- func (ts TimeSpan) DateRangeIn(loc *time.Location) DateRange
- func (ts TimeSpan) Duration() time.Duration
- func (ts TimeSpan) End() time.Time
- func (ts TimeSpan) Equal(us TimeSpan) bool
- func (ts TimeSpan) ExtendBy(d time.Duration) TimeSpan
- func (ts TimeSpan) ExtendWithoutWrapping(d time.Duration) TimeSpan
- func (ts TimeSpan) Format(layout, separator string, useDuration bool) string
- func (ts TimeSpan) FormatRFC5545(useDuration bool) string
- func (ts TimeSpan) In(loc *time.Location) TimeSpan
- func (ts TimeSpan) IsEmpty() bool
- func (ts TimeSpan) Mark() time.Time
- func (ts TimeSpan) MarshalText() (text []byte, err error)
- func (ts TimeSpan) Merge(other TimeSpan) TimeSpan
- func (ts TimeSpan) Normalise() TimeSpan
- func (ts TimeSpan) ShiftBy(d time.Duration) TimeSpan
- func (ts TimeSpan) Start() time.Time
- func (ts TimeSpan) String() string
- func (ts *TimeSpan) UnmarshalText(text []byte) (err error)
Constants ¶
const RFC5545DateTimeLayout = "20060102T150405"
RFC5545DateTimeLayout is the format string used by iCalendar (RFC5545). Note that "Z" is to be appended when the time is UTC.
No dashes are used; this follows ISO-8601 Basic Format practice.
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.
No dashes are used; this follows ISO-8601 Basic Format practice.
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 BetweenDates ¶
func BetweenDates(start, end date.Date) DateRange
BetweenDates 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 DayRange ¶
func DayRange(day date.Date, n PeriodOfDays) DateRange
DayRange constructs a range of n days.
Note that n can be negative, in which case the start day will be shifted to the corresponding earlier date.
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 NewDateRangeOf ¶
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 NewDateRangePeriod ¶
NewDateRangePeriod assembles a new date range from a start time and a period, discarding the precise time-of-day information. The start time includes a location, which is not necessarily UTC. The period can be negative.
func NewMonthOf ¶
NewMonthOf constructs the range encompassing the whole month specified for a given year. It handles leap years correctly.
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 ¶
Contains tests whether the date range contains a specified date. Empty date ranges (i.e. zero days) never contain anything.
func (DateRange) ContainsTime ¶
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() PeriodOfDays
Days returns the period represented by this range. This will never be negative.
func (DateRange) 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 ¶
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 returned date is the same as the start date, 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 ¶
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 ¶
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 PeriodOfDays) DateRange
ExtendBy extends (or reduces) the date range by moving the end date. A negative parameter is allowed.
func (DateRange) ExtendByPeriod ¶
ExtendByPeriod extends (or reduces) the date range by moving the end date. A negative parameter is allowed.
func (DateRange) IsEmpty ¶
IsEmpty returns true if this has a starting date but the range is empty (zero days).
func (DateRange) IsZero ¶
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 the zero date is returned. Therefore, it is often more useful to use End() instead of Last(). See also IsEmpty().
func (DateRange) Merge ¶
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) ShiftBy ¶
func (dateRange DateRange) ShiftBy(days PeriodOfDays) DateRange
ShiftBy moves the date range by moving both the start and end dates similarly. A negative parameter is allowed.
func (DateRange) ShiftByPeriod ¶
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 ¶
StartTimeIn returns the start time in a specified location.
func (DateRange) StartUTC ¶
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.
type PeriodOfDays ¶
type PeriodOfDays int
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 292 years.
It supports RFC5545 timespan representations.
func BetweenTimes ¶
BetweenTimes 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 ¶
ParseRFC5545InLocation parses a string as a timespan. The string must contain either of
time "/" time time "/" period period "/" time
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. Its expected format is RFC5545DateTimeLayout (with optional "Z").
The period can optionally be preceded by '+' or '-'. If the period comes first, it is treated as being the same as a negative period after the '/'.
RFC5545 does not allow the period to contain years or months. However, in this implementation they are permitted but discouraged.
func TimeSpanOf ¶
TimeSpanOf creates a new time span at a specified time and duration. The duration can be negative, e.g. for an alarm event before the mark time.
func ZeroTimeSpan ¶
ZeroTimeSpan creates a new zero-duration time span at a specified time.
func (TimeSpan) Contains ¶
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 ¶
DateRangeIn obtains the date range corresponding to the time span in a specified location. The result is normalised.
func (TimeSpan) End ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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) Mark ¶
Mark gets the time marked by this timespan. Typically this is the same as Start, but it's the same as End for time spans with negative duration.
func (TimeSpan) MarshalText ¶
MarshalText formats the timespan as a string using, using RFC5545 layout. This implements the encoding.TextMarshaler interface.
func (TimeSpan) Merge ¶
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 ¶
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 ¶
ShiftBy moves the time span by moving both the start and end times similarly. A negative parameter is allowed.
func (*TimeSpan) UnmarshalText ¶
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.