Package timeutil contains common function for time related operations.



This section is empty.


View Source
var TestingEndOfTime = time.Time{}

TestingEndOfTime is a special time returned by TestingNow objects to indicate that the end time has been reached.


func CompareTimestamp

func CompareTimestamp(ts1, ts2 string) (int, error)

CompareTimestamp compares 2 given timestamps. Returns 0 if they are equal, 1 if the frist is older and -1 if the second is older.

func MakeTimestamp

func MakeTimestamp() string

MakeTimestamp creates a timestamp string based on the systems epoch (January 1, 1970 UTC).

func TimestampString

func TimestampString(ts, loc string) (string, error)

TimestampString prints a given timestamp as a human readable time in a given Location (timezone).

func WaitTestingCron

func WaitTestingCron(c *Cron)

WaitTestingCron waits for a testing cron object to end. No need to call stop afterwards.


type Cron

type Cron struct {
	NowFunc func() time.Time // Function to get the current local time
	Tick    time.Duration    // Cron check interval
	// contains filtered or unexported fields

Cron is an object which implements cron-like functionality. It can be used to schedule jobs at certain time intervals based on local time.

Each Cron object runs a single scheduling thread. Very time consuming tasks which are triggered by this object are expected to run in a separate thread otherwise other registered tasks might not be triggered on time.

Time can be speed up for testing purposes by changing the NowFunc and Tick properties. See NewTestingCron for details.

Example code:

c := NewCron()

c.Register("0 0 12 1 * *", func() {

	// Do something at the beginning of hour 12:00 on 1st of every month

c.Start() // Start cron thread


c.Stop() // Shutdown cron thread

func NewCron

func NewCron() *Cron

NewCron creates a new Cron object.

func NewTestingCron

func NewTestingCron(startTime, endTime time.Time) *Cron

NewTestingCron creates a new Cron object which can be used for testing. When started it goes through all seconds of the the given time range in a fraction of the time (seconds are instantly increased). All handler functions are still called the exact number of times as if they would be running during the given time range in normal time. Use the NowFunc of the cron object to get the current testing time - the testing time will always return the same time unless advanced by the cron thread.

Example code:

c = NewTestingCronDay()

c.Register("0 12 12,8 * * *", func() {

	// Do something at minute 12 of hour 08:00 and hour 12:00 every day


func NewTestingCronDay

func NewTestingCronDay() *Cron

NewTestingCronDay creates a new test Cron object which goes through a full day.

func NewTestingCronMonth

func NewTestingCronMonth() *Cron

NewTestingCronMonth creates a new test Cron object which goes through a full month.

func NewTestingCronWeek

func NewTestingCronWeek() *Cron

NewTestingCronWeek creates a new test Cron object which goes through a full week.

func (*Cron) Register

func (c *Cron) Register(specString string, handler func()) error

Register registers a new handler to be called every interval, defined by the given spec.

func (*Cron) RegisterSpec

func (c *Cron) RegisterSpec(spec *CronSpec, handler func())

RegisterSpec registers a new handler to be called every interval, defined by the given spec.

func (*Cron) Start

func (c *Cron) Start()

Start starts the cron thread. Start is a NOP if cron is already running.

func (*Cron) Stop

func (c *Cron) Stop()

Stop stops the cron thread. Stop is a NOP if cron is not running.

type CronSpec

type CronSpec struct {
	Second     []string
	Minute     []string
	Hour       []string
	DayOfMonth []string
	Month      []string
	DayOfWeek  []string

CronSpec is a data structure which is used to specify time schedules. A CronSpec can be stated as a single text string which must have the following 6 entries separated by whitespace:

Field	        Valid values
-----	        ------------
second         * or 0-59 or *%1-59
minute         * or 0-59 or *%1-59
hour           * or 0-23 or *%1-23
day of month   * or 1-31 or *%1-31
month          * or 1-12 or *%1-12
day of week    * or 0-6 (0 is Sunday) or *%1-7

Multiple values for an entry can be separated by commas e.g. 1,3,5,7. A * in any field matches all values i.e. execute every minute, every day, etc. A *%<number> in any field entry matches when the time is a multiple of <number>.

Example code:

ss, _ := NewCronSpec("0 0 12 1 * *")


at the beginning of hour 12:00 on 1st of every month

func NewCronSpec

func NewCronSpec(spec string) (*CronSpec, error)

NewCronSpec creates a new CronSpec from a given spec string.

func (*CronSpec) DaysString

func (cs *CronSpec) DaysString() string

DaysString returns on which days this spec will trigger.

func (*CronSpec) Generate2000Examples

func (cs *CronSpec) Generate2000Examples(n int) []string

Generate2000Examples generates matching time examples from the year 2000 for this CronSpec. This function returns the first n examples starting from 01. January 2000 00:00:00.

func (*CronSpec) MatchesTime

func (cs *CronSpec) MatchesTime(t time.Time) bool

MatchesTime checks if a given time object matches this CronSpec.

func (*CronSpec) SpecString

func (cs *CronSpec) SpecString() string

SpecString returns the spec object as a spec string. This string can be used to construct the object again using NewCronSpec.

func (*CronSpec) String

func (cs *CronSpec) String() string

String returns a human readable string representing the spec.

func (*CronSpec) TimeString

func (cs *CronSpec) TimeString() string

TimeString returns on which time during the day this spec will trigger.

type TestingNow

type TestingNow struct {
	// contains filtered or unexported fields

TestingNow is a testing object which can provide a specialized Now function which runs from a given start to a given end time.

func NewTestingNow

func NewTestingNow(start, end time.Time) (*TestingNow, error)

NewTestingNow creates a new TestingNow object with a given start and end time.

func (*TestingNow) NewNow

func (tn *TestingNow) NewNow() time.Time

NewNow returns the current testing time and advances the clock.

func (*TestingNow) Now

func (tn *TestingNow) Now() time.Time

Now returns the current testing time.