cljs-time Documentation

Technical Documentation: logseq/cljs-time

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

cljs-time [](https://travis-ci.org/andrewmcveigh/cljs-time)

A date and time library for ClojureScript, imitating the API of the
clj-time library.

Cljs-time is an attempt at replicating the functionality and API of
clj-time. This is not a drop-in clojurescript replacement for
clj-time, however the goal is that over time enough functionality of
the clj-time API can be replicated to make this library "good enough"
for other projects.

This library is currently leaning on the
Google Closure goog.date
library for basic date/time functionality. The date objects in this
library are mutable, however any operations that alter a date
object return a copy, leaving the referenced date object alone. In the
future, immutable date objects will be preferred.

Artifacts Copy Chapter

Update your deps.edn to use:

{:deps
 {logseq/cljs-time
  {:git/url "https://github.com/logseq/cljs-time" :sha "xxxx"}}}

Bugs and Enhancements Copy Chapter

Please open issues against the
cljs-time repo on Github.

Note: version 0.5. follows the API of clj-time 0.11.0.*

API Copy Chapter

Most of the clj-time API has been implemented. Some of the parts that
don't make sense in clojurescript, such as Java interop, and
java.sql.* have been left out. Timezone functionality in javascript is
minimal, and therefore so is cljs-time's.

The majority of the tests from clj-time have been ported, and are
passing.

API documentation is
available.

Usage Copy Chapter

Note: Equality in goog.date.* (and also with plain javascript
dates) is not the same as in Joda/clj-time. Two date objects
representing the same instant in time in goog.date.* are not equal.

If you need to test for equality use either cljs-time.core/=, or
optionally you can require the cljs-time.extend namespace which will
extend the goog.date.* datatypes, so that clojure.core/= works as
expected.

If you want your goog.date.* serializable with pr-str, require
cljs-time.instant namespace.

cljs-time.core Copy Section

The main namespace for date-time operations in the cljs-time library
is cljs-time.core.

=> (use 'cljs-time.core)

Create a DateTime instance with date-time, specifying the year, month,
day, hour, minute, second, and millisecond:

=> (date-time 1986 10 14 4 3 27 456)
#<DateTime 1986-10-14T04:03:27.456Z>

Less-significant fields can be omitted:

=> (date-time 1986 10 14)
#<DateTime 1986-10-14T00:00:00.000Z>

Get the current time with (now) and the start of the Unix epoch with (epoch).

Once you have a date-time, use accessors like hour and second to access the corresponding fields:

=> (hour (date-time 1986 10 14 22))
22

The date-time constructor always returns times in the UTC time zone.

If you only want a date with no time component, consider using the local-date and today functions.
These return LocalDate instances that do not have time components (and thus don't suffer from timezone-related shifting).

=> (local-date 2013 3 20)
#<LocalDate 2013-03-20>

The functions after? and before? determine the relative position of two
DateTime instances:

=> (after? (date-time 1986 10) (date-time 1986 9))
true

Often you will want to find a date some amount of time from a given date. For
example, to find the time 1 month and 3 weeks from a given date-time:

=> (plus (date-time 1986 10 14) (months 1) (weeks 3))
#<DateTime 1986-12-05T00:00:00.000Z>

An Interval is used to represent the span of time between two DateTime
instances. Construct one using interval, then query them using within?,
overlaps?, and abuts?

=> (within? (interval (date-time 1986) (date-time 1990))
            (date-time 1987))
true

The in-seconds and in-minutes functions can be used to describe intervals in the corresponding temporal units:

=> (in-minutes (interval (date-time 1986 10 2) (date-time 1986 10 14)))
17280

cljs-time.format Copy Section

If you need to parse or print date-times, use cljs-time.format:

=> (use 'cljs-time.format)

Printing and parsing are controlled by formatters. You can either use one of the built in ISO8601 formatters or define your own, e.g.:

(def built-in-formatter (formatters :basic-date-time))
(def custom-formatter (formatter "yyyyMMdd"))

To see a list of available built-in formatters and an example of a date-time printed in their format:

=> (show-formatters)

Remember that mm is minutes, MM is months, ss is seconds and SSS is milliseconds.

Once you have a formatter, parsing and printing are straight-forward:

=> (parse custom-formatter "20100311")
#<20100311T000000>

=> (unparse custom-formatter (date-time 2010 10 3))
"20101003"

cljs-time.core/today-at returns a moment in time at the given hour, minute and second
on the current date:

=> (today-at 12 00)
#<20130329T120000>
=> (today-at 12 00 05)
#<20130329T120005>

cljs-time.coerce Copy Section

The namespace cljs-time.coerce contains utility functions for coercing Google Closure DateTime instances to and from various other types:

=> (use 'cljs-time.coerce)

For example, to convert a goog.date DateTime to and from a js Number:

=> (to-long (date-time 1998 4 25))
893462400000

=> (from-long 893462400000)
#<19980425T000000>

And by the magic of protocols you can pass in an isoformat string and get the unix epoch milliseconds:

=> (to-long "2013-08-01")
1375315200000

Development Copy Chapter

Running the tests:

$ shadow-cljs compile test

Getting a REPL Copy Section

$ shadow-cljs watch app

Documentation Copy Chapter

The complete API documentation
is also available.

License Copy Chapter

Copyright © 2013-2016 Andrew Mcveigh

Distributed under the Eclipse Public License, the same as Clojure.

--- METRICS ---

• Files Extracted: 1
• Estimated Token Budget: ~1541 tokens
• Canonical Reference: https://codewiki.google/github.com/logseq/cljs-time