package ztime

import "zgo.at/zstd/ztime"

Package ztime implements functions for date and time.

Index ¶

• Variables
• func AddPeriod(t time.Time, n int, p Period) time.Time
• func DaysInMonth(t time.Time) int
• func DurationAs(d, as time.Duration) string
• func EndOf(t time.Time, p Period) time.Time
• func FromString(s string) time.Time
• func LastInMonth(t time.Time) bool
• func LeapYear(t time.Time) bool
• func MustParse(layout, value string) time.Time
• func SetNow(t *testing.T, s string)
• func Sleep(ctx context.Context, d time.Duration)
• func StartOf(t time.Time, p Period) time.Time
• func Takes(f func()) time.Duration
• func Unpack(t time.Time) (year int, month time.Month, day, hour, minute, second, nanosecond int, loc *time.Location)
• type Diff
• func (d Diff) String() string
• type Durations
• func NewDurations(max int) Durations
• func (d *Durations) Append(add ...time.Duration)
• func (d Durations) Distrubute(n int) []Durations
• func (d *Durations) Grow(n int)
• func (d Durations) Len() int
• func (d Durations) List() []time.Duration
• func (d Durations) Max() time.Duration
• func (d Durations) Mean() time.Duration
• func (d Durations) Median() time.Duration
• func (d Durations) Min() time.Duration
• func (d Durations) String() string
• func (d Durations) Sum() time.Duration
• func (d Durations) Top(percent int) Durations
• type Period
• func Week(sundayStartsWeek bool) Period
• func (p Period) String() string
• type Range
• func NewRange(start time.Time) Range
• func (r Range) Current(p Period) Range
• func (r Range) Diff(periods ...Period) Diff
• func (r Range) Equal(cmp Range) bool
• func (r Range) From(start time.Time) Range
• func (r Range) In(loc *time.Location) Range
• func (r Range) IsZero() bool
• func (r Range) Last(p Period) Range
• func (r Range) Locale(l RangeLocale) Range
• func (r Range) Period(n int, p Period) Range
• func (r Range) Round(d time.Duration) Range
• func (r Range) String() string
• func (r Range) To(end time.Time) Range
• func (r Range) Truncate(d time.Duration) Range
• func (r Range) UTC() Range
• type RangeLocale
• type Time
• func (t Time) Add(d time.Duration) Time
• func (t Time) AddDate(years, months, days int) Time
• func (t Time) AddPeriod(n int, p Period) Time
• func (t Time) EndOf(p Period) Time
• func (t Time) In(loc *time.Location) Time
• func (t Time) Local() Time
• func (t Time) Round(d time.Duration) Time
• func (t Time) StartOf(p Period) Time
• func (t Time) Truncate(d time.Duration) Time
• func (t Time) UTC() Time
• func (t Time) Unpack() (year int, month time.Month, day, hour, minute, second, nanosecond int, loc *time.Location)

Variables ¶

var DefaultRangeLocale = RangeLocale{
	Months: [12]string{"January", "February", "March", "April", "May",
		"June", "July", "August", "September", "October", "November", "December"},
	MonthsShort: [12]string{"Jan", "Feb", "Mar", "Apr", "May", "Jun",
		"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"},
	Days:      [7]string{"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"},
	DaysShort: [7]string{"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"},

	Today:     func() string { return "Today" },
	Yesterday: func() string { return "Yesterday" },
	Month: func(m time.Month) string {
		return []string{"January", "February", "March", "April", "May", "June",
			"July", "August", "September", "October", "November", "December"}[m-1]
	},
	DayAgo: func(n int) string {
		if n == 1 {
			return "1 day ago"
		}
		return strconv.Itoa(n) + " days ago"
	},
	WeekAgo: func(n int) string {
		if n == 1 {
			return "1 week ago"
		}
		return strconv.Itoa(n) + " weeks ago"
	},
	MonthAgo: func(n int) string {
		if n == 1 {
			return "1 month ago"
		}
		return strconv.Itoa(n) + " months ago"
	},
}

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

Now returns the current time as UTC.

This can be swapped out in tests with SetNow()

TODO: this shouldn't use .UTC(), at least not by default.

Functions ¶

func AddPeriod ¶

func AddPeriod(t time.Time, n int, p Period) time.Time

AddPeriod adds time period.

This matches common understanding of what things like "next month" mean; adding or subtracting months will always end up in the expected month, regardless of the number of days in either month.

For example:

Jan 31 + 1 month  = Feb 28 (or Feb 29, if it's a leap year)
Dec 31 - 3 months = Sep 30

This is done for Month, Quarter, and HalfYear.

There is one special case for Year: if the date is Feb 29th, adding or subtracting a year will land you on Feb 28th.

Since leap seconds are irregular and unpredictable they are not handled. The entire concept is silly and most programs should just pretend they don't exist.

func DaysInMonth ¶

func DaysInMonth(t time.Time) int

DaysInMonth returns the number of days for this month.

func DurationAs ¶

func DurationAs(d, as time.Duration) string

DurationAs formats a duration as the given time unit, with fractions (if any).

For example DurationAs(d, time.Millisecond) will return "0.05" for 50 microseconds.

Use Round() if you want to limit the precision.

func EndOf ¶

func EndOf(t time.Time, p Period) time.Time

EndOf adjusts the time to the end of the given period.

For example EndOf(t, QuarterHour) with "15:19" will adjust the time to "15:30".

func FromString ¶

func FromString(s string) time.Time

FromString creates a new date from a string according to the layout:

2006-01-02 15:04:05 MST

Any part on the right can be omitted; for example "2020-01-01" will create a new date without any time, or "2020-01-01 13" will create a date with the hour set.

A timezone can always be added, for example "2020-01-01 13 CET".

This will panic on errors. This is mostly useful in tests to quickly create a date without too much ceremony.

func LastInMonth ¶

func LastInMonth(t time.Time) bool

LastInMonth reports if the current day is the last day in this month.

func LeapYear ¶

func LeapYear(t time.Time) bool

LeapYear reports if this year is a leap year according to the Gregorian calendar.

func MustParse ¶

func MustParse(layout, value string) time.Time

MustParse is like time.Parse, but will panic on errors.

func SetNow ¶

func SetNow(t *testing.T, s string)

SetNow sets Now() and restores it when the test finishes.

The date is parsed with FromString().

func Sleep ¶

func Sleep(ctx context.Context, d time.Duration)

Sleep for d duration, or until the context times out.

func StartOf ¶

func StartOf(t time.Time, p Period) time.Time

StartOf adjusts the time to the start of the given period.

For example StartOf(t, QuarterHour) with "15:19" will adjust the time to "15:15".

func Takes ¶

func Takes(f func()) time.Duration

Takes records how long the execution of f takes.

func Unpack ¶

func Unpack(t time.Time) (year int, month time.Month, day, hour, minute, second, nanosecond int, loc *time.Location)

Unpack a time to its individual components.

Types ¶

type Diff ¶

type Diff struct {
	Years, Months, Weeks, Days int
	Hours, Mins, Secs          int
}

Diff represents the difference between two times.

func (Diff) String ¶

func (d Diff) String() string

TODO: i18n this.

type Durations ¶

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

Durations is a list of time.Durations.

This is useful if you want to record a list of durations; for example to keep track of performance metrics.

All operations are thread-safe.

func NewDurations ¶

func NewDurations(max int) Durations

NewDurations creates a new Durations.

The maximum size of the list is set to max items. After this, the oldest entries will be removed. Set to not have an upper limit.

func (*Durations) Append ¶

func (d *Durations) Append(add ...time.Duration)

Append durations to the list.

func (Durations) Distrubute ¶

func (d Durations) Distrubute(n int) []Durations

Distrubute the list of Durations in n blocks.

For example with Distribute(5) it returns 5 set of durations, from the fastest 20% to the slowest 20%.

func (*Durations) Grow ¶

func (d *Durations) Grow(n int)

Grow the list of durations for another n durations.

After Grow(n), at least n items can be appended without another allocation.

Grow will panic if n is negative or if the list can't grow (i.e. larger than MaxInt items).

func (Durations) Len ¶

func (d Durations) Len() int

Len returns the number of durations in this list.

func (Durations) List ¶

func (d Durations) List() []time.Duration

List returns a copy of all durations.

func (Durations) Max ¶

func (d Durations) Max() time.Duration

Max returns the maximum value in this list.

func (Durations) Mean ¶

func (d Durations) Mean() time.Duration

Mean returns the mean average of the durations in this list.

func (Durations) Median ¶

func (d Durations) Median() time.Duration

Median returns the median average of the durations in this list.

func (Durations) Min ¶

func (d Durations) Min() time.Duration

Min returns the minimum value in this list.

func (Durations) String ¶

func (d Durations) String() string

func (Durations) Sum ¶

func (d Durations) Sum() time.Duration

Sum returns the sum of all durations in this list.

func (Durations) Top ¶

func (d Durations) Top(percent int) Durations

Top gets the top percent items in this list.

e.g. with a list of 200 durations, Top(10) returns the top 10% longest durations (20 of them). Use negative numbers to get the bottom percentile (the fastest 10%).

The return value is a copy.

Numbers higher than 100 or lower than -100 will panic.

type Period ¶

type Period uint8

Period to adjust or align a time by.

const (
	Second Period
	Minute
	QuarterHour
	HalfHour
	Hour
	Day
	WeekMonday
	WeekSunday
	Month
	Quarter
	HalfYear
	Year
)

Periods to adjust or align a time by.

func Week ¶

func Week(sundayStartsWeek bool) Period

Week returns WeekSunday or WeekMonday.

func (Period) String ¶

func (p Period) String() string

type Range ¶

type Range struct {
	Start time.Time `json:"start"`
	End   time.Time `json:"end"`
	// contains filtered or unexported fields
}

A Range represents a time range from Start to End.

The timezone is always taken from the start time. The end's timezone will be adjusted if it differs.

func NewRange ¶

func NewRange(start time.Time) Range

NewRange creates a new range with the start date set.

func (Range) Current ¶

func (r Range) Current(p Period) Range

Current returns a copy with the start and end times set the current Period p.

This uses the value of the start time. Any value in the end time is ignored.

For example with NewRange("2020-06-18 14:00:00"):

Current(Month)       2020-06-01 00:00:00       → 2020-06-30 23:59:59
Current(WeekMonday)  2020-06-15 00:00:00 (Mon) → 2020-06-21 23:59:59 (Sun)

func (Range) Diff ¶

func (r Range) Diff(periods ...Period) Diff

Diff gets the difference between two dates.

Optionally pass any Period arguments to get the difference in those periods, ignoring any others. For example "Month, Day" would return "29 months, 6 days", instead of "2 years, 5 months, 6 days". The default is to get everything excluding weeks.

Adapted from https://stackoverflow.com/a/36531443/660921

func (Range) Equal ¶

func (r Range) Equal(cmp Range) bool

Equal reports whether this range equals the given time range with time.Time.Equal().

func (Range) From ¶

func (r Range) From(start time.Time) Range

From returns a copy with the start time set.

This will apply the timezone from the passed start time to the end time.

func (Range) In ¶

func (r Range) In(loc *time.Location) Range

In returns a copy with the timezone set to loc.

func (Range) IsZero ¶

func (r Range) IsZero() bool

IsZero reports whether both the start and end date represent the zero time instant with time.Time.Equal().

func (Range) Last ¶

func (r Range) Last(p Period) Range

Last returns a copy with the start and end times set to the last Period p.

This uses the value of the start time. Any value in the end time is ignored.

For example with NewRange("2020-06-18 14:00:00") (Thursday):

Last(Month)       2020-05-18 00:00:00       → 2020-06-18 23:59:59
Last(WeekMonday)  2020-06-11 00:00:00 (Wed) → 2020-06-18 23:59:59 (Thu)

func (Range) Locale ¶

func (r Range) Locale(l RangeLocale) Range

Locale sets the translated strings to use for this time range.

Any of the struct values will default to DefaultRangeLocale if one of the struct values isn't set, so this:

rng = rng.Locale(RangeLocale{Today: func() string { return ".." }})

Will work.

func (Range) Period ¶

func (r Range) Period(n int, p Period) Range

Period returns a copy withh the end time set to n Period from the start time.

This uses ztime.AddPeriod() and its "common sense" understanding of months.

func (Range) Round ¶

func (r Range) Round(d time.Duration) Range

Round returns the result of rounding the start and end dates to the nearest multiple of the given duration with time.Time.Round().

func (Range) String ¶

func (r Range) String() string

String shows the range from start to end as a human-readable representation; e.g. "current week", "last week", "previous month", etc.

It falls back to "Mon Jan 2–Mon Jan 2" if there's no clear way to describe it.

TODO: i18n for months names; should really use CLDR for "short" format too.

func (Range) To ¶

func (r Range) To(end time.Time) Range

To returns a copy with the end time set.

This will apply the timezone from the start time to the passed end time.

func (Range) Truncate ¶

func (r Range) Truncate(d time.Duration) Range

Truncate returns the result of rounding the start and end dates down to a multiple of the given duration with time.Time.Truncate().

func (Range) UTC ¶

func (r Range) UTC() Range

In returns a copy with the timezone set to UTC.

type RangeLocale ¶

type RangeLocale struct {
	Months      [12]string
	MonthsShort [12]string
	Days        [7]string
	DaysShort   [7]string
	Today       func() string             // "Today"
	Yesterday   func() string             // "Yesterday"
	Month       func(m time.Month) string // "January", "December"
	DayAgo      func(n int) string        // "1 day ago", "5 days ago"
	WeekAgo     func(n int) string        // "1 week ago", "5 weeks ago"
	MonthAgo    func(n int) string        // "1 month ago", "5 months ago"
}

RangeLocale can be used to translate the output of Range.String().

This defaults to DefaultRangeLocale.

type Time ¶

type Time struct{ time.Time }

Time wraps time.Time to add {Start,End}Of, AddPeriod(), and Unpack(). It also wraps operations that return time.Time to return ztime.Time.

func (Time) Add ¶

func (t Time) Add(d time.Duration) Time

func (Time) AddDate ¶

func (t Time) AddDate(years, months, days int) Time

func (Time) AddPeriod ¶

func (t Time) AddPeriod(n int, p Period) Time

func (Time) EndOf ¶

func (t Time) EndOf(p Period) Time

func (Time) In ¶

func (t Time) In(loc *time.Location) Time

func (Time) Local ¶

func (t Time) Local() Time

func (Time) Round ¶

func (t Time) Round(d time.Duration) Time

func (Time) StartOf ¶

func (t Time) StartOf(p Period) Time

func (Time) Truncate ¶

func (t Time) Truncate(d time.Duration) Time

func (Time) UTC ¶

func (t Time) UTC() Time

func (Time) Unpack ¶

func (t Time) Unpack() (year int, month time.Month, day, hour, minute, second, nanosecond int, loc *time.Location)

Source Files ¶

cal.go duration.go durations.go locale.go now.go range.go time.go ztime.go