See the new home at https://github.com/nav-inc/datetime
datetime provides a Parse function for turning commonly-used
ISO 8601 date/time formats into
Golang time.Time variables. datetime.Parse takes two arguments:
- the string you want to parse
- the timezone location to be used if there's not one specified inside the string
Unlike Go's built-in RFC-3339 time format, this package automatically supports ISO 8601 date and time stamps with varying levels of granularity. Examples:
package main
import (
"fmt"
"time"
"github.com/nav-inc/datetime"
)
func main() {
// just a year, defaulting to the time.UTC timezone
fmt.Println(datetime.Parse("2007", time.UTC)) // 2007-01-01 00:00:00 +0000 UTC <nil>
// a year and a month, this time defaulting to time.Local timezone
fmt.Println(datetime.Parse("2007-11", time.Local)) // 2007-11-01 00:00:00 -0600 MDT <nil>
// a full date
fmt.Println(datetime.Parse("2007-11-22", time.UTC)) // 2007-11-22 00:00:00 +0000 UTC <nil>
// adding time
fmt.Println(datetime.Parse("2007-11-22T12:30:22", time.UTC)) // 2007-11-22 12:30:22 -0700 MST <nil>
// fractions of a second
fmt.Println(datetime.Parse("2007-11-22T12:30:22.321", time.UTC)) // 2007-11-22 12:30:22.321 -0700 MST <nil>
// omitting dashes and colons, as ISO 8601 allows
fmt.Println(datetime.Parse("20071122T123022", time.UTC)) // 2007-11-22 12:30:22 -0700 MST <nil>
// a timezone offset inside the input will override the default provided to datetime.Parse
fmt.Println(datetime.Parse("2007-11-22T12:30:22+0800", time.Local)) // 2007-11-22 12:30:22 +0800 +0800 <nil>
// adding separators to the offset too
fmt.Println(datetime.Parse("2007-11-22T12:30:22+08:00", time.UTC)) // 2007-11-22 12:30:22 +0800 +08:00 <nil>
// using a shorthand for UTC
fmt.Println(datetime.Parse("2007-11-22T12:30:22Z", time.Local)) // 2007-11-22 12:30:22 +0000 UTC <nil>
}DefaultUTC and DefaultLocal types are also provided. Used as struct fields, their Scan, Value,
and UnmarshalJSON methods support easy parsing of ISO 8601 timestamps from external systems.