Go ISO8601 Duration

A small, zero alloc and high performance libary for parsing ISO8601 compliant duration format into Go time compatible representation.

go get github.com/xnacly/go-iso8601-duration

Features

• ISO8601 duration parsing formats: [+-]P[n]Y[n]W[n]M[n]DT[n]H[n]M[n]S via goiso8601duration.From:
  • aligned with ECMAScript: Temporal - 7 Temporal.Duration Objects and ISO8601
• Interop with time.Time and time.Duration via:
  • goiso8601duration.Duration.Apply(time.Time) time.Time
  • goiso8601duration.Duration.Duration() time.Duration
  • goiso8601duration.FromDuration(time.Duration) goiso8601duration.Duration
• Serializing goiso8601duration.Duration to the correct format goiso8601duration.Duration.String
• JSON serialisation support via json.Unmarshaller and json.Marshaller
• High quality errors with position context.

Example

package main

import (
    "fmt"
    "time"

    "github.com/xnacly/go-iso8601-duration"
)

func Must[T any](t T, err error) T {
	if err != nil {
		panic(err)
	}
	return t
}

func main() {
	rawDuration := "PT1H30M12S"
	duration := Must(goiso8601duration.From(rawDuration))

	// 1h30m12s PT1H30M12S
	fmt.Println(duration.Duration().String(), duration.String())

	// 01:00:00 02:30:12
	fmt.Println(
		time.
			Unix(0, 0).
			Format(time.TimeOnly),
		duration.
			Apply(time.Unix(0, 0)).
			Format(time.TimeOnly),
	)

	type arrival struct {
		In goiso8601duration.Duration `json:"in"`
	}

	asJson := Must(
		json.Marshal(
			arrival{
				In: goiso8601duration.FromDuration(
					12*time.Minute + 43*time.Second,
				),
			},
		),
	)

	// {"in":"PT12M43S"}
	fmt.Println(string(asJson))

	var a arrival
	json.Unmarshal(asJson, &a)

	// {In:PT12M43S}
	fmt.Printf("%+v\n", a)
}

Benchmarks

Reproduce with:

goos: linux
goarch: amd64
pkg: github.com/xnacly/go-iso8601-duration
cpu: Intel(R) Core(TM) Ultra 9 275HX
BenchmarkDuration/P0D-24                        165412600                 6.97 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/PT15H-24                      155630031                 7.80 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P1W-24                        171056552                 7.08 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P15W-24                       163372800                 7.00 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P1Y15W-24                     145697648                 8.48 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P15Y-24                       160867038                 7.13 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P15Y3M-24                     147443806                 8.57 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P15Y3M41D-24                   99545108                11.50 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/PT15M-24                      152095197                 7.46 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/PT15M10S-24                   100000000                11.59 ns/op           0 B/op          0 allocs/op
BenchmarkDuration/P3Y6M4DT12H30M5S-24            57697164                25.43 ns/op           0 B/op          0 allocs/op
PASS
ok      github.com/xnacly/go-iso8601-duration   20.435s