README
¶
duration
A zero dependency library to overcome issues with lack of days and weeks in standard library's duration as well as ease parsing for common date/times and print durations without zeroes (eg 1d3m instead of 24h3m0s) - it originated in tclock and is available also via dflag for dynamic flag (includes regular duration.Flag for simple flags parsing with new duration in days and weeks).
See the godoc for examples and more details.
See also [golang/go#74813]
Usage
import fortio.org/duration and go mod tidy, or
go get fortio.org/duration@latest
Documentation
¶
Overview ¶
Package duration allows duration parsing with "d" for days (24 hours) and "w" for week (7 days). For output direction, it implements a more human friendly formatting of durations removing all 0 values and using days and weeks when applicable. Includes helpers for command line flag duration parsing and for date/time parsing replacement. See also fortio.org/dflag if you need dynamic flags with days/weeks support.
Index ¶
- Constants
- Variables
- func Flag(name string, value time.Duration, usage string) *time.Duration
- func FlagSet(fs *flag.FlagSet, name string, value time.Duration, usage string) *time.Duration
- func FlagSetVar(fs *flag.FlagSet, p *time.Duration, name string, value time.Duration, ...)
- func FlagVar(p *time.Duration, name string, value time.Duration, usage string)
- func NextTime(now, d time.Time) time.Time
- func Parse(s string) (time.Duration, error)
- func ParseDateTime(now time.Time, s string) (time.Time, error)
- type Duration
Examples ¶
Constants ¶
const ( Day = 24 * time.Hour Week = 7 * Day )
Variables ¶
var ErrDateTimeParsing = errors.New("expecting one of YYYY-MM-DD HH:MM:SS, YYYY-MM-DD, HH:MM:SS, or H:MM am/pm")
Functions ¶
func Flag ¶
Flag defines a duration flag with the specified name, default value, and usage string, like flag.Duration but supporting durations in days (24 hours) and weeks (7 days) in addition to the other stdlib units. Replacement for flag.Duration.
Example ¶
package main
import (
"flag"
"fmt"
"fortio.org/duration"
)
func main() {
f := duration.Flag("duration-flag", 1*duration.Day, "test `duration`")
// and then use *f normally and the users can use days, weeks etc.
// to test/show:
flv := flag.Lookup("duration-flag").Value
fmt.Println("Default:", flv.String())
flv.Set("1d1h") // no error
fmt.Println("After set:", flv.String())
fmt.Println("After set (dereferenced):", *f)
}
Output: Default: 1d After set: 1d1h After set (dereferenced): 25h0m0s
func FlagSet ¶ added in v1.0.0
FlagSet is like Flag but for the specified flag set. Replacement for flag.FlagSet.Duration.
func FlagSetVar ¶ added in v1.0.0
FlagSet is like FlagVar but for the specified flag set. Replacement for flag.FlagSet.DurationVar.
func FlagVar ¶ added in v1.0.0
FlagVar is like Flag but binds the value to variable referenced. Replacement for flag.DurationVar.
func NextTime ¶
NextTime takes a partially parsed time.Time (without date) and returns the time in the future relative to now with same HH:MM:SS. It will adjust to daylight savings so that time maybe 25h or 23h in the future around daylight savings transitions. If it's a double 3a-4a transition, and now is the first 3:10am asking for 3:05a will not give the very next 3:05a (same day) but instead the one next day ie at minimum 23h later. The timezone of now is the one used and timezone of d should be the same.
func Parse ¶
Parse parses a duration string with "d" for days (24 hours) and "w" for weeks (7 days) in addition to what stdlib time.ParseDuration supports.
Example ¶
package main
import (
"fmt"
"fortio.org/duration"
)
func main() {
d, err := duration.Parse("1w 2d 3h 4m")
if err != nil {
fmt.Println("Error:", err)
return
}
fmt.Println("Parsed duration (std):", d)
fmt.Println("Parsed duration (new):", duration.Duration(d))
}
Output: Parsed duration (std): 219h4m0s Parsed duration (new): 1w2d3h4m
func ParseDateTime ¶
ParseDateTime parses date/times in one of the following format:
- Date and 24h time: YYYY-MM-DD HH:MM:SS
- Just a date: YYYY-MM-DD
- Just a 24h time: HH:MM:SS
- Just a time (12-hour, 'kitchen' style): H:MM AM/PM
When date is missing next same time from now is used (ie later that day or next, up to 25h from now). When the time is missing 00:00 is assumed. The time/date is interpreted in relation to the location and timezone of the `now` parameter (local time per TZ environment when using time.Now() for instance).
Types ¶
type Duration ¶
Duration is like time.Duration but supports days (24h) and weeks (7d) in addition to the units supported by time.Duration. This is mostly for internal use for the Flag function which still returns a standard duration for compatibility. Or if you want the more compact formatting with days and weeks and no zeroes in Duration.String.
Source Files