Code Monkey home page Code Monkey logo

clj-time's Introduction

clj-time

A date and time library for Clojure, wrapping the Joda Time library.

Usage

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

=> (use 'clj-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 sec 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 want a time with the specified fields in a different time zone, use from-time-zone:

=> (from-time-zone (date-time 1986 10 22) (time-zone-for-offset -2))
#<DateTime 1986-10-22T00:00:00.000-02:00>

If on the other hand you want a given absolute instant in time in a different time zone, use to-time-zone:

=> (to-time-zone (date-time 1986 10 22) (time-zone-for-offset -2))
#<DateTime 1986-10-21T22:00:00.000-02:00>

In addition to time-zone-for-offset, you can use the time-zone-for-id and default-time-zone functions and the utc Var to construct or get DateTimeZone instances.

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-secs 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

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

=> (use 'clj-time.format)

Printing and printing 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)

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

=> (parse custom-formatter "20100311")
#<DateTime 2010-03-11T00:00:00.000Z>

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

To parse dates in multiple formats and format dates in just one format, you can do this:

=> (def multi-parser (formatter (default-time-zone) "YYYY-MM-dd" "YYYY/MM/dd"))

=> (unparse multi-parser (parse multi-parser "2012-02-01"))
"2012-02-01"

=> (unparse multi-parser (parse multi-parser "2012/02/01"))
"2012-02-01"

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

=> (use 'clj-time.coerce)

For example, to convert a Joda DateTime to and from a Java long:

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

=> (from-long 893462400000)
#<DateTime 1998-04-25T00:00:00.000Z>

There are also conversions to and from java.util.Date (to-date and from-date), java.sql.Date (to-sql-date and from-sql-date) and several other types.

The namespace clj-time.local contains functions for working with local time without having to shift to/from utc, the preferred time zone of clj-time.core.

Get the current local time with

=> (local-now)

Get a local date-time instance retaining the time fields with

=> (to-local-date-time obj)

The following all return 1986-10-14 04:03:27.246 with the local time zone.

(to-local-date-time (clj-time.core/date-time 1986 10 14 4 3 27 246))
(to-local-date-time "1986-10-14T04:03:27.246")
(to-local-date-time "1986-10-14T04:03:27.246Z")

The dynamic var *local-formatters* contains a map of local formatters for parsing and printing. It is initialized with all the formatters in clj-time.format localized.

to-local-date-time for strings uses *local-formatters* to parse.

Format an obj using a formatter in *local-formatters* corresponding to the format-key passed in with

=> (format-local-time (local-now) :basic-date-time)

Installation

clj-time is available as a Maven artifact via Clojars.

Current stable build dependency:

[clj-time "0.4.4"]

Development

Running the tests:

$ lein2 test-all

Documentation

The complete API documentation is also available (codox generated).

License

Released under the MIT License: http://www.opensource.org/licenses/mit-license.php

clj-time's People

Contributors

alexbaranosky avatar alexrobbins avatar aria42 avatar aviflax avatar bmabey avatar davidsantiago avatar devn avatar drone29a avatar ejackson avatar gorsuch avatar jasonpatt avatar michaelklishin avatar michalmarczyk avatar mmcgrana avatar mpenet avatar mw10013 avatar r0man avatar raynes avatar seancorfield avatar slr71 avatar swannodette avatar w01fe avatar weavejester avatar

Watchers

 avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.