iso8601

README

A fast ISO8601 date parser for Go

go get github.com/relvacode/iso8601

The built-in RFC3333 time layout in Go is too restrictive to support any ISO8601 date-time.

This library parses any ISO8601 date into a native Go time object without regular expressions.

Usage

package main

import "github.com/relvacode/iso8601"

// iso8601.Time can be used as a drop-in replacement for time.Time with JSON responses
type ExternalAPIResponse struct {
	Timestamp *iso8601.Time
}


func main() {
	// iso8601.ParseString can also be called directly
	t, err := iso8601.ParseString("2020-01-02T16:20:00")
}

Benchmark

goos: linux
goarch: amd64
pkg: github.com/relvacode/iso8601
cpu: AMD Ryzen 7 7840U w/ Radeon 780M Graphics      
BenchmarkParse-16               35880919                30.89 ns/op            0 B/op          0 allocs/op

Documentation

Overview

Package iso8601 is a utility for parsing ISO8601 datetime strings into native Go times. The standard library's RFC3339 reference layout can be too strict for working with 3rd party APIs, especially ones written in other languages.

Use the provided `Time` structure instead of the default `time.Time` to provide ISO8601 support for JSON responses.

Index

• Variables
• func Parse(inp []byte) (time.Time, error)
• func ParseISOZone(inp []byte) (*time.Location, error)
• func ParseInLocation(inp []byte, loc *time.Location) (time.Time, error)
• func ParseString(inp string) (time.Time, error)
• func ParseStringInLocation(inp string, loc *time.Location) (time.Time, error)
• type RangeError
  • func (e *RangeError) Error() string
• type Time
  • func (t *Time) UnmarshalJSON(b []byte) error
• type UnexpectedCharacterError
  • func (e *UnexpectedCharacterError) Error() string

Variables

var (
	// ErrZoneCharacters indicates an incorrect amount of characters was passed to ParseISOZone.
	ErrZoneCharacters = errors.New("iso8601: Expected between 3 and 6 characters for zone information")

	// ErrInvalidZone indicates an invalid timezone per the standard that doesn't violate any specific
	// character parsing rules.
	ErrInvalidZone = errors.New("iso8601: Specified zone is invalid")

	// ErrRemainingData indicates that there is extra data after a `Z` character.
	ErrRemainingData = errors.New("iso8601: Unexepected remaining data after `Z`")

	// ErrNotString indicates that a non string type was passed to the UnmarshalJSON method of `Time`.
	ErrNotString = errors.New("iso8601: Invalid json type (expected string)")

	// ErrPrecision indicates that there was too much precision (characters) given to parse
	// for the fraction of a second of the input time.
	ErrPrecision = errors.New("iso8601: Too many characters in fraction of second precision")
)

Functions

func Parse

func Parse(inp []byte) (time.Time, error)

Parse parses an ISO8601 compliant date-time byte slice into a time.Time object. If any component of an input date-time is not within the expected range then an *iso8601.RangeError is returned.

func ParseISOZone

func ParseISOZone(inp []byte) (*time.Location, error)

ParseISOZone parses the 5 character zone information in an ISO8601 date string. This function expects input that matches:

Z, z (UTC)
-0100
+0100
+01:00
-01:00
+01
+01:45
+0145

func ParseInLocation

func ParseInLocation(inp []byte, loc *time.Location) (time.Time, error)

ParseInLocation parses an ISO8601 compliant date-time byte slice into a time.Time object. If the input does not have timezone information, it will use the given location.

func ParseString

func ParseString(inp string) (time.Time, error)

ParseString parses an ISO8601 compliant date-time string into a time.Time object.

func ParseStringInLocation

func ParseStringInLocation(inp string, loc *time.Location) (time.Time, error)

ParseStringInLocation parses an ISO8601 compliant date-time string into a time.Time object. If the input does not have timezone information, it will use the given location.

Types

type RangeError

type RangeError struct {
	Value   string
	Element string
	Min     int
	Max     int
	Given   int
}

RangeError indicates that a value is not in an expected range.

func (*RangeError) Error

func (e *RangeError) Error() string

type Time

type Time struct {
	time.Time
}

Time is a helper object for parsing ISO8601 dates as a JSON string.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(b []byte) error

UnmarshalJSON decodes a JSON string or null into a iso8601 time

type UnexpectedCharacterError

type UnexpectedCharacterError struct {
	Character byte
}

UnexpectedCharacterError indicates the parser scanned a character that was not expected at that time.

func (*UnexpectedCharacterError) Error

func (e *UnexpectedCharacterError) Error() string