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 (dateRange DateRange) Contains(d 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
- 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(period period.Period) DateRange
- func (dateRange DateRange) IsEmpty() bool
- func (dateRange DateRange) IsZero() bool
- func (dateRange DateRange) Last() Date
- func (thisRange DateRange) Merge(thatRange DateRange) DateRange
- func (dateRange DateRange) Normalise() DateRange
- func (dateRange DateRange) ShiftBy(days PeriodOfDays) DateRange
- func (dateRange DateRange) ShiftByPeriod(period period.Period) DateRange
- func (dateRange DateRange) Start() 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) ExtendBy(d time.Duration) TimeSpan
- func (ts TimeSpan) ExtendWithoutWrapping(d time.Duration) TimeSpan
- func (ts TimeSpan) In(loc *time.Location) TimeSpan
- func (ts TimeSpan) IsEmpty() bool
- 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
Constants ¶
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 EmptyRange ¶
func EmptyRange(day 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) 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).
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 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) DateRange
OneDayRange constructs a range of exactly one day. This is often a useful basis for further operations. Note that the end 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
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 ¶
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 ¶
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 ¶
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 ¶
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
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 ¶
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 ¶
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 ¶
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.
func (DateRange) Start ¶
func (dateRange DateRange) Start() 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 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 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) 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) 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) 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.
Source Files