timeutil

Documentation

Index

• Constants
• func Human(then time.Time) string
• func Includes(schedule []*Schedule, t time.Time) bool
• 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 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 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 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 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 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