durafmt

README

durafmt

durafmt is a tiny Go library that formats time.Duration strings (and types) into a human readable format.

go get github.com/hako/durafmt

Why

If you've worked with time.Duration in Go, you most likely have come across this:

53m28.587093086s // :)

The above seems very easy to read, unless your duration looks like this:

354h22m3.24s // :S

Usage

durafmt.ParseString()

package main

import (
	"fmt"
	
	"github.com/hako/durafmt"
)

func main() {
	duration, err := durafmt.ParseString("354h22m3.24s")
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds
	// duration.String() // String representation. "2 weeks 18 hours 22 minutes 3 seconds"
}

durafmt.ParseStringShort()

Version of durafmt.ParseString() that only returns the first part of the duration string.

package main

import (
	"fmt"
	
	"github.com/hako/durafmt"
)

func main() {
	duration, err := durafmt.ParseStringShort("354h22m3.24s")
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(duration) // 2 weeks
	// duration.String() // String short representation. "2 weeks"
}

durafmt.Parse()

package main

import (
	"fmt"
	"time"
	
	"github.com/hako/durafmt"
)

func main() {
	timeduration := (354 * time.Hour) + (22 * time.Minute) + (3 * time.Second)
	duration := durafmt.Parse(timeduration).String()
	fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds
}

LimitFirstN()

Like durafmt.ParseStringShort() but for limiting the first N parts of the duration string.

package main

import (
	"fmt"
	"time"
	
	"github.com/hako/durafmt"
)

func main() {
	timeduration := (354 * time.Hour) + (22 * time.Minute) + (3 * time.Second)
	duration := durafmt.Parse(timeduration).LimitFirstN(2) // // limit first two parts.
	fmt.Println(duration) // 2 weeks 18 hours
}

Contributing

Contributions are welcome! Fork this repo, add your changes and submit a PR.

If you would like to fix a bug, add a feature or provide feedback you can do so in the issues section.

durafmt is tested against golangci-lint and you can run tests with go test.

When contributing, running go test; go vet; golint or golangci-lint is recommended.

License

MIT

Documentation

Overview

Package durafmt formats time.Duration into a human readable format.

Index

• type Durafmt
  • func Parse(dinput time.Duration) *Durafmt
  • func ParseShort(dinput time.Duration) *Durafmt
  • func ParseString(input string) (*Durafmt, error)
  • func ParseStringShort(input string) (*Durafmt, error)
  • func (d *Durafmt) Duration() time.Duration
  • func (d *Durafmt) LimitFirstN(n int) *Durafmt
  • func (d *Durafmt) LimitToUnit(unit string) *Durafmt
  • func (d *Durafmt) String() string

Examples

• Durafmt.LimitFirstN
• Durafmt.LimitToUnit
• Parse
• ParseShort
• ParseString
• ParseString (Sequence)
• ParseStringShort

Types

type Durafmt

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

Durafmt holds the parsed duration and the original input duration.

func Parse

func Parse(dinput time.Duration) *Durafmt

Parse creates a new *Durafmt struct, returns error if input is invalid.

Example

timeduration := (354 * time.Hour) + (22 * time.Minute) + (3 * time.Second)
duration := Parse(timeduration).String()
fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds

func ParseShort

func ParseShort(dinput time.Duration) *Durafmt

ParseShort creates a new *Durafmt struct, short form, returns error if input is invalid. It's shortcut for `Parse(dur).LimitFirstN(1)`

Example

Version of durafmt.Parse() that only returns the first part of the duration string.

timeduration := (354 * time.Hour) + (22 * time.Minute) + (3 * time.Second)
duration := ParseShort(timeduration).String()
fmt.Println(duration) // 2 weeks

func ParseString

func ParseString(input string) (*Durafmt, error)

ParseString creates a new *Durafmt struct from a string. returns an error if input is invalid.

Example

duration, err := ParseString("354h22m3.24s")
if err != nil {
	fmt.Println(err)
}
fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds
// duration.String() // String representation. "2 weeks 18 hours 22 minutes 3 seconds"

Example (Sequence)

for hours := 1.0; hours < 12.0; hours++ {
	hour := fmt.Sprintf("%fh", math.Pow(2, hours))
	duration, err := ParseString(hour)
	if err != nil {
		fmt.Println(err)
	}
	fmt.Println(duration) // 2 hours, 4 hours, ...
}

func ParseStringShort

func ParseStringShort(input string) (*Durafmt, error)

ParseStringShort creates a new *Durafmt struct from a string, short form returns an error if input is invalid. It's shortcut for `ParseString(durStr)` and then calling `LimitFirstN(1)`

Example

Version of durafmt.ParseString() that only returns the first part of the duration string.

duration, err := ParseStringShort("354h22m3.24s")
if err != nil {
	fmt.Println(err)
}
fmt.Println(duration) // 2 weeks 18 hours 22 minutes 3 seconds
// duration.String() // String representation. "2 weeks 18 hours 22 minutes 3 seconds"

func (*Durafmt) Duration

func (d *Durafmt) Duration() time.Duration

func (*Durafmt) LimitFirstN

func (d *Durafmt) LimitFirstN(n int) *Durafmt

LimitFirstN sets the output format, outputing only first N elements. n == 0 means no limit.

Example

duration, err := ParseString("354h22m3.24s")
if err != nil {
	fmt.Println(err)
}
duration = duration.LimitFirstN(2)
fmt.Println(duration) // 2 weeks 18 hours
// duration.String() // String representation. "2 weeks 18 hours"

func (*Durafmt) LimitToUnit

func (d *Durafmt) LimitToUnit(unit string) *Durafmt

LimitToUnit sets the output format, you will not have unit bigger than the UNIT specified. UNIT = "" means no restriction.

Example

duration, err := ParseString("354h22m3.24s")
if err != nil {
	fmt.Println(err)
}
duration = duration.LimitToUnit("days")
fmt.Println(duration) // 14 days 18 hours 22 minutes 3 seconds
// duration.String() // String representation. "14 days 18 hours 22 minutes 3 seconds"

func (*Durafmt) String

func (d *Durafmt) String() string

String parses d *Durafmt into a human readable duration.