github.com/go-chrono/chrono@v0.0.0-20240102183611-532f0d0d7c34/README.md (about) 1 [![Go Reference](https://pkg.go.dev/badge/github.com/go-chrono/chrono.svg)](https://pkg.go.dev/github.com/go-chrono/chrono) 2 [![Maintenance](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/go-chrono/chrono/graphs/commit-activity) 3 [![GoReportCard example](https://goreportcard.com/badge/github.com/go-chrono/chrono)](https://goreportcard.com/report/github.com/go-chrono/chrono) 4 5 # `chrono` - supplementary time and date module 6 7 `chrono` provides additional functionality and improved ergonomics to complement the Go standard library's `time` package. It is not a replacement for, nor an extension of, the `time` package, but for certain use cases for which it was not explicitly designed to support, `chrono` can help to simplify and clarify. 8 9 `chrono` is also designed to look and feel like Go. Many of the ideas and much of the API is inspired by `time`, and should therefore feel familiar. That said, capable time and date libraries exist for most mainstream languages, and `chrono` has taken inspiration from several besides Go's `time` package, including Rust, Java and Python. 10 11 --- 12 13 **Not all features are complete yet. See the [roadmap](https://github.com/orgs/go-chrono/projects/1) for the current state. If in doubt, [create an issue](https://github.com/go-chrono/chrono/issues) to ask a question or open a feature request.** 14 15 --- 16 17 # Use cases 18 19 ## Local (or "civil") dates and times 20 21 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's `time.Date` function and setting the time values to `0`. Alternatively, some people use Google's [`civil`](https://pkg.go.dev/cloud.google.com/go/civil) package. 22 23 `chrono` provides 3 types for dealing with these use cases: [`LocalDate`](https://pkg.go.dev/github.com/go-chrono/chrono#LocalDate) (a date without a time), [`LocalTime`](https://pkg.go.dev/github.com/go-chrono/chrono#LocalTime) (a time without a date), and [`LocalDateTime`](https://pkg.go.dev/github.com/go-chrono/chrono#LocalDateTime) (a combination of `LocalDate` and `LocalTime`). 24 25 A `LocalDate` and a `LocalTime` are initialized with numeric values. A `LocalDateTime` can either be initialized with numeric values, or by combining a `LocalDate` and `LocalTime` (as below): 26 27 ```golang 28 date := chrono.LocalDateOf(2007, chrono.May, 20) 29 time := chrono.LocalTimeOf(12, 30, 15, 0) 30 fmt.Println(chrono.OfLocalDateAndTime(date, time)) 31 ``` 32 33 ✅ [See more `LocalDate` examples](example_local_date_test.go). 34 <br /> 35 ✅ [See more `LocalTime` examples](example_local_time_test.go). 36 <br /> 37 ✅ [See more `LocalDateTime` examples](example_local_date_time_test.go). 38 39 ## Parse and format dates and times 40 41 `chrono` differs from the `time` package because it uses format codes instead of a mnemonic device. The format codes are borrowed from `strftime`/`strptime`, and therefore maybe familiar from other languages. The full list is documented [here](https://pkg.go.dev/github.com/go-chrono/chrono#pkg-constants), but here's a simple example of formatting a time: 42 43 ```golang 44 time := chrono.LocalTimeOf(12, 30, 15, 0) 45 fmt.Println(time.Format("%H:%M:%S")) 46 ``` 47 48 And parsing a time: 49 50 ```golang 51 var time chrono.LocalTime 52 time.Parse("%H:%M:%S", "12:30:15") 53 ``` 54 55 There are also predefined layouts, similar to the `time` package, but with the addition of layouts compatible with ISO 8601. 56 57 ## Parse and format ISO 8601 durations 58 59 When interfacing with systems where the <code>time</code> package's duration formatting is not understood, ISO 8601 is a commonly-adopted standard. 60 61 `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: 62 63 ```go 64 var d time.Duration 65 fmt.Printf("PT%dS", int(d.Seconds())) 66 ``` 67 68 `chrono` supports both [parsing](https://pkg.go.dev/github.com/go-chrono/chrono#ParseDuration) and [formatting](https://pkg.go.dev/github.com/go-chrono/chrono#FormatDuration) of ISO 8601 strings: 69 70 ```go 71 period, duration, _ := chrono.ParseDuration("P3Y6M4DT1M5S") 72 fmt.Println(chrono.FormatDuration(period, duration)) 73 ``` 74 75 Alternatively, a [`Period`](https://pkg.go.dev/github.com/go-chrono/chrono#Period) and [`Duration`](https://pkg.go.dev/github.com/go-chrono/chrono#Duration) can be initialized with numeric values: 76 77 ```go 78 period := chrono.Period{Years: 3, Months: 6, Days: 4} 79 duration := chrono.DurationOf(1*chrono.Hour + 30*chrono.Minute + 5*chrono.Second) 80 fmt.Println(chrono.FormatDuration(period, duration)) 81 ``` 82 83 ✅ [See more examples](example_duration_period_test.go). 84 85 ## Intervals 86 87 Intervals as a concept are absent from the `time` package. `chrono` introduces the `Interval` 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. 88 89 Parsing and formatting of intervals using the ISO 8601 notation is supported as follows, including the use of repeating intervals: 90 91 ```go 92 interval, _ := chrono.ParseInterval("R5/2007-03-01T13:00:00Z/P1Y2M10DT2H30M") 93 fmt.Println(interval.String()) 94 ``` 95 96 ✅ [See more examples](example_interval_test.go).