datetime

package module
v0.0.0-...-052fa94 Latest Latest
Warning

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

 Go to latest Published: Jan 14, 2026 License: Apache-2.0 Imports: 9 Imported by: 5

README

Package cloudeng.io/datetime

import cloudeng.io/datetime

Package datetime provides support for working with dates, the time of day and associated ranges.

Variables

ErrInvalidISO8601Duration
ErrInvalidISO8601Duration = errors.New("invalid ISO8601 duration")

Functions

Func AsISO8601Period
func AsISO8601Period(dur time.Duration) string
Func ContextWithYearPlace
func ContextWithYearPlace(ctx context.Context, yp YearPlace) context.Context

ContextWithYearPlace returns a new context with the given YearPlace value stored in it.

Func DaysInFeb
func DaysInFeb(year int) uint8

DaysInFeb returns the number of days in February for the given year.

Func DaysInMonth
func DaysInMonth(year int, month Month) uint8

DaysInMonth returns the number of days in the given month for the given year.

Func DaysInYear
func DaysInYear(year int) int

DaysInYear returns the number of days in the given year.dc

Func IsLeap
func IsLeap(year int) bool

IsLeap returns true if the given year is a leap year.

Func ParseISO8601Period
func ParseISO8601Period(dur string) (time.Duration, error)

ParseISO8601Period parses an ISO 8601 'period' of the form [-]PnYnMnDTnHnMnS

Func Time
func Time(yp YearPlace, date Date, tod TimeOfDay) time.Time

Time returns a time.Time for the specified YearAndPlace, Date and TimeOfDay using time.Date, and hence, implicitly normalizing the date.

Types

Type CalendarDate
type CalendarDate uint32

CalendarDate represents a date with a year, month and day. Year is represented in the top 16 bits and Date in the lower 16 bits.

Functions
func CalendarDateFromTime(t time.Time) CalendarDate

CalendarDateFromTime creates a new CalendarDate from the specified time.Time.

func NewCalendarDate(year int, month Month, day int) CalendarDate

NewCalendarDate creates a new CalendarDate from the specified year, month and day. Year must be in the range 0..65535, month in the range 0..12 and day in the range 0..31.

func NewCalendarDateFromTime(t time.Time) CalendarDate

NewCalendarDateFromTime creates a new CalendarDate from the specified time.Time.

func ParseAnyDate(year int, val string) (CalendarDate, error)

ParseAnyDate parses a date in the format '01/02/2006', 'Jan-02-2006', '01/02', 'Jan-02' or '01'. The year argument is ignored for the '01/02/2006' and 'Jan-02-2006' formats. Jan-02, 01/02 are treated as month and day and the year argument is used to set the year.

func ParseCalendarDate(val string) (CalendarDate, error)

ParseCalendarDate a numeric calendar date in formats 'Jan-02-2006' with error checking for valid month and day.

func ParseNumericCalendarDate(val string) (CalendarDate, error)

ParseNumericCalendarDate a numeric calendar date in formats '01/02/2006' with error checking for valid month and day.

Methods
func (cd CalendarDate) Date() Date

Date returns the Date for the CalendarDate.

func (cd CalendarDate) Day() int

func (cd CalendarDate) DayOfYear() int

func (cd CalendarDate) IsDST(loc *time.Location) bool

IsDST returns true if the date is within daylight savings time for the specified location assuming that the time is 12:00 hours. DST starts at 2am and ends at 3am.

func (cd CalendarDate) Month() Month

func (cd CalendarDate) Normalize(firstOfMonth bool) CalendarDate

Normalize adjusts the date for the given year. If the day is zero then firstOfMonth is used to determine the interpretation of the day. If firstOfMonth is true then the day is set to the first day of the month, otherwise it is set to the last day of the month. Month is normalized to be in the range 1-12.

func (cd *CalendarDate) Parse(val string) error

func (cd CalendarDate) String() string

func (cd CalendarDate) Time(tod TimeOfDay, loc *time.Location) time.Time

func (cd CalendarDate) Tomorrow() CalendarDate

Tomorrow returns the CalendarDate for the day after the specified date, wrapping to the next month or year as needed.

func (cd CalendarDate) Year() int

func (cd CalendarDate) YearDay() YearDay

func (cd CalendarDate) Yesterday() CalendarDate

Yesterday returns the CalendarDate for the day before the specified date, wrapping to the previous month or year as needed.

Type CalendarDateList
type CalendarDateList []CalendarDate

CalendarDateList represents a list of CalendarDate values, it can sorted and searched using the slices package.

Methods
func (cdl CalendarDateList) Merge() CalendarDateRangeList

Merge returns a new list of date ranges that contains merged consecutive calendar dates into ranges. The dates are normalized using date.Normalize(true). The date list is assumed to be sorted.

func (cdl CalendarDateList) String() string
Type CalendarDateRange
type CalendarDateRange uint64

CalendarDateRange represents a range of CalendarDate values.

Functions
func NewCalendarDateRange(from, to CalendarDate) CalendarDateRange

NewCalendarDateRange returns a CalendarDateRange for the from/to dates. If the from date is later than the to date then they are swapped. The resulting from and to dates are then normalized using calendardate.Normalize(year, true) for the from date and calendardate.Normalize(year, false) for the to date.

Methods
func (cdr CalendarDateRange) Bound(bound CalendarDateRange) CalendarDateRange

Bound returns a new CalendarDateRange that is bounded by the specified CalendarDateRange, namely the from date is the later of the two from dates and the to date is the earlier of the two to dates. If the resulting range is empty then the zero value is returned.

func (cdr CalendarDateRange) DateRange(year int) DateRange

func (cdr CalendarDateRange) Dates() iter.Seq[CalendarDate]

Dates returns an iterator that yields each Date in the range for the given year.

func (cdr CalendarDateRange) DatesConstrained(dc Constraints) iter.Seq[CalendarDate]

DatesConstrained returns an iterator that yields each Date in the range for the given year constrained by the given DateConstraints.

func (cdr CalendarDateRange) Days() iter.Seq[YearDay]

Days returns an iterator that yields each day in the range for the given year.

func (cdr CalendarDateRange) DaysConstrained(dc Constraints) iter.Seq[YearDay]

DaysConstrained returns an iterator that yields each day in the range for the given year constrained by the given DateConstraints.

func (cdr CalendarDateRange) From() CalendarDate

From returns the start date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

func (cd CalendarDateRange) Include(d CalendarDate) bool

Include returns true if the specified date is within the range.

func (cdr *CalendarDateRange) Parse(val string) error

Parse ranges in formats '01/2006:03/2007', 'Jan-2006:Mar-2007', '01/02/2006:03/04/2007' or 'Jan-02-2006:Mar-04-2007', If the from day is zero then it is treated as the first day of the month. If the from day is 29 for a non-leap year then it is left as 29. If the to day is zero then it is treated as the last day of the month taking the year into account for Feb. The start date must be before the end date after normalization as per the above rules.

func (cdr CalendarDateRange) RangesConstrained(dc Constraints) iter.Seq[CalendarDateRange]

Ranges returns an iterator that yields each DateRange in the range for the given year constrained by the given DateConstraints.

func (cdr CalendarDateRange) String() string

func (cdr CalendarDateRange) To() CalendarDate

To returns the end date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

func (cdr CalendarDateRange) Truncate(year int) DateRange

Truncate returns a DateRange that is truncated to the start or end of specified year iff the range spans consecutive years, otherwise it returns DateRange(0).

Type CalendarDateRangeList
type CalendarDateRangeList []CalendarDateRange
Methods
func (cdrl CalendarDateRangeList) Bound(bound CalendarDateRange) CalendarDateRangeList

Bound returns a new list of date ranges that are bounded by the supplied calendar date range.

func (cdrl CalendarDateRangeList) Merge() CalendarDateRangeList

Merge returns a new list of date ranges that contains merged consecutive overlapping ranges. The date list is assumed to be sorted.

func (cdrl CalendarDateRangeList) MergeMonths(year int, months MonthList) CalendarDateRangeList

MergeMonths returns a merged list of date ranges that contains the specified months for the given year.

func (cdrl *CalendarDateRangeList) Parse(ranges []string) error

Parse parses a list of ranges in the format expected by CalendarDateRange.Parse.

Type Constraints
type Constraints struct {
	Weekdays       bool                 // If true, include weekdays
	Weekends       bool                 // If true, include weekends
	Custom         DateList             // If non-empty, exclude these dates
	CustomCalendar CalendarDateList     // If non-empty, exclude these calendar dates
	Dynamic        DynamicDateRangeList // If non-nil, exclude dates based on the evaluation of the dynamic date range functions.
}

Constraints represents constraints on date values such as weekends or custom dates to exclude. Custom dates take precedence over weekdays and weekends.

Methods
func (dc Constraints) Empty() bool

func (dc Constraints) Include(when time.Time) bool

Include returns true if the given date satisfies the constraints. Custom dates are evaluated before weekdays and weekends. An empty set Constraints will return true, ie. include all dates.

func (dc Constraints) String() string
Type Date
type Date uint16

Date as a uint16 with the month in the high byte and the day in the low byte.

Functions
func DateFromTime(when time.Time) Date

DateFromTime returns the Date for the given time.Time.

func NewDate(month Month, day int) Date

NewDate returns a Date for the given month and day. Both are assumed to valid for the context in which they are used. Normalize should be used to to adjust for a given year and interpretation of zero day value.

func ParseDate(val string) (Date, error)

ParseDate parses a date in the forma 'Jan-02' with error checking for valid month and day (Feb is treated as having 29 days)

func ParseNumericDate(val string) (Date, error)

Parse a numeric date in the format '01/02' with error checking for valid month and day (Feb is treated as having 29 days)

Methods
func (d Date) CalendarDate(year int) CalendarDate

func (d Date) Day() int

Day returns the day for the date.

func (d Date) DayOfYear(year int) int

DayOfYear returns the day of the year for the given year as 1-365 for non-leap years and 1-366 for leap years. It will silently treat days that exceed those for a given month to the last day of that month. A day of zero can be used to refer to the last day of the previous month.

func (d Date) Month() Month

Month returns the month for the date.

func (d Date) Normalize(year int, firstOfMonth bool) Date

Normalize adjusts the date for the given year. If the day is zero then firstOfMonth is used to determine the interpretation of the day. If firstOfMonth is true then the day is set to the first day of the month, otherwise it is set to the last day of the month. Month is normalized to be in the range 1-12.

func (d *Date) Parse(val string) error

Parse date in formats '01', 'Jan','01/02' or 'Jan-02' with error checking for valid month and day (Feb is treated as having 29 days)

func (d Date) String() string

func (d Date) Tomorrow(year int) Date

Tomorrow returns the date of the next day. It will silently treat days that exceed those for a given month as the last day of that month. 12/31 wraps to 1/1.

func (d Date) YearDay(year int) YearDay

func (d Date) Yesterday(year int) Date

Yesterday returns the date of the previous day. 1/1 wraps to 12/31.

Type DateList
type DateList []Date

DateList represents a list of Dates, it can be sorted and searched the slices package.

Methods
func (dl DateList) ExpandMonths(year int) DateRangeList

func (dl DateList) Merge(year int) DateRangeList

Merge returns a new list of date ranges that contains merged consecutive dates into ranges. All dates are normalized using date.Normalize(year, true). The date list is assumed to be sorted.

func (dl *DateList) Parse(val string) error

Parse a comma separated list of Dates.

func (dl DateList) String() string
Type DateRange
type DateRange uint32

DateRange represents a range of dates, inclusive of the start and end dates. NewDateRange and Parse create or initialize a DateRange. The from and to months are stored in the top 8 bits and the from and to days in the lower 8 bits to allow for sorting.

Functions
func DateRangeYear() DateRange

DateRangeYear returns a DateRange for the entire year.

func NewDateRange(from, to Date) DateRange

NewDateRange returns a DateRange for the from/to dates for the specified year. If the from date is later than the to date then they are swapped.

Methods
func (dr DateRange) Bound(year int, bound DateRange) DateRange

Bound returns a new DateRange that is bounded by the specified DateRange, namely the from date is the later of the two from dates and the to date is the earlier of the two to dates. If the resulting range is empty then the zero value is returned.

func (dr DateRange) CalendarDateRange(year int) CalendarDateRange

CalendarDateRange returns a CalendarDateRange for the DateRange for the specified year. The date range is first normalized to the specified year before creating the CalendarDateRange.

func (dr DateRange) Dates(year int) func(yield func(CalendarDate) bool)

Dates returns an iterator that yields each CalendarDate in the range for the given year. All of the CalendarDate values will have the same year.

func (dr DateRange) DatesConstrained(year int, dc Constraints) func(yield func(CalendarDate) bool)

DatesConstrained returns an iterator that yields each CalendarDate in the range for the given year constrained by the given DateConstraints. All of the CalendarDate values will have the same year.

func (dr DateRange) Days(year int) func(yield func(YearDay) bool)

Days returns an iterator that yields each day in the range for the given year.

func (dr DateRange) DaysConstrained(year int, dc Constraints) func(yield func(YearDay) bool)

DaysConstrained returns an iterator that yields each day in the range for the given year constrained by the given DateConstraints.

func (dr DateRange) Equal(year int, dr2 DateRange) bool

Equal returns true if the two DateRange values are equal for the given year. Both ranges are first normalized before comparison.

func (dr DateRange) From(year int) Date

From returns the start date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

func (dr DateRange) Include(d Date) bool

Include returns true if the specified date is within the range.

func (dr DateRange) Normalize(year int) DateRange

Normalize rerturns a new DateRange with the from and to dates normalized to the specified year. This is equivalent to calling date.Normalize(year, true) for the from date and date.Normalize(year, false) for the to date.

func (dr *DateRange) Parse(val string) error

Parse ranges in formats '01:03', 'Jan:Mar', '01/02:03-04' or 'Jan-02:Mar-04'.

func (dr DateRange) RangesConstrained(year int, dc Constraints) func(yield func(CalendarDateRange) bool)

Ranges returns an iterator that yields each DateRange in the range for the given year constrained by the given DateConstraints.

func (dr DateRange) String() string

func (dr DateRange) To(year int) Date

To returns the end date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

Type DateRangeList
type DateRangeList []DateRange

DateRangeList represents a list of DateRange values, it can be sorted and searched using the slices package.

Methods
func (drl DateRangeList) Bound(year int, bound DateRange) DateRangeList

Bound returns a new list of date ranges that are bounded by the specified date range.

func (drl DateRangeList) Equal(year int, dr2 DateRangeList) bool

Equal returns true if the two DateRangeList values are equal for the given year.

func (drl DateRangeList) Merge(year int) DateRangeList

Merge returns a new list of date ranges that contains merged consecutive overlapping ranges. The date list is assumed to be sorted.

func (drl DateRangeList) MergeMonths(year int, months MonthList) DateRangeList

MergeMonths returns a merged list of date ranges that contains the specified months for the given year.

func (drl *DateRangeList) Parse(ranges []string) error

Parse ranges in formats '01:03', 'Jan:Mar', '01-02:03-04' or 'Jan-02:Mar-04'. The parsed list is sorted and without duplicates. If the start date is identical then the end date is used to determine the order.

func (drl DateRangeList) String() string
Type DynamicDateRange
type DynamicDateRange interface {
	Name() string
	Evaluate(year int) CalendarDateRange
}

DynamicDateRange is a function that returns a DateRange for a given year and is intended to be evaluated once per year to calculate events such as solstices, seasons or holidays.

Type DynamicDateRangeList
type DynamicDateRangeList []DynamicDateRange
Methods
func (dl DynamicDateRangeList) Evaluate(year int) []CalendarDateRange

func (dl DynamicDateRangeList) String() string
Type DynamicTimeOfDay
type DynamicTimeOfDay interface {
	Name() string
	Evaluate(cd CalendarDate, yp Place) TimeOfDay
}

DynamicTimeOfDay is a function that returns a TimeOfDay for a given date and is intended to be evaluated once per day to calculate events such as sunrise, sunset etc.

Type Month
type Month uint8

Month as a uint8

Constants
January, February, March, April, May, June, July, August, September, October, November, December
January Month = 1 + iota
February
March
April
May
June
July
August
September
October
November
December
Functions
func MirrorMonth(month Month) Month

MirrorMonth returns the month that is equidistant from the summer or winter solstice for the specified month. For example, the mirror month for January is November, and the mirror month for February is October.

func ParseMonth(val string) (Month, error)

ParseMonth parses a month name of the form "Jan" to "Dec" or any other longer prefixes of "January" to "December" in either lower or upper case.

func ParseNumericMonth(val string) (Month, error)

ParseNumericMonth parses a 1 or 2 digit numeric month value in the range 1-12.

Methods
func (m Month) Days(year int) uint8

func (m *Month) Parse(val string) error

Parse parses a month in either numeric or month name format.

func (m Month) String() string
Type MonthList
type MonthList []Month

MonthList represents a list of Months, it can be sorted and searched the slices package.

Methods
func (ml *MonthList) Parse(val string) error

Parse val in formats 'Jan,12,Nov'. The parsed list is sorted and without duplicates.

func (ml MonthList) String() string
Type Place
type Place struct {
	TimeLocation        *time.Location
	Latitude, Longitude float64
}

Place a location in terms of time.Location and a latitude and longitude.

Type TimeOfDay
type TimeOfDay uint32

TimeOfDay represents a time of day.

Functions
func NewTimeOfDay(hour, minute, second int) TimeOfDay

NewTimeOfDay creates a new TimeOfDay from the specified hour, minute and second.

func TimeOfDayFromTime(t time.Time) TimeOfDay

TimeOfDayFromTime returns a TimeOfDay from the specified time.Time.

Methods
func (t TimeOfDay) Add(delta time.Duration) TimeOfDay

Add delta to the time of day. The result will be normalized to 00:00:00 to 23:59:59.

func (t TimeOfDay) Duration() time.Duration

Duration returns the time.Duration for the TimeOfDay.

func (t TimeOfDay) Hour() int

func (t TimeOfDay) Minute() int

func (t TimeOfDay) Normalize() TimeOfDay

Normalize returns a new TimeOfDay with the hour, minute and second values normalized to be within the valid range (0-23, 0-59, 0-59).

func (t *TimeOfDay) Parse(val string) error

Parse val in formats '08[:12[:10]][am|pm]'

func (t TimeOfDay) Second() int

func (t TimeOfDay) String() string
Type TimeOfDayList
type TimeOfDayList []TimeOfDay
Methods
func (tl *TimeOfDayList) Parse(val string) error

Parse val as a comma separated list of TimeOfDay values.

Type YearDay
type YearDay uint32

YearDay represents a year and the day in that year as 1-365/366.

Functions
func NewYearDay(year, day int) YearDay

NewYearDay returns a YearDay for the given year and day. If the day is greater than the number of days in the year then the last day of the year is used.

Methods
func (yd YearDay) CalendarDate() CalendarDate

func (yd YearDay) Date() Date

Date returns the Date for the given day of the year. A day of <= 0 is treated as Jan-01 and a day of > 365/366 is treated as Dec-31.

func (yd YearDay) Day() int

func (yd YearDay) String() string

func (yd YearDay) Year() int
Type YearPlace
type YearPlace struct {
	Year int
	Place
}

YearPlace represents a year at a given place.

Functions
func NewYearLocation(year int, loc *time.Location) YearPlace

func NewYearPlace(year int, place Place) YearPlace

func YearPlaceFromContext(ctx context.Context) YearPlace

YearPlaceFromContext returns the YearPlace value stored in the given context, if there is no value stored then an empty YearPlace is returned for which is IsNotset will be true.

TODO
  • cnicolaou: test with calendar dates also.
  • cnicolaou: add calendar date ranges
  • cnicolaou: add time ranges also.

Documentation

Overview

Package datetime provides support for working with dates, the time of day and associated ranges.

Index

Constants

This section is empty.

Variables

View Source 
var ErrInvalidISO8601Duration = errors.New("invalid ISO8601 duration")

Functions

func AsISO8601Period 

func AsISO8601Period(dur time.Duration) string

func ContextWithYearPlace 

func ContextWithYearPlace(ctx context.Context, yp YearPlace) context.Context

ContextWithYearPlace returns a new context with the given YearPlace value stored in it.

func DaysInFeb 

func DaysInFeb(year int) uint8

DaysInFeb returns the number of days in February for the given year.

func DaysInMonth 

func DaysInMonth(year int, month Month) uint8

DaysInMonth returns the number of days in the given month for the given year.

func DaysInYear 

func DaysInYear(year int) int

DaysInYear returns the number of days in the given year.dc

func IsLeap 

func IsLeap(year int) bool

IsLeap returns true if the given year is a leap year.

func ParseISO8601Period 

func ParseISO8601Period(dur string) (time.Duration, error)

ParseISO8601Period parses an ISO 8601 'period' of the form [-]PnYnMnDTnHnMnS

func Time 

func Time(yp YearPlace, date Date, tod TimeOfDay) time.Time

Time returns a time.Time for the specified YearAndPlace, Date and TimeOfDay using time.Date, and hence, implicitly normalizing the date.

Types

type CalendarDate 

type CalendarDate uint32

CalendarDate represents a date with a year, month and day. Year is represented in the top 16 bits and Date in the lower 16 bits.

func CalendarDateFromTime 

func CalendarDateFromTime(t time.Time) CalendarDate

CalendarDateFromTime creates a new CalendarDate from the specified time.Time.

func NewCalendarDate 

func NewCalendarDate(year int, month Month, day int) CalendarDate

NewCalendarDate creates a new CalendarDate from the specified year, month and day. Year must be in the range 0..65535, month in the range 0..12 and day in the range 0..31.

func NewCalendarDateFromTime 

func NewCalendarDateFromTime(t time.Time) CalendarDate

NewCalendarDateFromTime creates a new CalendarDate from the specified time.Time.

func ParseAnyDate 

func ParseAnyDate(year int, val string) (CalendarDate, error)

ParseAnyDate parses a date in the format '01/02/2006', 'Jan-02-2006', '01/02', 'Jan-02' or '01'. The year argument is ignored for the '01/02/2006' and 'Jan-02-2006' formats. Jan-02, 01/02 are treated as month and day and the year argument is used to set the year.

func ParseCalendarDate 

func ParseCalendarDate(val string) (CalendarDate, error)

ParseCalendarDate a numeric calendar date in formats 'Jan-02-2006' with error checking for valid month and day.

func ParseNumericCalendarDate 

func ParseNumericCalendarDate(val string) (CalendarDate, error)

ParseNumericCalendarDate a numeric calendar date in formats '01/02/2006' with error checking for valid month and day.

func (CalendarDate) Date 

func (cd CalendarDate) Date() Date

Date returns the Date for the CalendarDate.

func (CalendarDate) Day 

func (cd CalendarDate) Day() int

func (CalendarDate) DayOfYear 

func (cd CalendarDate) DayOfYear() int

func (CalendarDate) IsDST 

func (cd CalendarDate) IsDST(loc *time.Location) bool

IsDST returns true if the date is within daylight savings time for the specified location assuming that the time is 12:00 hours. DST starts at 2am and ends at 3am.

func (CalendarDate) Month 

func (cd CalendarDate) Month() Month

func (CalendarDate) Normalize 

func (cd CalendarDate) Normalize(firstOfMonth bool) CalendarDate

Normalize adjusts the date for the given year. If the day is zero then firstOfMonth is used to determine the interpretation of the day. If firstOfMonth is true then the day is set to the first day of the month, otherwise it is set to the last day of the month. Month is normalized to be in the range 1-12.

func (*CalendarDate) Parse 

func (cd *CalendarDate) Parse(val string) error

func (CalendarDate) String 

func (cd CalendarDate) String() string

func (CalendarDate) Time 

func (cd CalendarDate) Time(tod TimeOfDay, loc *time.Location) time.Time

func (CalendarDate) Tomorrow 

func (cd CalendarDate) Tomorrow() CalendarDate

Tomorrow returns the CalendarDate for the day after the specified date, wrapping to the next month or year as needed.

func (CalendarDate) Year 

func (cd CalendarDate) Year() int

func (CalendarDate) YearDay 

func (cd CalendarDate) YearDay() YearDay

func (CalendarDate) Yesterday 

func (cd CalendarDate) Yesterday() CalendarDate

Yesterday returns the CalendarDate for the day before the specified date, wrapping to the previous month or year as needed.

type CalendarDateList 

type CalendarDateList []CalendarDate

CalendarDateList represents a list of CalendarDate values, it can sorted and searched using the slices package.

func (CalendarDateList) Merge 

func (cdl CalendarDateList) Merge() CalendarDateRangeList

Merge returns a new list of date ranges that contains merged consecutive calendar dates into ranges. The dates are normalized using date.Normalize(true). The date list is assumed to be sorted.

func (CalendarDateList) String 

func (cdl CalendarDateList) String() string

type CalendarDateRange 

type CalendarDateRange uint64

CalendarDateRange represents a range of CalendarDate values.

func NewCalendarDateRange 

func NewCalendarDateRange(from, to CalendarDate) CalendarDateRange

NewCalendarDateRange returns a CalendarDateRange for the from/to dates. If the from date is later than the to date then they are swapped. The resulting from and to dates are then normalized using calendardate.Normalize(year, true) for the from date and calendardate.Normalize(year, false) for the to date.

func (CalendarDateRange) Bound 

func (cdr CalendarDateRange) Bound(bound CalendarDateRange) CalendarDateRange

Bound returns a new CalendarDateRange that is bounded by the specified CalendarDateRange, namely the from date is the later of the two from dates and the to date is the earlier of the two to dates. If the resulting range is empty then the zero value is returned.

func (CalendarDateRange) DateRange 

func (cdr CalendarDateRange) DateRange(year int) DateRange

func (CalendarDateRange) Dates 

func (cdr CalendarDateRange) Dates() iter.Seq[CalendarDate]

Dates returns an iterator that yields each Date in the range for the given year.

func (CalendarDateRange) DatesConstrained 

func (cdr CalendarDateRange) DatesConstrained(dc Constraints) iter.Seq[CalendarDate]

DatesConstrained returns an iterator that yields each Date in the range for the given year constrained by the given DateConstraints.

func (CalendarDateRange) Days 

func (cdr CalendarDateRange) Days() iter.Seq[YearDay]

Days returns an iterator that yields each day in the range for the given year.

func (CalendarDateRange) DaysConstrained 

func (cdr CalendarDateRange) DaysConstrained(dc Constraints) iter.Seq[YearDay]

DaysConstrained returns an iterator that yields each day in the range for the given year constrained by the given DateConstraints.

func (CalendarDateRange) From 

func (cdr CalendarDateRange) From() CalendarDate

From returns the start date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

func (CalendarDateRange) Include 

func (cd CalendarDateRange) Include(d CalendarDate) bool

Include returns true if the specified date is within the range.

func (*CalendarDateRange) Parse 

func (cdr *CalendarDateRange) Parse(val string) error

Parse ranges in formats '01/2006:03/2007', 'Jan-2006:Mar-2007', '01/02/2006:03/04/2007' or 'Jan-02-2006:Mar-04-2007', If the from day is zero then it is treated as the first day of the month. If the from day is 29 for a non-leap year then it is left as 29. If the to day is zero then it is treated as the last day of the month taking the year into account for Feb. The start date must be before the end date after normalization as per the above rules.

func (CalendarDateRange) RangesConstrained 

func (cdr CalendarDateRange) RangesConstrained(dc Constraints) iter.Seq[CalendarDateRange]

Ranges returns an iterator that yields each DateRange in the range for the given year constrained by the given DateConstraints.

func (CalendarDateRange) String 

func (cdr CalendarDateRange) String() string

func (CalendarDateRange) To 

func (cdr CalendarDateRange) To() CalendarDate

To returns the end date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

func (CalendarDateRange) Truncate 

func (cdr CalendarDateRange) Truncate(year int) DateRange

Truncate returns a DateRange that is truncated to the start or end of specified year iff the range spans consecutive years, otherwise it returns DateRange(0).

type CalendarDateRangeList 

type CalendarDateRangeList []CalendarDateRange

func (CalendarDateRangeList) Bound 

func (cdrl CalendarDateRangeList) Bound(bound CalendarDateRange) CalendarDateRangeList

Bound returns a new list of date ranges that are bounded by the supplied calendar date range.

func (CalendarDateRangeList) Merge 

func (cdrl CalendarDateRangeList) Merge() CalendarDateRangeList

Merge returns a new list of date ranges that contains merged consecutive overlapping ranges. The date list is assumed to be sorted.

func (CalendarDateRangeList) MergeMonths 

func (cdrl CalendarDateRangeList) MergeMonths(year int, months MonthList) CalendarDateRangeList

MergeMonths returns a merged list of date ranges that contains the specified months for the given year.

func (*CalendarDateRangeList) Parse 

func (cdrl *CalendarDateRangeList) Parse(ranges []string) error

Parse parses a list of ranges in the format expected by CalendarDateRange.Parse.

type Constraints 

type Constraints struct {
	Weekdays       bool                 // If true, include weekdays
	Weekends       bool                 // If true, include weekends
	Custom         DateList             // If non-empty, exclude these dates
	CustomCalendar CalendarDateList     // If non-empty, exclude these calendar dates
	Dynamic        DynamicDateRangeList // If non-nil, exclude dates based on the evaluation of the dynamic date range functions.
}

Constraints represents constraints on date values such as weekends or custom dates to exclude. Custom dates take precedence over weekdays and weekends.

func (Constraints) Empty 

func (dc Constraints) Empty() bool

func (Constraints) Include 

func (dc Constraints) Include(when time.Time) bool

Include returns true if the given date satisfies the constraints. Custom dates are evaluated before weekdays and weekends. An empty set Constraints will return true, ie. include all dates.

func (Constraints) String 

func (dc Constraints) String() string

type Date 

type Date uint16

Date as a uint16 with the month in the high byte and the day in the low byte.

func DateFromTime 

func DateFromTime(when time.Time) Date

DateFromTime returns the Date for the given time.Time.

func NewDate 

func NewDate(month Month, day int) Date

NewDate returns a Date for the given month and day. Both are assumed to valid for the context in which they are used. Normalize should be used to to adjust for a given year and interpretation of zero day value.

func ParseDate 

func ParseDate(val string) (Date, error)

ParseDate parses a date in the forma 'Jan-02' with error checking for valid month and day (Feb is treated as having 29 days)

func ParseNumericDate 

func ParseNumericDate(val string) (Date, error)

Parse a numeric date in the format '01/02' with error checking for valid month and day (Feb is treated as having 29 days)

func (Date) CalendarDate 

func (d Date) CalendarDate(year int) CalendarDate

func (Date) Day 

func (d Date) Day() int

Day returns the day for the date.

func (Date) DayOfYear 

func (d Date) DayOfYear(year int) int

DayOfYear returns the day of the year for the given year as 1-365 for non-leap years and 1-366 for leap years. It will silently treat days that exceed those for a given month to the last day of that month. A day of zero can be used to refer to the last day of the previous month.

func (Date) Month 

func (d Date) Month() Month

Month returns the month for the date.

func (Date) Normalize 

func (d Date) Normalize(year int, firstOfMonth bool) Date

Normalize adjusts the date for the given year. If the day is zero then firstOfMonth is used to determine the interpretation of the day. If firstOfMonth is true then the day is set to the first day of the month, otherwise it is set to the last day of the month. Month is normalized to be in the range 1-12.

func (*Date) Parse 

func (d *Date) Parse(val string) error

Parse date in formats '01', 'Jan','01/02' or 'Jan-02' with error checking for valid month and day (Feb is treated as having 29 days)

func (Date) String 

func (d Date) String() string

func (Date) Tomorrow 

func (d Date) Tomorrow(year int) Date

Tomorrow returns the date of the next day. It will silently treat days that exceed those for a given month as the last day of that month. 12/31 wraps to 1/1.

func (Date) YearDay 

func (d Date) YearDay(year int) YearDay

func (Date) Yesterday 

func (d Date) Yesterday(year int) Date

Yesterday returns the date of the previous day. 1/1 wraps to 12/31.

type DateList 

type DateList []Date

DateList represents a list of Dates, it can be sorted and searched the slices package.

func (DateList) ExpandMonths 

func (dl DateList) ExpandMonths(year int) DateRangeList

func (DateList) Merge 

func (dl DateList) Merge(year int) DateRangeList

Merge returns a new list of date ranges that contains merged consecutive dates into ranges. All dates are normalized using date.Normalize(year, true). The date list is assumed to be sorted.

func (*DateList) Parse 

func (dl *DateList) Parse(val string) error

Parse a comma separated list of Dates.

func (DateList) String 

func (dl DateList) String() string

type DateRange 

type DateRange uint32

DateRange represents a range of dates, inclusive of the start and end dates. NewDateRange and Parse create or initialize a DateRange. The from and to months are stored in the top 8 bits and the from and to days in the lower 8 bits to allow for sorting.

func DateRangeYear 

func DateRangeYear() DateRange

DateRangeYear returns a DateRange for the entire year.

func NewDateRange 

func NewDateRange(from, to Date) DateRange

NewDateRange returns a DateRange for the from/to dates for the specified year. If the from date is later than the to date then they are swapped.

func (DateRange) Bound 

func (dr DateRange) Bound(year int, bound DateRange) DateRange

Bound returns a new DateRange that is bounded by the specified DateRange, namely the from date is the later of the two from dates and the to date is the earlier of the two to dates. If the resulting range is empty then the zero value is returned.

func (DateRange) CalendarDateRange 

func (dr DateRange) CalendarDateRange(year int) CalendarDateRange

CalendarDateRange returns a CalendarDateRange for the DateRange for the specified year. The date range is first normalized to the specified year before creating the CalendarDateRange.

func (DateRange) Dates 

func (dr DateRange) Dates(year int) func(yield func(CalendarDate) bool)

Dates returns an iterator that yields each CalendarDate in the range for the given year. All of the CalendarDate values will have the same year.

func (DateRange) DatesConstrained 

func (dr DateRange) DatesConstrained(year int, dc Constraints) func(yield func(CalendarDate) bool)

DatesConstrained returns an iterator that yields each CalendarDate in the range for the given year constrained by the given DateConstraints. All of the CalendarDate values will have the same year.

func (DateRange) Days 

func (dr DateRange) Days(year int) func(yield func(YearDay) bool)

Days returns an iterator that yields each day in the range for the given year.

func (DateRange) DaysConstrained 

func (dr DateRange) DaysConstrained(year int, dc Constraints) func(yield func(YearDay) bool)

DaysConstrained returns an iterator that yields each day in the range for the given year constrained by the given DateConstraints.

func (DateRange) Equal 

func (dr DateRange) Equal(year int, dr2 DateRange) bool

Equal returns true if the two DateRange values are equal for the given year. Both ranges are first normalized before comparison.

func (DateRange) From 

func (dr DateRange) From(year int) Date

From returns the start date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

func (DateRange) Include 

func (dr DateRange) Include(d Date) bool

Include returns true if the specified date is within the range.

func (DateRange) Normalize 

func (dr DateRange) Normalize(year int) DateRange

Normalize rerturns a new DateRange with the from and to dates normalized to the specified year. This is equivalent to calling date.Normalize(year, true) for the from date and date.Normalize(year, false) for the to date.

func (*DateRange) Parse 

func (dr *DateRange) Parse(val string) error

Parse ranges in formats '01:03', 'Jan:Mar', '01/02:03-04' or 'Jan-02:Mar-04'.

func (DateRange) RangesConstrained 

func (dr DateRange) RangesConstrained(year int, dc Constraints) func(yield func(CalendarDateRange) bool)

Ranges returns an iterator that yields each DateRange in the range for the given year constrained by the given DateConstraints.

func (DateRange) String 

func (dr DateRange) String() string

func (DateRange) To 

func (dr DateRange) To(year int) Date

To returns the end date of the range for the specified year. Feb 29 is returned as Feb 28 for non-leap years.

type DateRangeList 

type DateRangeList []DateRange

DateRangeList represents a list of DateRange values, it can be sorted and searched using the slices package.

func (DateRangeList) Bound 

func (drl DateRangeList) Bound(year int, bound DateRange) DateRangeList

Bound returns a new list of date ranges that are bounded by the specified date range.

func (DateRangeList) Equal 

func (drl DateRangeList) Equal(year int, dr2 DateRangeList) bool

Equal returns true if the two DateRangeList values are equal for the given year.

func (DateRangeList) Merge 

func (drl DateRangeList) Merge(year int) DateRangeList

Merge returns a new list of date ranges that contains merged consecutive overlapping ranges. The date list is assumed to be sorted.

func (DateRangeList) MergeMonths 

func (drl DateRangeList) MergeMonths(year int, months MonthList) DateRangeList

MergeMonths returns a merged list of date ranges that contains the specified months for the given year.

func (*DateRangeList) Parse 

func (drl *DateRangeList) Parse(ranges []string) error

Parse ranges in formats '01:03', 'Jan:Mar', '01-02:03-04' or 'Jan-02:Mar-04'. The parsed list is sorted and without duplicates. If the start date is identical then the end date is used to determine the order.

func (DateRangeList) String 

func (drl DateRangeList) String() string

type DynamicDateRange 

type DynamicDateRange interface {
	Name() string
	Evaluate(year int) CalendarDateRange
}

DynamicDateRange is a function that returns a DateRange for a given year and is intended to be evaluated once per year to calculate events such as solstices, seasons or holidays.

type DynamicDateRangeList 

type DynamicDateRangeList []DynamicDateRange

func (DynamicDateRangeList) Evaluate 

func (dl DynamicDateRangeList) Evaluate(year int) []CalendarDateRange

func (DynamicDateRangeList) String 

func (dl DynamicDateRangeList) String() string

type DynamicTimeOfDay 

type DynamicTimeOfDay interface {
	Name() string
	Evaluate(cd CalendarDate, yp Place) TimeOfDay
}

DynamicTimeOfDay is a function that returns a TimeOfDay for a given date and is intended to be evaluated once per day to calculate events such as sunrise, sunset etc.

type Month 

type Month uint8

Month as a uint8 

const (
	January Month = 1 + iota
	February
	March
	April
	May
	June
	July
	August
	September
	October
	November
	December
)

func MirrorMonth 

func MirrorMonth(month Month) Month

MirrorMonth returns the month that is equidistant from the summer or winter solstice for the specified month. For example, the mirror month for January is November, and the mirror month for February is October.

func ParseMonth 

func ParseMonth(val string) (Month, error)

ParseMonth parses a month name of the form "Jan" to "Dec" or any other longer prefixes of "January" to "December" in either lower or upper case.

func ParseNumericMonth 

func ParseNumericMonth(val string) (Month, error)

ParseNumericMonth parses a 1 or 2 digit numeric month value in the range 1-12.

func (Month) Days 

func (m Month) Days(year int) uint8

func (*Month) Parse 

func (m *Month) Parse(val string) error

Parse parses a month in either numeric or month name format.

func (Month) String 

func (m Month) String() string

type MonthList 

type MonthList []Month

MonthList represents a list of Months, it can be sorted and searched the slices package.

func (*MonthList) Parse 

func (ml *MonthList) Parse(val string) error

Parse val in formats 'Jan,12,Nov'. The parsed list is sorted and without duplicates.

func (MonthList) String 

func (ml MonthList) String() string

type Place 

type Place struct {
	TimeLocation        *time.Location
	Latitude, Longitude float64
}

Place a location in terms of time.Location and a latitude and longitude.

type TimeOfDay 

type TimeOfDay uint32

TimeOfDay represents a time of day.

func NewTimeOfDay 

func NewTimeOfDay(hour, minute, second int) TimeOfDay

NewTimeOfDay creates a new TimeOfDay from the specified hour, minute and second.

func TimeOfDayFromTime 

func TimeOfDayFromTime(t time.Time) TimeOfDay

TimeOfDayFromTime returns a TimeOfDay from the specified time.Time.

func (TimeOfDay) Add 

func (t TimeOfDay) Add(delta time.Duration) TimeOfDay

Add delta to the time of day. The result will be normalized to 00:00:00 to 23:59:59.

func (TimeOfDay) Duration 

func (t TimeOfDay) Duration() time.Duration

Duration returns the time.Duration for the TimeOfDay.

func (TimeOfDay) Hour 

func (t TimeOfDay) Hour() int

func (TimeOfDay) Minute 

func (t TimeOfDay) Minute() int

func (TimeOfDay) Normalize 

func (t TimeOfDay) Normalize() TimeOfDay

Normalize returns a new TimeOfDay with the hour, minute and second values normalized to be within the valid range (0-23, 0-59, 0-59).

func (*TimeOfDay) Parse 

func (t *TimeOfDay) Parse(val string) error

Parse val in formats '08[:12[:10]][am|pm]'

func (TimeOfDay) Second 

func (t TimeOfDay) Second() int

func (TimeOfDay) String 

func (t TimeOfDay) String() string

type TimeOfDayList 

type TimeOfDayList []TimeOfDay

func (*TimeOfDayList) Parse 

func (tl *TimeOfDayList) Parse(val string) error

Parse val as a comma separated list of TimeOfDay values.

type YearDay 

type YearDay uint32

YearDay represents a year and the day in that year as 1-365/366.

func NewYearDay 

func NewYearDay(year, day int) YearDay

NewYearDay returns a YearDay for the given year and day. If the day is greater than the number of days in the year then the last day of the year is used.

func (YearDay) CalendarDate 

func (yd YearDay) CalendarDate() CalendarDate

func (YearDay) Date 

func (yd YearDay) Date() Date

Date returns the Date for the given day of the year. A day of <= 0 is treated as Jan-01 and a day of > 365/366 is treated as Dec-31.

func (YearDay) Day 

func (yd YearDay) Day() int

func (YearDay) String 

func (yd YearDay) String() string

func (YearDay) Year 

func (yd YearDay) Year() int

type YearPlace 

type YearPlace struct {
	Year int
	Place
}

YearPlace represents a year at a given place.

func NewYearLocation 

func NewYearLocation(year int, loc *time.Location) YearPlace

func NewYearPlace 

func NewYearPlace(year int, place Place) YearPlace

func YearPlaceFromContext 

func YearPlaceFromContext(ctx context.Context) YearPlace

YearPlaceFromContext returns the YearPlace value stored in the given context, if there is no value stored then an empty YearPlace is returned for which is IsNotset will be true.

Source Files

View all Source files

Directories

Path Synopsis
Package schedule provides support for scheduling events based on dates and times.
 Package schedule provides support for scheduling events based on dates and times.

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.