https://github.com/metabase/second-date
Helpful java.time utility functions for Clojure
https://github.com/metabase/second-date
clj-time clojure datetime java-time temporal
Last synced: about 2 months ago
JSON representation
Helpful java.time utility functions for Clojure
- Host: GitHub
- URL: https://github.com/metabase/second-date
- Owner: metabase
- License: epl-1.0
- Created: 2020-04-15T08:31:19.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-03-20T07:40:06.000Z (about 1 year ago)
- Last Synced: 2024-05-01T21:38:48.953Z (about 1 year ago)
- Topics: clj-time, clojure, datetime, java-time, temporal
- Language: Clojure
- Homepage:
- Size: 63.5 KB
- Stars: 2
- Watchers: 12
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
[](https://raw.githubusercontent.com/metabase/second-date/master/LICENSE)
[](https://github.com/metabase/second-date/commits/)
[](https://cljdoc.org/d/metabase/second-date/CURRENT)
[](https://clojars.org/metabase/second-date)
(Thanks Bing Image Creator for this totally accurate portrayal of a Clojure library for working with datetimes that is also a second date)
# Second Date
Second Date provides a handful of utility functions for working with `java.time`. The most important are:
###### `parse`
Can parse almost any temporal literal String to the correct `java.time` class.
```clj
(require '[second-date.core :as second-date])
(second-date/parse "2020-04")
;; -> #object[java.time.LocalDate 0x1998e54f "2020-04-01"]
(second-date/parse "2020-04-01")
;; -> #object[java.time.LocalDate 0x1998e54f "2020-04-01"]
(second-date/parse "2020-04-01T15:01")
;; -> #object[java.time.LocalDateTime 0x121829b7 "2020-04-01T15:01"]
(second-date/parse "2020-04-01T15:01-07:00")
;; -> #object[java.time.OffsetDateTime 0x7dc126b0 "2020-04-01T15:01-07:00"]
(second-date/parse "2020-04-01T15:01-07:00[US/Pacific]")
;; -> #object[java.time.ZonedDateTime 0x351fb7c8 "2020-04-01T15:01-07:00[US/Pacific]"]
```
`parse` handles ISO-8601 strings as well as SQL literals (e.g. `2020-04-01 15:01:00`).
You can also use the built-in literal reader `second-date/t`:
```clj
#second-date/t "2020-04-01T15:01"
;; -> #object[java.time.LocalDateTime 0x121829b7 "2020-04-01T15:01"]
```
For more convenience, you may want to give this a shorter data reader tag, for example `#t`, in your own project.
Optionally, you can also have Second Date print Temporals in a REPL-friendly format by installing print methods with
`second-date/install-print-methods!`:
```clj
#second-date/t "2020-04-01T15:01"
;; -> #object[java.time.LocalDateTime 0x121829b7 "2020-04-01T15:01"]
(second-date/install-print-methods!)
#second-date/t "2020-04-01T15:01"
;; -> #second-date/t "2020-04-01T15:01"
;; use a different data reader tag
(second-date/install-print-methods! 't)
#t "2020-04-01T15:01"
;; -> #t "2020-04-01T15:01"
```
###### `format`
Formats any of the main `java.time` temporal instant classes as a String. Uses ISO-8601 by default, but can use any
`java.time.format.DateTimeFormatter` or keywords naming static formatters as understood by
[`clojure.java-time`](https://github.com/dm3/clojure.java-time).
```clj
(require '[java-time :as t]
'[second-date.core :as second-date])
(second-date/format (t/zoned-date-time "2020-04-01T15:01-07:00[US/Pacific]"))
;; -> "2020-04-01T16:01:00-07:00"
(second-date/format (t/offset-date-time "2020-04-01T15:01-07:00"))
;; -> "2020-04-01T16:01:00-07:00"
(second-date/format (t/local-date-time "2020-04-01T15:01"))
;; -> "2020-04-01T15:01:00"
;; with a different formatter
(second-date/format :basic-iso-date (t/local-date-time "2020-04-01T15:01"))
;; -> "20200401"
;; it even handles Instants
(second-date/format :iso-week-date (t/instant "2020-04-01T15:01:00-07:00"))
;; "2020-W14-3Z"
```
Check the value of `java-time.format/predefined-formatters` for all supported predefined formatters.
###### `second-date.parse.builder/formatter`
`second-date.parse.builder/formatter` is a Clojure interface for `java.time.format.DateTimeFormatterBuilder`, used to
create `DateTimeFormatter`s.
```clj
(require '[java-time :as t]
'[second-date :as second-date]
'[second-date.parse.builder :as b])
(def my-time-formatter
(b/formatter
(b/case-insensitive
(b/value :hour-of-day 2)
(b/optional
":"
(b/value :minute-of-hour 2)
(b/optional
":"
(b/value :second-of-minute))))))
;; -> #object[java.time.format.DateTimeFormatter "ParseCaseSensitive(false)Value(HourOfDay,2)[':'Value(MinuteOfHour,2)[':'Value(SecondOfMinute)]]"]
;; you can now use the formatter to format and parse
(second-date/format my-time-formatter (t/zoned-date-time "2020-04-01T15:23:52.878132-07:00[America/Los_Angeles]"))
;; -> "15:23:52"
(second-date/parse my-time-formatter "15:23:52")
;; -> #object[java.time.LocalTime 0x514c293c "15:23:52"]
```
Some example formatters can be found in `second-date.parse`.