time

Documentation

Overview

Package time provide a library for working with time.

Index

• Constants
• Variables
• func Microsecond(t *time.Time) int64
• func ParseDuration(s string) (time.Duration, error)
• func SortClock(list []Clock)
• func UnixMicro(t *time.Time) int64
• func UnixMilli(t time.Time) int64
• func UnixMilliString(t time.Time) string
• type Clock
  • func CreateClock(hour, min, sec int) Clock
  • func ParseClock(v string) (c Clock)
  • func (c Clock) After(d Clock) bool
  • func (c Clock) Before(d Clock) bool
  • func (c Clock) Equal(d Clock) bool
  • func (c Clock) Hour() int
  • func (c Clock) Minute() int
  • func (c Clock) Second() int
  • func (c Clock) String() string
• type Scheduler
  • func NewScheduler(schedule string) (sch *Scheduler, err error)
  • func (sch *Scheduler) Next() (next time.Time)
  • func (sch *Scheduler) Stop()

Examples

• Clock.After
• Clock.Before
• Clock.Equal
• Clock.Hour
• Clock.Minute
• Clock.Second
• Clock.String
• CreateClock
• Microsecond
• ParseClock
• Scheduler.Next
• SortClock
• UnixMicro
• UnixMilli
• UnixMilliString

Constants

const (
	// Day the duration for a day.
	Day = 24 * time.Hour
	// Week the duration for a week.
	Week = 7 * Day
)

const (
	ScheduleKindMinutely = `minutely`
	ScheduleKindHourly   = `hourly`
	ScheduleKindDaily    = `daily`
	ScheduleKindWeekly   = `weekly`
	ScheduleKindMonthly  = `monthly`
)

List of kind of schedule.

Variables

var (
	// ErrDurationMissingValue an error when value is missing when parsing
	// duration.
	ErrDurationMissingValue = errors.New("missing value in duration")
)

var ErrScheduleUnknown error = errors.New(`unknown schedule`)

ErrScheduleUnknown define an error when unknown schedule kind parsed from value.

var Now = func() time.Time {
	return time.Now()
}

Now returns the current local time. Unlike standard library, this is a variable that can be override to mock the current time during testing.

var ShortDayNames = []string{`Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`}

ShortDayNames contains list of day name in English, in shorter.

var ShortMonths = map[string]time.Month{
	`Jan`: time.January,
	`Feb`: time.February,
	`Mar`: time.March,
	`Apr`: time.April,
	`May`: time.May,
	`Jun`: time.June,
	`Jul`: time.July,
	`Aug`: time.August,
	`Sep`: time.September,
	`Oct`: time.October,
	`Nov`: time.November,
	`Dec`: time.December,
}

ShortMonths provide mapping between text of month, in English, short format to their time.Month value

Functions

func Microsecond

func Microsecond(t *time.Time) int64

Microsecond return the microsecond value of time. For example, if the unix nano seconds is 1612331218913557000 then the micro second value is 913557.

To get the unix microsecond use UnixMicro().

Example

nano := time.Unix(1612331000, 123456789)
fmt.Printf("%d", Microsecond(&nano))

Output:

123456

func ParseDuration

func ParseDuration(s string) (time.Duration, error)

ParseDuration extend the capability of standard time.Duration with additional unit suffix: day and week. Day unit end with "d" and week unit end with "w". A day is equal with "24h", an a week is equal to "7d". Unlike standard time.Duration the week or day units must be before hours.

func SortClock

func SortClock(list []Clock)

SortClock sort the clock.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var (
		list = []time.Clock{
			time.CreateClock(3, 2, 1),
			time.CreateClock(2, 3, 1),
			time.CreateClock(1, 2, 3),
		}
	)
	time.SortClock(list)
	fmt.Println(list)
}

Output:

[01:02:03 02:03:01 03:02:01]

func UnixMicro

func UnixMicro(t *time.Time) int64

UnixMicro returns t as a Unix time in microsecond. For example, if the unix nano seconds is 1612331218913557000 then the UnixMicro value is 1612331218913557.

Example

nano := time.Unix(1612331000, 123456789)
fmt.Printf("%d", UnixMicro(&nano))

Output:

1612331000123456

func UnixMilli

func UnixMilli(t time.Time) int64

UnixMilli returns t as a Unix time, the number of milliseconds elapsed since January 1, 1970 UTC.

Example

nano := time.Unix(1612331000, 123456789)
fmt.Printf("%d", UnixMilli(nano))

Output:

1612331000123

func UnixMilliString

func UnixMilliString(t time.Time) string

UnixMilliString returns the UnixMilli() as string.

Example

nano := time.Unix(1612331000, 123456789)
fmt.Printf("%s", UnixMilliString(nano))

Output:

1612331000123

Types

type Clock

type Clock struct {
	// contains filtered or unexported fields
}

Clock represent 24 hours time with hour, minute, and second. An hour value is from 0 to 23, a minute value is from 0 to 59, and a second value is from 0 to 59.

func CreateClock

func CreateClock(hour, min, sec int) Clock

CreateClock create instance of Clock. Any value that is not valid will be set to 0.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var c = time.CreateClock(-1, 2, 3) // The hour valid is invalid.
	fmt.Println(c)
}

Output:

00:02:03

func ParseClock

func ParseClock(v string) (c Clock)

ParseClock parse the clock from string with format `HH:MM:SS`. The MM and SS are optionals. Any value that is not valid will be set to 0.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var c = time.ParseClock(`01:23:60`) // The second value is invalid.
	fmt.Println(c)
}

Output:

01:23:00

func (Clock) After

func (c Clock) After(d Clock) bool

After return true if the Clock instant c is after d.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var (
		c = time.CreateClock(1, 2, 3)
	)

	fmt.Println(c.After(time.CreateClock(0, 2, 3)))
	fmt.Println(c.After(time.CreateClock(1, 1, 3)))
	fmt.Println(c.After(time.CreateClock(1, 2, 2)))

	fmt.Println(c.After(time.CreateClock(1, 2, 3))) // Equal Clock is not an After.
	fmt.Println(c.After(time.CreateClock(1, 2, 4)))
	fmt.Println(c.After(time.CreateClock(1, 3, 0)))
	fmt.Println(c.After(time.CreateClock(2, 0, 0)))
}

Output:

true
true
true
false
false
false
false

func (Clock) Before

func (c Clock) Before(d Clock) bool

Before return true if the Clock instant c is before d.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var (
		c = time.CreateClock(1, 2, 3)
	)

	fmt.Println(c.Before(time.CreateClock(0, 2, 3)))
	fmt.Println(c.Before(time.CreateClock(1, 1, 3)))
	fmt.Println(c.Before(time.CreateClock(1, 2, 2)))
	fmt.Println(c.Before(time.CreateClock(1, 2, 3))) // Equal Clock is not a Before.
	fmt.Println(c.Before(time.CreateClock(1, 2, 4)))
	fmt.Println(c.Before(time.CreateClock(1, 3, 0)))
}

Output:

false
false
false
false
true
true

func (Clock) Equal

func (c Clock) Equal(d Clock) bool

Equal return true if the Clock instance c is equal with d.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var (
		c = time.CreateClock(1, 2, 3)
	)

	fmt.Println(c.Equal(time.CreateClock(0, 2, 3)))
	fmt.Println(c.Equal(time.CreateClock(1, 2, 2)))
	fmt.Println(c.Equal(time.CreateClock(1, 2, 3)))
	fmt.Println(c.Equal(time.CreateClock(1, 2, 4)))
	fmt.Println(c.Equal(time.CreateClock(1, 3, 0)))
}

Output:

false
false
true
false
false

func (Clock) Hour

func (c Clock) Hour() int

Hour return the Clock hour value.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var c = time.CreateClock(1, 2, 3)
	fmt.Println(c.Hour())
}

Output:

1

func (Clock) Minute

func (c Clock) Minute() int

Minute return the Clock minute value.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var c = time.CreateClock(1, 2, 3)
	fmt.Println(c.Minute())
}

Output:

2

func (Clock) Second

func (c Clock) Second() int

Second return the Clock second value.

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var c = time.CreateClock(1, 2, 3)
	fmt.Println(c.Second())
}

Output:

3

func (Clock) String

func (c Clock) String() string

String return the Clock value as "HH:MM:SS".

Example

package main

import (
	"fmt"

	"github.com/shuLhan/share/lib/time"
)

func main() {
	var c = time.CreateClock(1, 2, 3)
	fmt.Println(c.String())
}

Output:

01:02:03

type Scheduler

type Scheduler struct {
	C <-chan time.Time // The channel on which the schedule are delivered.

	sync.Mutex
	// contains filtered or unexported fields
}

Scheduler is a timer that run periodically based on calendar or day time.

A schedule is divided into monthly, weekly, daily, hourly, and minutely. An empty schedule is equal to minutely, a schedule that run every minute.

func NewScheduler

func NewScheduler(schedule string) (sch *Scheduler, err error)

NewScheduler create new Scheduler from string schedule. A schedule is divided into monthly, weekly, daily, hourly, and minutely. An empty schedule is equal to minutely.

Monthly

A monthly schedule can be divided into calendar day and a time, with the following format,

MONTHLY      = "monthly" ["@" DAY_OF_MONTH] ["@" TIME_OF_DAY]
DAY_OF_MONTH = [ 1-31 *("," 1-31) ]
TIME_OF_DAY  = [ TIME *("," TIME) ]
TIME         = "00:00"-"23:59"

An empty DAY_OF_MONTH is equal to 1 or the first day. An empty TIME_OF_DAY is equal to midnight or 00:00. If registered DAY_OF_MONTH is not available in the current month, it will be skipped, for example "monthly@31" will not run in February. For example,

• monthly = monthly@1@00:00 = the first day of each month at 00:00.
• monthly@1,15@18:00 = on day 1 and 15 every month at 6 PM.

Weekly

A weekly schedule can be divided into day of week and a time, with the following format,

WEEKLY      = "weekly" ["@" LIST_DOW] ["@" TIME_OF_DAY]
LIST_DOW    = [ DAY_OF_WEEK *("," DAY_OF_WEEK) ]
DAY_OF_WEEK = "Sunday" / "Monday" / "Tuesday" / "Wednesday"
            / "Thursday" / "Friday" / "Saturday"

The first day of the week or empty LIST_DOW is equal to Sunday.

For example,

• weekly = weekly@Sunday@00:00 = every Sunday at 00:00.
• weekly@Sunday,Tuesday,Friday@15:00 = every Sunday, Tuesday, and Friday on each week at 3 PM.

Daily

A daily schedule can be divided only into time.

DAILY = "daily" ["@" TIME_OF_DAY]

For example,

• daily = daily@00:00 = every day at 00:00.
• daily@00:00,06:00,12:00,18:00 = every day at midnight, 6 AM, and 12 PM.

A hourly schedule can be divided into minutes, with the following format,

HOURLY  = "hourly" ["@" MINUTES]
MINUTES = [ 0-59 *("," 0-59) ]

An empty MINUTES is equal to 0. For example,

• hourly = hourly@0 = every hour at minute 0.
• hourly@0,15,30,45 = on minutes 0, 15, 30, 45 every hour.

Minutely

A minutely schedule run every minute, with the following format,

MINUTELY = "minutely"

For example,

• minutely = every minute

func (*Scheduler) Next

func (sch *Scheduler) Next() (next time.Time)

Next return the next schedule.

Example

package main

import (
	"fmt"
	"log"
	"time"

	libtime "github.com/shuLhan/share/lib/time"
)

func main() {
	// Override Now for making this example works.
	libtime.Now = func() time.Time {
		return time.Date(2013, time.January, 20, 14, 26, 59, 0, time.UTC)
	}

	var (
		sch *libtime.Scheduler
		err error
	)

	sch, err = libtime.NewScheduler(`minutely`)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(sch.Next())
}

Output:

2013-01-20 14:27:00 +0000 UTC

func (*Scheduler) Stop

func (sch *Scheduler) Stop()

Stop the scheduler.