CrossClj

0.14.4 docs

SourceDocs



RECENT

    clj-time

    Clojars

    May 16, 2018


    OWNER
    clj-time

    Readme

    Index of all namespaces


    « Project + dependencies

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

    clj-time.coerceDocsSource
    Utilites to coerce Joda DateTime instances to and from various other types.
    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>
    clj-time.coreDocsSource
    The core namespace for date-time operations in the clj-time library.
    
    Create a DateTime instance with date-time (or a LocalDateTime instance with local-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>
    
      => (local-date-time 1986 10 14 4 3 27 456)
      #<LocalDateTime 1986-10-14T04:03:27.456>
    
    Less-significant fields can be omitted:
    
      => (date-time 1986 10 14)
      #<DateTime 1986-10-14T00:00:00.000Z>
    
      => (local-date-time 1986 10 14)
      #<LocalDateTime 1986-10-14T00:00:00.000>
    
    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
    
      => (hour (local-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 constgruct 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
    
      => (after? (local-date-time 1986 10) (local-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>
    
      => (plus (local-date-time 1986 10 14) (months 1) (weeks 3))
      #<LocalDateTime 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
    
    To find the amount of time encompased by an interval, use in-seconds and
    in-minutes:
    
      => (in-minutes (interval (date-time 1986 10 2) (date-time 1986 10 14)))
      17280
    
    Note that all functions in this namespace work with Joda objects or ints. If
    you need to print or parse date-times, see clj-time.format. If you need to
    ceorce date-times to or from other types, see clj-time.coerce.
    clj-time.formatDocsSource
    Utilities for parsing and unparsing DateTimes as Strings.
    
    Parsing and printing are controlled by formatters. You can either use one
    of the built in ISO 8601 and a single RFC 822 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"
    
    By default the parse function always returns a DateTime instance with a UTC
    time zone, and the unparse function always represents a given DateTime
    instance in UTC. A formatter can be modified to different timezones, locales,
    etc with the functions with-zone, with-locale, with-chronology,
    with-default-year and with-pivot-year.
    clj-time.instantDocsSource
    An optional convenience namespaces that allows key JodaTime types
    to be transparently serialized with the Clojure reader (via instant literals).
    clj-time.jdbcDocsSource
    clojure.java.jdbc protocol extensions supporting DateTime coercion.
    
    To use in your project, just require the namespace:
    
      => (require 'clj-time.jdbc)
      nil
    
    Doing so will extend the protocols defined by clojure.java.jdbc, which will
    cause java.sql.Timestamp objects in JDBC result sets to be coerced to
    org.joda.time.DateTime objects, and vice versa where java.sql.Timestamp
    objects would be required by JDBC.
    clj-time.localDocsSource
    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).
    
     (to-local-date-time obj) returns a local date-time instance
     retaining the time fields.
    
    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-local-time (local-now) :basic-date-time) formats an obj using
    a formatter in *local-formatters* corresponding to the  format-key
    passed in.
    clj-time.predicatesDocsSource
    Predicate functions to ask basic questions about a date
    
    Was it Monday?
    (monday? (clj-time.core/date-time 1999 9 9))
    
    Is it January?
    (january? (clj-time.core/date-time 2011 1 1))
    clj-time.specDocsSource
    This namespace requires Clojure 1.9 or later. It defines a set of predicates plus a set of spec defs with associated generators.
    
    clj-time.typesDocsSource
    This namespace defines a set of predicates for the various Joda Time types used by clj-time.
    
    The README below is fetched from the published project artifact. Some relative links may be broken.

    clj-time Dependency Status Join the chat at https://gitter.im/clj-time/clj-time

    A date and time library for Clojure, wrapping the Joda Time library. The Joda Time website says:

    Note that from Java SE 8 onwards, users are asked to migrate to java.time (JSR-310) - a core part of the JDK which replaces this project.

    If you are using Java 8 or later, consider using the built-in Java Time instead of Joda Time – and look at clojure.java-time if you want a Clojure wrapper for that. See Converting from Joda Time to java.time for more details about the similarities and differences between the two libraries.

    Artifacts

    clj-time artifacts are released to Clojars.

    If you are using Maven, add the following repository definition to your pom.xml:

    <repository>
      <id>clojars.org</id>
      <url>http://clojars.org/repo</url>
    </repository>
    

    The Most Recent Release

    With Leiningen:

    [clj-time "0.14.4"]
    

    With Maven:

    <dependency>
      <groupId>clj-time</groupId>
      <artifactId>clj-time</artifactId>
      <version>0.14.4</version>
    </dependency>
    

    Bugs and Enhancements

    Please open issues against the official clj-time repo on Github. clj-time is a very thin wrapper around Joda Time. That means that if Joda Time has a “peculiar behavior”, it’s likely to be surfaced directly in clj-time as well. A good example of this is clj-time.format/unparse which simply calls Joda Time’s .print method – and if the date passed in happens to be nil, you silently get back the current date/time (many people would expect an exception!).

    Mailing List

    Please ask questions on the clj-time mailing list.

    Usage

    clj-time.core

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

    (require '[clj-time.core :as t])
    

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

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

    Less-significant fields can be omitted:

    (t/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:

    (t/hour (t/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:

    (t/from-time-zone (t/date-time 1986 10 22) (t/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:

    (t/to-time-zone (t/date-time 1986 10 22) (t/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.

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

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

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

    (t/equal? (t/date-time 1986 10) (t/date-time 1986 10))
    => true
    (t/after? (t/date-time 1986 10) (t/date-time 1986 9))
    => true
    (t/before? (t/date-time 1986 9) (t/date-time 1986 10))
    => 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:

    (t/plus (t/date-time 1986 10 14) (t/months 1) (t/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?

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

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

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

    The overlap function can be used to get an Interval representing the overlap between two intervals:

    (t/overlap (t/interval (t/date-time 1986) (t/date-time 1990))
             (t/interval (t/date-time 1987) (t/date-time 1991)))
    => #<Interval 1987-01-01T00:00:00.000Z/1990-01-01T00:00:00.000Z>
    

    today-at returns a moment in time at the given hour, minute and second on the current date UTC; not the current system date:

    (t/today-at 12 00)
    => #<DateTime 2013-03-29T12:00:00.000Z>
    (t/today-at 12 00 05)
    => #<DateTime 2013-03-29T12:00:05.000Z>
    
    ;; System clock says 11PM on 12/20/2016 UTC-5
    (t/today-at 7 00 00)
    => #<DateTime 2016-12-21T7:00:00.000Z>
    

    clj-time.format

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

    (require '[clj-time.format :as f])
    

    Parsing 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 (f/formatters :basic-date-time))
    (def custom-formatter (f/formatter "yyyyMMdd"))
    

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

    (f/show-formatters)
    

    Remember that mm is minutes, MM is months, ss is seconds and SS is milliseconds. You can find a complete list of patterns on the Joda Time website.

    Once you have a formatter, parsing and printing are straightforward:

    (f/parse custom-formatter "20100311")
    => #<DateTime 2010-03-11T00:00:00.000Z>
    
    (f/unparse custom-formatter (t/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 (f/formatter (t/default-time-zone) "YYYY-MM-dd" "YYYY/MM/dd"))
    
    (f/unparse multi-parser (f/parse multi-parser "2012-02-01"))
    => "2012-02-01"
    
    (f/unparse multi-parser (f/parse multi-parser "2012/02/01"))
    => "2012-02-01"
    

    Note: Joda Time’s .print method accepts a null date/time object and substitutes the current date/time, so (f/unparse my-fmt nil) will not throw an exception – it will just silently return the current date/time!

    clj-time.coerce

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

    (require '[clj-time.coerce :as c])
    

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

    (c/to-long (t/date-time 1998 4 25))
    => 893462400000
    
    (c/from-long 893462400000)
    => #<DateTime 1998-04-25T00:00:00.000Z>
    

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

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

    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), java.sql.Timestamp (to-sql-time and from-sql-time) and several other types.

    clj-time.local

    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.

    (require '[clj-time.local :as l])
    

    Get the current local time with

    (l/local-now)
    

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

    (l/to-local-date-time obj)
    

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

    (l/to-local-date-time (clj-time.core/date-time 1986 10 14 4 3 27 246))
    (l/to-local-date-time "1986-10-14T04:03:27.246")
    (l/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

    (l/format-local-time (l/local-now) :basic-date-time)
    

    clj-time.periodic

    clj-time.periodic/periodic-seq returns an infinite sequence of instants separated by a time period starting with the given point in time:

    (require '[clj-time.periodic :as p])
    (require '[clj-time.core :as t])
    
    ;; returns 10 instants starting with current time separated
    ;; by 12 hours
    (take 10 (p/periodic-seq (t/now) (t/hours 12)))
    

    In particular, if you ask for a sequence of instants separated by a month, you will get dates where the month increases each time (rather than being, say, 30 days apart).

    clj-time.predicates

    clj-time.predicates comes with a set of handy predicates to check for common conditions. For instance:

    (require '[clj-time.core :as t])
    (require '[clj-time.predicates :as pr])
    
    (pr/monday? (t/date-time 1999 9 9))
    => false
    
    (pr/january? (t/date-time 2011 1 1))
    => true
    
    (pr/weekend? (t/date-time 2014 1 26))
    => true
    
    (pr/weekday? (t/date-time 2014 1 26))
    => false
    
    (pr/last-day-of-month? (t/date-time 2014 1 26))
    => false
    
    (pr/first-day-of-month? (t/date-time 2014 1 26))
    => false
    

    clj-time.jdbc

    clj-time.jdbc registers protocol extensions so you don’t have to use clj-time.coerce yourself to coerce to and from SQL timestamps.

    From the REPL:

    (require 'clj-time.jdbc)
    

    In your project:

    (ns my.neat.project
      (:require [clj-time.jdbc]))
    
    ; They're registered and ready to use.
    

    Now you can use org.joda.time.DateTime objects when “writing” to the database in place of java.sql.Timestamp objects, and expect org.joda.time.DateTime objects when “reading” where you would have previously expected java.sql.Timestamp objects.

    Development

    Running the tests:

    $ rm -f test/readme.clj && lein test-all && lein test-readme
    

    (assumes Leiningen 2.x)

    Documentation

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

    License

    Released under the MIT License: https://github.com/clj-time/clj-time/blob/master/MIT-LICENSE.txt