dur

README

dur

a library to parse:

• time specifications and convert them to durations.
• datetime specifications and convert them to unix timestamps.

Meant to work like Graphite's from/until parsing. which aims to support all at(1) formats also. So do we. see some notes below.

Durations

Similar to time.ParseDuration which has valid time units "ns", "us" (or "µs"), "ms", "s", "m", "h". which allows signed sequences and optional fractions like "300ms", "-1.5h" or "2h45m".

But we work with larger units (and more forgiving ways to specify them) in this range: s/sec/secs/second/seconds, m/min/mins/minute/minutes, h/hour/hours, d/day/days, w/week/weeks, mon/month/months, y/year/years We however do not allow fractions or negative numbers. Note that this library takes a shortcut to provide convenience: a day = 24 hours, week = 7days, mon = 30 times 24 hours, year is 365 days. If these inaccuracies are a problem to you, do your own date math.

E.g.: '7d', '1y6mon', '1hour15min3s'

Datetimes

Functions to convert human specified date time specifications into timestamps. Supported formats:

• now-<duration> now with duration subtracted. (for duration formats see above)
• -<duration>: shortcut for the above
• now+<duration> now with duration added. (for duration formats see above)
• HH:MM_YYMMDD
• YYYYMMDD
• MM/DD/YY
• integer: unix timestamp
• <monthname> <num> like january 3 or march 8
• monday, tuesday last (or current day if matching) day.
• at formats : now, today, midnight, noon, teatime, midnight yesterday, 6pm tomorrow, 3AM yesterday

See the code and unit tests for details.

Notes on compatibility and implementation.

• Graphite #1691: monthname+num goes back in time and clears HH/MM fields (unlike at): we follow graphite.
• Graphite applies the appropriate timezone (given via tz argument or defaulting to what's configured in the config file) to:
  1. the interpretation of datetime specifications where applicable.
  2. the rendering of output timestamps in images (does not apply for metrictank) Though #639 shows (1) doesn't always work (not for at-style patterns). Here we apply this consistently.
• Graphite #263 shows that patterns like "6pm+yesterday" sometimes don't work. Here it does.
• Graphite doesn't seem to support all the at syntax, and we aim to support the same as Graphite for now (which is already quite much!). Going 100% is not a high prio for now.

Documentation

Overview

Package dur is a package to convert string duration and time specifications to numbers of seconds and to unix timestamps. It aims to support the full specification as outlined in http://graphite.readthedocs.io/en/latest/render_api.html#from-until which incorporates the formats defined by `at`.

this package works with the following shorthands: Duration : unsigned (positive) number of seconds NDuration: like Duration, but non-zero.

Index

• func FormatDuration(seconds uint32) string
• func IsTime(s string) bool
• func MustParseDateTime(s string, loc *time.Location, now time.Time, def uint32) uint32
• func MustParseDuration(desc, s string) uint32
• func MustParseNDuration(desc, s string) uint32
• func ParseDateTime(s string, loc *time.Location, now time.Time, def uint32) (uint32, error)
• func ParseDuration(s string) (uint32, error)
• func ParseNDuration(s string) (uint32, error)
• func ParseTime(s string) (hour, minute int, err error)
• func RewindToWeekday(t time.Time, day time.Weekday) time.Time

Functions

func FormatDuration

func FormatDuration(seconds uint32) string

FormatDuration takes a number of seconds and returns a minimal string represention that can be parsed by ParseDuration(). Due to its ambiguity and length, we don't use "month" units in the returned value.

func IsTime

func IsTime(s string) bool

func MustParseDateTime

func MustParseDateTime(s string, loc *time.Location, now time.Time, def uint32) uint32

MustParseDateTime parses a format string to a unix timestamp, or panics otherwise

func MustParseDuration

func MustParseDuration(desc, s string) uint32

MustParseDuration parses a format string to a number of seconds, or panics otherwise unit defaults to s if not specified

func MustParseNDuration

func MustParseNDuration(desc, s string) uint32

MustParseNDuration parses a format string to a non-zero number of seconds, or panics otherwise unit defaults to s if not specified

func ParseDateTime

func ParseDateTime(s string, loc *time.Location, now time.Time, def uint32) (uint32, error)

ParseDateTime parses a format string to a unix timestamp, or error otherwise. 'loc' is the timezone to use for interpretation (when applicable) 'now' is a reference, in case a relative specification is given. 'def' is a default in case an empty specification is given.

func ParseDuration

func ParseDuration(s string) (uint32, error)

ParseDuration parses a format string to a number of seconds, or error otherwise valid units are s/sec/secs/second/seconds, m/min/mins/minute/minutes, h/hour/hours, d/day/days, w/week/weeks, mon/month/months, y/year/years unit defaults to s if not specified

func ParseNDuration

func ParseNDuration(s string) (uint32, error)

ParseNDuration parses a format string to a non-zero number of seconds, or error otherwise unit defaults to s if not specified

func ParseTime

func ParseTime(s string) (hour, minute int, err error)

ParseTime parses a time and returns hours and minutes

func RewindToWeekday

func RewindToWeekday(t time.Time, day time.Weekday) time.Time

RewindToWeekday moves a datetime back to the last occurence of the given weekday (potentially that day without needing to seek back) while retaining hour/minute/second values.