https://github.com/karrick/tparse
time parsing library for Go; supports more time units than standard library
https://github.com/karrick/tparse
duration-string golang parse
Last synced: 5 months ago
JSON representation
time parsing library for Go; supports more time units than standard library
- Host: GitHub
- URL: https://github.com/karrick/tparse
- Owner: karrick
- License: mit
- Created: 2015-10-22T18:19:05.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2020-11-20T21:51:12.000Z (about 5 years ago)
- Last Synced: 2025-01-11T05:24:28.155Z (about 1 year ago)
- Topics: duration-string, golang, parse
- Language: Go
- Homepage:
- Size: 43.9 KB
- Stars: 43
- Watchers: 3
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# tparse
`Parse` will return the time corresponding to the layout and value.
It also parses floating point epoch values, and values of "now",
"now+DURATION", and "now-DURATION".
In addition to the duration abbreviations recognized by
`time.ParseDuration`, tparse recognizes various tokens for days,
weeks, months, and years, as well as tokens for seconds, minutes, and
hours.
Like `time.ParseDuration`, it accepts multiple fractional scalars, so
"now+1.5days-3.21hours" is evaluated properly.
## Documentation
In addition to this handy README.md file, documentation is available
in godoc format at
[](https://godoc.org/github.com/karrick/tparse).
## Examples
### ParseNow
`ParseNow` can parse time values that are relative to the current
time, by specifying a string starting with "now", a '+' or '-' byte,
followed by a time duration.
```Go
package main
import (
"fmt"
"os"
"time"
"github.com/karrick/tparse"
)
func main() {
actual, err := tparse.ParseNow(time.RFC3339, "now+1d-3w4mo+7y6h4m")
if err != nil {
fmt.Fprintf(os.Stderr, "error: %s\n", err)
os.Exit(1)
}
fmt.Printf("time is: %s\n", actual)
}
```
### ParseWithMap
`ParseWithMap` can parse time values that use a base time other than "now".
```Go
package main
import (
"fmt"
"os"
"time"
"github.com/karrick/tparse"
)
func main() {
m := make(map[string]time.Time)
m["end"] = time.Now()
start, err := tparse.ParseWithMap(time.RFC3339, "end-12h", m)
if err != nil {
fmt.Fprintf(os.Stderr, "error: %s\n", err)
os.Exit(1)
}
fmt.Printf("start: %s; end: %s\n", start, end)
}
```
### AddDuration
`AddDuration` is used to compute the value of a duration string and
add it to a known time. This function is used by the other library
functions to parse all duration strings.
The following tokens may be used to specify the respective unit of
time:
* Nanosecond: ns
* Microsecond: us, µs (U+00B5 = micro symbol), μs (U+03BC = Greek letter mu)
* Millisecond: ms
* Second: s, sec, second, seconds
* Minute: m, min, minute, minutes
* Hour: h, hr, hour, hours
* Day: d, day, days
* Week: w, wk, week, weeks
* Month: mo, mon, month, months
* Year: y, yr, year, years
```Go
package main
import (
"fmt"
"os"
"time"
"github.com/karrick/tparse"
)
func main() {
now := time.Now()
another, err := tparse.AddDuration(now, "+1d3w4mo-7y6h4m")
if err != nil {
fmt.Fprintf(os.Stderr, "error: %s\n", err)
os.Exit(1)
}
fmt.Printf("time is: %s\n", another)
}
```
### AbsoluteDuration
When you would rather have the `time.Duration` representation of a
duration string, there is a function for that, but with a
caveat.
First, not every month has 30 days, and therefore Go does not have a
`time.Duration` type constant to represent one month.
When I add one month to February 3, do I get March 3 or March 4?
Depends on what the year is and whether or not that year is a leap
year.
Is one month always 30 days? Is one month 31 days, or 28, or 29? I did
not want to have to answer this question, so I defaulted to saying the
length of one month depends on which month and year, and I allowed the
Go standard library to add duration concretely to a given moment in
time.
Consider the below two examples of calling `AbsoluteDuration` with the
same duration string, but different base times.
```Go
func ExampleAbsoluteDuration() {
t1 := time.Date(2009, time.November, 10, 23, 0, 0, 0, time.UTC)
d1, err := AbsoluteDuration(t1, "1.5month")
if err != nil {
fmt.Println(err)
return
}
fmt.Println(d1)
t2 := time.Date(2020, time.February, 10, 23, 0, 0, 0, time.UTC)
d2, err := AbsoluteDuration(t2, "1.5month")
if err != nil {
fmt.Println(err)
return
}
fmt.Println(d2)
// Output:
// 1080h0m0s
// 1056h0m0s
}
```
## Benchmark against goparsetime
```Bash
GO111MODULE=on go test -bench=. -tags goparsetime
```