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).