README.md
1# durafmt
2
3[](https://travis-ci.org/hako/durafmt) [](https://goreportcard.com/report/github.com/hako/durafmt) [](https://codecov.io/gh/hako/durafmt) [](https://godoc.org/github.com/hako/durafmt)
4[](https://www.codetriage.com/hako/durafmt)
5
6
7
8durafmt is a tiny Go library that formats `time.Duration` strings (and types) into a human readable format.
9
10```
11go get github.com/hako/durafmt
12```
13
14# Why
15
16If you've worked with `time.Duration` in Go, you most likely have come across this:
17
18```
1953m28.587093086s // :)
20```
21
22The above seems very easy to read, unless your duration looks like this:
23
24```
25354h22m3.24s // :S
26```
27
28# Usage
29
30### durafmt.ParseString()
31
32```go
33package main
34
35import (
36 "fmt"
37 "github.com/hako/durafmt"
38)
39
40func main() {
41 duration, err := durafmt.ParseString("354h22m3.24s")
42 if err != nil {
43 fmt.Println(err)
44 }
45 fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds
46 // duration.String() // String representation. "2 weeks 18 hours 22 minutes 3 seconds"
47}
48```
49
50### durafmt.ParseStringShort()
51
52Version of `durafmt.ParseString()` that only returns the first part of the duration string.
53
54```go
55package main
56
57import (
58 "fmt"
59 "github.com/hako/durafmt"
60)
61
62func main() {
63 duration, err := durafmt.ParseStringShort("354h22m3.24s")
64 if err != nil {
65 fmt.Println(err)
66 }
67 fmt.Println(duration) // 2 weeks
68 // duration.String() // String short representation. "2 weeks"
69}
70```
71
72### durafmt.Parse()
73
74```go
75package main
76
77import (
78 "fmt"
79 "time"
80 "github.com/hako/durafmt"
81)
82
83func main() {
84 timeduration := (354 * time.Hour) + (22 * time.Minute) + (3 * time.Second)
85 duration := durafmt.Parse(timeduration).String()
86 fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds
87}
88```
89
90#### LimitFirstN()
91
92Like `durafmt.ParseStringShort()` but for limiting the first N parts of the duration string.
93
94```go
95package main
96
97import (
98 "fmt"
99 "time"
100 "github.com/hako/durafmt"
101)
102
103func main() {
104 timeduration := (354 * time.Hour) + (22 * time.Minute) + (3 * time.Second)
105 duration := durafmt.Parse(timeduration).LimitFirstN(2) // // limit first two parts.
106 fmt.Println(duration) // 2 weeks 18 hours
107}
108```
109
110#### Custom Units
111
112Like `durafmt.Units{}` and `durafmt.Durafmt.Format(units)` to stringify duration with custom units.
113
114```go
115package main
116
117import (
118 "fmt"
119 "time"
120 "github.com/hako/durafmt"
121)
122
123func main() {
124 timeduration := (354 * time.Hour) + (22 * time.Minute) + (1 * time.Second) + (100*time.Microsecond)
125 duration := durafmt.Parse(timeduration)
126 // units in portuguese
127 units, err := durafmt.DefaultUnitsCoder.Decode("ano,semana,dia,hora,minuto,segundo,milissegundo,microssegundo")
128 if err != nil {
129 panic(err)
130 }
131 fmt.Println(duration.Format(units)) // 2 semanas 18 horas 22 minutos 1 segundo 100 microssegundos
132
133 // custom plural (singular:plural)
134 units, err = durafmt.DefaultUnitsCoder.Decode("ano,semana:SEMANAS,dia,hora,minuto,segundo,milissegundo,microssegundo")
135 if err != nil {
136 panic(err)
137 }
138 fmt.Println(duration.Format(units)) // 2 SEMANAS 18 horas 22 minutos 1 segundo 100 microssegundos
139}
140```
141
142# Contributing
143
144Contributions are welcome! Fork this repo, add your changes and submit a PR.
145
146If you would like to fix a bug, add a feature or provide feedback you can do so in the issues section.
147
148durafmt is tested against `golangci-lint` and you can run tests with `go test`.
149
150When contributing, running `go test; go vet; golint` or `golangci-lint` is recommended.
151
152# License
153
154MIT
155
){kind=link}
){kind=link}
){kind=link}
){kind=link}