timeutil

Documentation

Index

• Constants
• func Human(then time.Time) string
• func Includes(schedule []*Schedule, t time.Time) bool
• func IsNTPSynchronized() (bool, error)
• func MockTimeNow(f func() time.Time) (restorer func())
• func Next(schedule []*Schedule, last time.Time, maxDuration time.Duration) time.Duration
• type Clock
  • func ParseClock(s string) (t Clock, err error)
  • func (t Clock) Add(dur time.Duration) Clock
  • func (t Clock) String() string
  • func (t Clock) Sub(other Clock) time.Duration
  • func (t Clock) Time(base time.Time) time.Time
• type ClockSpan
  • func (ts ClockSpan) ClockSpans() []ClockSpan
  • func (ts ClockSpan) String() string
  • func (ts ClockSpan) Window(t time.Time) ScheduleWindow
• type NoTimedate1Error
  • func (e NoTimedate1Error) Error() string
• type Schedule
  • func ParseLegacySchedule(scheduleSpec string) ([]*Schedule, error)
  • func ParseSchedule(scheduleSpec string) ([]*Schedule, error)
  • func (sched *Schedule) Includes(t time.Time) bool
  • func (sched *Schedule) Next(last time.Time) ScheduleWindow
  • func (sched *Schedule) String() string
• type ScheduleWindow
  • func (s ScheduleWindow) Includes(t time.Time) bool
  • func (s ScheduleWindow) IsZero() bool
• type StdlibTimer
  • func AfterFunc(d time.Duration, f func()) StdlibTimer
  • func NewTimer(d time.Duration) StdlibTimer
  • func (t StdlibTimer) ExpiredC() <-chan time.Time
• type Timer
• type Week
  • func (w Week) String() string
• type WeekSpan
  • func (ws WeekSpan) AnchoredAtStart() bool
  • func (ws WeekSpan) IsSingleDay() bool
  • func (ws WeekSpan) Match(t time.Time) bool
  • func (ws WeekSpan) String() string

Constants

const (
	EveryWeek uint = 0
	LastWeek  uint = 5
)

Functions

func Human

func Human(then time.Time) string

Human turns the time into a relative expression of time meant for human consumption. Human(t) --> "today at 07:47"

func Includes

func Includes(schedule []*Schedule, t time.Time) bool

Includes checks whether given time t falls inside the time range covered by a schedule.

func IsNTPSynchronized

func IsNTPSynchronized() (bool, error)

IsNTPSynchronized returns true if the time is syncronized according to systemd-timedated.

func MockTimeNow

func MockTimeNow(f func() time.Time) (restorer func())

MockTimeNow mocks the time.Now() calls used in the timeutil package.

func Next

func Next(schedule []*Schedule, last time.Time, maxDuration time.Duration) time.Duration

Next returns the earliest event after last according to the provided schedule but no later than maxDuration since last.

Types

type Clock

type Clock struct {
	Hour   int
	Minute int
}

Clock represents a hour:minute time within a day.

func ParseClock

func ParseClock(s string) (t Clock, err error)

ParseClock parses a string that contains hour:minute and returns a Clock type or an error

func (Clock) Add

func (t Clock) Add(dur time.Duration) Clock

Add adds given duration to t and returns a new Clock

func (Clock) String

func (t Clock) String() string

func (Clock) Sub

func (t Clock) Sub(other Clock) time.Duration

Sub returns the duration t - other.

func (Clock) Time

func (t Clock) Time(base time.Time) time.Time

Time generates a time.Time with hour and minute set from t, while year, month and day are taken from base

type ClockSpan

type ClockSpan struct {
	Start Clock
	End   Clock
	// Split defines the number of subspans this span will be divided into.
	Split uint
	// Spread defines whether the events are randomly spread inside the span
	// or subspans.
	Spread bool
}

ClockSpan represents a time span within 24h, potentially crossing days. For example, 23:00-1:00 represents a span from 11pm to 1am.

func (ClockSpan) ClockSpans

func (ts ClockSpan) ClockSpans() []ClockSpan

ClockSpans returns a slice of ClockSpans generated from ts by splitting the time between ts.Start and ts.End into ts.Split equal spans.

func (ClockSpan) String

func (ts ClockSpan) String() string

func (ClockSpan) Window

func (ts ClockSpan) Window(t time.Time) ScheduleWindow

Window generates a ScheduleWindow which has the start date same as t. The window's start and end time are set according to Start and End, with the end time possibly crossing into the next day.

type NoTimedate1Error

type NoTimedate1Error struct {
	Err error
}

func (NoTimedate1Error) Error

func (e NoTimedate1Error) Error() string

type Schedule

type Schedule struct {
	WeekSpans  []WeekSpan
	ClockSpans []ClockSpan
}

Schedule represents a single schedule

func ParseLegacySchedule

func ParseLegacySchedule(scheduleSpec string) ([]*Schedule, error)

ParseLegacySchedule takes an obsolete schedule string in the form of:

9:00-15:00 (every day between 9am and 3pm) 9:00-15:00/21:00-22:00 (every day between 9am,5pm and 9pm,10pm)

and returns a list of Schedule types or an error

func ParseSchedule

func ParseSchedule(scheduleSpec string) ([]*Schedule, error)

ParseSchedule parses a schedule in V2 format. The format is described as:

eventlist = eventset *( ",," eventset )
eventset = wdaylist / timelist / wdaylist "," timelist

wdaylist = wdayset *( "," wdayset )
wdayset = wday / wdaynumber / wdayspan
wday =  ( "sun" / "mon" / "tue" / "wed" / "thu" / "fri" / "sat" )
wdaynumber =  ( "sun" / "mon" / "tue" / "wed" / "thu" / "fri" / "sat" ) DIGIT
wdayspan = wday "-" wday / wdaynumber "-" wday / wday "-" wdaynumber

timelist = timeset *( "," timeset )
timeset = time / timespan
time = 2DIGIT ":" 2DIGIT
timespan = time ( "-" / "~" ) time [ "/" ( time / count ) ]
count = 1*DIGIT

Examples: mon,10:00,,fri,15:00 (Monday at 10:00, Friday at 15:00) mon,fri,10:00,15:00 (Monday at 10:00 and 15:00, Friday at 10:00 and 15:00) mon-wed,fri,9:00-11:00/2 (Monday to Wednesday and on Friday, twice between 9:00 and 11:00) mon,9:00~11:00,,wed,22:00~23:00 (Monday, sometime between 9:00 and 11:00, and on Wednesday, sometime between 22:00 and 23:00) mon,wed (Monday and on Wednesday) mon,,wed (same as above) mon1-wed (1st Monday of the month to the following Wednesday) mon-wed1 (from the 1st Wednesday of the month to the prior Monday) mon1 (1st Monday of the month) mon1-mon (from the 1st Monday of the month to the following Monday)

Returns a slice of schedules or an error if parsing failed

func (*Schedule) Includes

func (sched *Schedule) Includes(t time.Time) bool

Includes checks whether given time t falls inside the time range covered by the schedule. A single time schedule eg. '10:00' is treated as spanning the time [10:00, 10:01)

func (*Schedule) Next

func (sched *Schedule) Next(last time.Time) ScheduleWindow

Next returns the earliest window after last according to the schedule.

func (*Schedule) String

func (sched *Schedule) String() string

type ScheduleWindow

type ScheduleWindow struct {
	Start time.Time
	End   time.Time
	// Spread defines whether the event shall be randomly placed between
	// Start and End times
	Spread bool
}

ScheduleWindow represents a time window between Start and End times when the scheduled event can happen.

func (ScheduleWindow) Includes

func (s ScheduleWindow) Includes(t time.Time) bool

Includes returns whether t is inside the window.

func (ScheduleWindow) IsZero

func (s ScheduleWindow) IsZero() bool

IsZero returns whether s is uninitialized.

type StdlibTimer

type StdlibTimer struct {
	*time.Timer
}

func AfterFunc

func AfterFunc(d time.Duration, f func()) StdlibTimer

AfterFunc waits for the duration to elapse and then calls f in its own goroutine. It returns a Timer that can be used to cancel the call using its Stop method. The returned Timer's C field is not used and will be nil.

See here for more information: https://pkg.go.dev/time#AfterFunc

func NewTimer

func NewTimer(d time.Duration) StdlibTimer

NewTimer creates a new Timer that will send the current time on its channel after at least duration d.

See here for more information: https://pkg.go.dev/time#NewTimer

func (StdlibTimer) ExpiredC

func (t StdlibTimer) ExpiredC() <-chan time.Time

ExpiredC returns the channel t.C over which the current time will be sent when the timer expires, assuming the timer was created via NewTimer.

If the timer was created via AfterFunc, then t.C is nil, so this function returns nil.

type Timer

type Timer interface {
	Reset(d time.Duration) bool
	Stop() bool
	// ExpiredC is equivalent to t.C for StdlibTimer and time.Timer.
	ExpiredC() <-chan time.Time
}

Timer is an interface which wraps time.Timer so that it may be mocked.

Timer is fully compatible with time.Timer, except that since interfaces cannot have instance variables, we must expose the C channel as a method. Therefore, when replacing a time.Timer with timeutil.Timer, any accesses of C must be replaced with ExpireC().

For more information about time.Timer, see: https://pkg.go.dev/time#Timer

type Week

type Week struct {
	Weekday time.Weekday
	// Pos defines which week inside the month the Day refers to, where zero
	// means every week, 1 means first occurrence of the weekday, and 5
	// means last occurrence (which might be the fourth or the fifth).
	Pos uint
}

Week represents a weekday such as Monday, Tuesday, with optional week-in-the-month position, eg. the first Monday of the month

func (Week) String

func (w Week) String() string

type WeekSpan

type WeekSpan struct {
	Start Week
	End   Week
}

WeekSpan represents a span of weekdays between Start and End days, which may be a single day. WeekSpan may wrap around the week, eg. fri-mon is a span from Friday to Monday, mon1-fri is a span from the first Monday to the following Friday, while mon1 (internally, an equal start and end range) represents the 1st Monday of a month.

func (WeekSpan) AnchoredAtStart

func (ws WeekSpan) AnchoredAtStart() bool

AnchoredAtStart returns true when the week span is anchored at the starting point, or false otherwise

func (WeekSpan) IsSingleDay

func (ws WeekSpan) IsSingleDay() bool

IsSingleDay returns true when the week span represents a single day

func (WeekSpan) Match

func (ws WeekSpan) Match(t time.Time) bool

Match checks if t is within the day span represented by ws.

func (WeekSpan) String

func (ws WeekSpan) String() string