Repository files navigation

chrono provides additional functionality and improved ergonomics to complement the Go standard library'stime package. It is not a replacement for, nor an extension of, thetime package, but for certain use cases for which it was not explicitly designed to support,chrono can help to simplify and clarify.

chrono is also designed to look and feel like Go. Many of the ideas and much of the API is inspired bytime, and should therefore feel familiar. That said, capable time and date libraries exist for most mainstream languages, andchrono has taken inspiration from several besides Go'stime package, including Rust, Java and Python.

Not all features are complete yet. See theroadmap for the current state. If in doubt,create an issue to ask a question or open a feature request.

Often it's necessary to represent civil time, or dates and times without a time zone or time offset component. Usually, this is achieved using the standard library'stime.Date function and setting the time values to0. Alternatively, some people use Google'scivil package.

chrono provides 3 types for dealing with these use cases:LocalDate (a date without a time),LocalTime (a time without a date), andLocalDateTime (a combination ofLocalDate andLocalTime).

ALocalDate and aLocalTime are initialized with numeric values. ALocalDateTime can either be initialized with numeric values, or by combining aLocalDate andLocalTime (as below):

date:=chrono.LocalDateOf(2007,chrono.May,20)time:=chrono.LocalTimeOf(12,30,15,0)fmt.Println(chrono.OfLocalDateAndTime(date,time))

✅See moreLocalDate examples.
✅See moreLocalTime examples.
✅See moreLocalDateTime examples.

chrono differs from thetime package because it uses format codes instead of a mnemonic device. The format codes are borrowed fromstrftime/strptime, and therefore maybe familiar from other languages. The full list is documentedhere, but here's a simple example of formatting a time:

time:=chrono.LocalTimeOf(12,30,15,0)fmt.Println(time.Format("%H:%M:%S"))

And parsing a time:

vartime chrono.LocalTimefmt.Println(time.Parse("%H:%M:%S","12:30:15"))

There are also predefined layouts, similar to thetime package, but with the addition of layouts compatible with ISO 8601.

The example above assumes that you know how a date time string is formatted, but that's not always the case. For these situations,ParseToLayout accepts just a string and attempts to parse it, also returning the layout string.

varc chrono.OffsetDateTimefmt.Println(chrono.ParseToLayout("2006-04-09",    chrono.ParseConfig{},&c,))// %Y-%m-%d

To access this function you need to build with-tag parse.

This API is incomplete and subject to change until a stable release is reached.

When interfacing with systems where thetime package's duration formatting is not understood, ISO 8601 is a commonly-adopted standard.

time doesn't support ISO 8601 durations notation. A simple one-liner that uses only the seconds component is possible, but this is neither readable nor solves the problem of parsing such strings:

vard time.Durationfmt.Printf("PT%dS",int(d.Seconds()))

chrono supports bothparsing andformatting of ISO 8601 strings:

period,duration,_:=chrono.ParseDuration("P3Y6M4DT1M5S")fmt.Println(chrono.FormatDuration(period,duration))

Alternatively, aPeriod andDuration can be initialized with numeric values:

period:= chrono.Period{Years:3,Months:6,Days:4}duration:=chrono.DurationOf(1*chrono.Hour+30*chrono.Minute+5*chrono.Second)fmt.Println(chrono.FormatDuration(period,duration))

✅See more examples.

Intervals as a concept are absent from thetime package.chrono introduces theInterval type, which can be used to represent the intervening time between two time points. This can be by reference to a pair of times (start and end), a start time and a duration, a duration and an end time, or just a duration.

Parsing and formatting of intervals using the ISO 8601 notation is supported as follows, including the use of repeating intervals:

interval,_:=chrono.ParseInterval("R5/2007-03-01T13:00:00Z/P1Y2M10DT2H30M")fmt.Println(interval.String())

✅See more examples.