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 DayRange(day date.Date, n date.PeriodOfDays) DateRange
- func EmptyRange(day date.Date) DateRange
- func NewDateRange(start, end date.Date) DateRange
- func NewDateRangeOf(start time.Time, duration time.Duration) 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() date.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 date.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) Normalise() DateRange
- func (dateRange DateRange) ShiftBy(days date.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 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) 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.
const RFC5545DateTimeUTC = RFC5545DateTimeLayout + "Z"
RFC5545DateTimeUTC is the UTC format string used by iCalendar (RFC5545). Note that this cannot be used for parsing with time.Parse.
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 isodate and a number of days and describes a range between two isodates.
func DayRange ¶
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 ¶
EmptyRange constructs an empty range. This is often a useful basis for further operations but note that the end isodate is undefined.
func NewDateRange ¶
NewDateRange assembles a new isodate range from two isodates. 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 isodate (not two). The result is normalised.
func NewDateRangeOf ¶
NewDateRangeOf assembles a new isodate 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 ¶
NewMonthOf constructs the range encompassing the whole month specified for a given year. It handles leap years correctly.
func OneDayRange ¶
OneDayRange constructs a range of exactly one day. This is often a useful basis for further operations. Note that the last isodate is the same as the start isodate.
func (DateRange) Contains ¶
Contains tests whether the isodate range contains a specified isodate. Empty isodate ranges (i.e. zero days) never contain anything.
func (DateRange) ContainsTime ¶
ContainsTime tests whether a given local time is within the isodate range. The time range is from midnight on the start day to one nanosecond before midnight on the day after the end isodate. Empty isodate ranges (i.e. zero days) never contain anything.
If a calculation needs to be 'half-open' (i.e. the end isodate 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 ¶
Duration computes the duration (in nanoseconds) from midnight at the start of the isodate 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 isodate 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 isodate 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 ¶
End returns the isodate following the last isodate 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 isodate 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 ¶
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 isodate is a UTC isodate 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 isodate range by moving the end isodate. A negative parameter is allowed and this may cause the range to become inverted (i.e. the mark isodate becomes the end isodate instead of the start isodate).
func (DateRange) ExtendByPeriod ¶
ExtendByPeriod extends (or reduces) the isodate range by moving the end isodate. A negative parameter is allowed and this may cause the range to become inverted (i.e. the mark isodate becomes the end isodate instead of the start isodate).
func (DateRange) IsEmpty ¶
IsEmpty returns true if this has a starting isodate but the range is empty (zero days).
func (DateRange) IsZero ¶
IsZero returns true if this has a zero start isodate and the the range is empty. Usually this is because the range was created via the zero value.
func (DateRange) Last ¶
Last returns the last isodate (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 isodate is returned. Therefore it is often more useful to use End() instead of Last(). See also IsEmpty().
func (DateRange) Merge ¶
Merge combines two isodate ranges by calculating a isodate 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 ¶
Normalise ensures that the number of days is zero or positive. The normalised isodate range is returned; in this value, the mark isodate is the same as the start isodate.
func (DateRange) ShiftBy ¶
func (dateRange DateRange) ShiftBy(days date.PeriodOfDays) DateRange
ShiftBy moves the isodate range by moving both the start and end isodates similarly. A negative parameter is allowed.
func (DateRange) ShiftByPeriod ¶
ShiftByPeriod moves the isodate range by moving both the start and end isodates 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) StartTimeIn ¶
StartTimeIn returns the start time in a specified location.
func (DateRange) StartUTC ¶
StartUTC assumes that the start isodate is a UTC isodate and gets the start time of that isodate, as UTC. It returns midnight on the first day of the range.
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 ¶
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 NewTimeSpanOf ¶
NewTimeSpanOf creates a new time span at a specified time and duration.
func ParseRFC5545InLocation ¶
ParseRFC5545InLocation parses a string as a timespan. The string must contain either of
time "/" time time "/" period
The timestamp package will assume UTC for timestamps lacking a timezone indicator. The timespanreturned will have its tims set to the location specified.
func ParseRFC5545InUTC ¶
ParseRFC5545InUTC parses a string as a timespan. The string must contain either of
time "/" time time "/" period
The timestamp package will assume UTC for timestamps lacking a timezone indicator. The timespanreturned will have its tims set to UTC.
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" UTC 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. 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) 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.
Source Files