New upstream version 0.14.0

parents
lib
bin
classes
target
clj-time.jar
pom.xml
*.jar
*~
.lein-*
.nrepl-*
checkouts
.classpath
.project
.settings
*.iml
.idea
/pom.xml.asc
test/readme.clj
doc/*
language: clojure
cache:
directories:
- $HOME/.m2
before_script:
- rm -f test/readme.clj
- echo y | sudo lein upgrade
script: lein test-all
jdk:
- openjdk7
- oraclejdk7
- oraclejdk8
## Changes Between 0.13.0 and 0.14.0
* Add `from-epoch`.
* Clarify `today-at` is UTC.
* Add optional `clj-time.spec` namespace (requires Clojure 1.9 Alpha 17).
* Add `clj-time.types` namespace with type-based predicates.
## Changes Between 0.12.2 and 0.13.0
* Update Joda Time to 2.9.7 (#223).
## Changes Between 0.12.1 and 0.12.2
* More reflection warnings removed (#221).
## Changes Between 0.12.0 and 0.12.1
* Updated Joda Time (to 2.9.4) and several testing dependencies as well.
* `floor` now retains timezone information (#204).
* Reflection warning removed from `with-time-at-start-of-day` (#219).
## Changes Between 0.11.0 and 0.12.0 (June 6th, 2016)
### Joda Time 2.9.3
[Joda Time](http://www.joda.org/joda-time/) has been [upgraded to `2.9.3`](http://www.joda.org/joda-time/upgradeto293.html).
### java.jdbc coercions
`java.sql.Date` and `java.sql.Time` are now coerced automatically if you `require` `clj-time.jdbc` (previously only `java.sql.Timestamp` was coerced).
### Formatters
The `formatter` function now accepts keywords and formatter objects, as well as string formats, so you can easily select a standard format (with a keyword) or provide a specific formatter object.
### Clojure 1.8 by Default
The library now depends on Clojure `1.8.0` and is tested against `1.6.0`, `1.7.0`, and `1.9.0-master-SNAPSHOT`.
### Enhancements
* `first-day-of-the-month?` and `last-day-of-the-month?` -- aliases to improve consistency (so it's `the-month` everywhere).
* `min-date` and `max-date` -- to return the minimum or maximum of two or more dates.
* `nth-day-of-the-month` -- return the Nth day of the year/month, or date/time.
* `nth-day-of-the-month?` -- return true if a given date/time is on the Nth day of its month.
* `with-time-at-start-of-day` -- return the time at the start of the day, including timezone and DST support.
### Deprecations
* `today-at-midnight` -- deprecated in favor of `with-time-at-start-of-day`.
### Bug Fixes
[Issue 185](https://github.com/clj-time/clj-time/issues/185) is fixed by explicitly tying the `:rfc822` formatter to the US locale.
The examples in the README are now automatically tested (by midje-readme) so they are more likely to be valid.
## Changes Between 0.10.0 and 0.11.0
### Joda Time 2.8
[Joda Time](http://www.joda.org/joda-time/) has been [upgraded to `2.8.2`](http://www.joda.org/joda-time/upgradeto282.html).
### Clojure 1.7 by Default
The library now depends on Clojure `1.7.0`.
## Changes Between 0.9.0 and 0.10.0
### clj-time.instant
`clj-time.instant` is a new namespace that, when loaded, makes it possible
for the Clojure reader to serialize Joda Time data types.
### Joda Time 2.7
[Joda Time](http://www.joda.org/joda-time/) has been [upgraded to `2.7`](http://www.joda.org/joda-time/upgradeto270.html).
### `equal?`
A new predicate `equal?` has been added, which can be used like `before?` and
`after?` to assert two instants represent identical points in time regardless of
differences in time zone.
Contributed by [@gws](https://github.com/gws).
### `clj-time.jdbc`
A new namespace `clj-time.jdbc` has been added which extends protocols in
clojure.java.jdbc to allow for easy coercion to and from java.sql.Timestamp
driven by `clj-time.coerce`.
Contributed by [@gws](https://github.com/gws).
## Changes Between 0.8.0 and 0.9.0
### with-default-year
`clj-time.format/with-default-year` is a new function that accepts a formatter
and returns a formatter that uses provided year by default.
Contributed by lummax.
### InTimeUnitProtocol
`clj-time.core/InTimeUnitProtocol` is a new protocol that provides convenient
functions for time unit conversion:
``` clojure
(defprotocol InTimeUnitProtocol
"Interface for in-<time unit> functions"
(in-millis [this] "Return the time in milliseconds.")
(in-seconds [this] "Return the time in seconds.")
(in-minutes [this] "Return the time in minutes.")
(in-hours [this] "Return the time in hours.")
(in-days [this] "Return the time in days.")
(in-weeks [this] "Return the time in weeks")
(in-months [this] "Return the time in months")
(in-years [this] "Return the time in years"))
```
### Clojure 1.2-1.4 Support Dropped
`clj-time` now officially supports Clojure `1.5.1` and later versions.
### Joda Time 2.6
[Joda Time](http://www.joda.org/joda-time/) has been [upgraded to `2.6`](http://www.joda.org/joda-time/upgradeto260.html).
Copyright 2013 Mark McGranaghan, Sean Corfield and other contributors
https://github.com/clj-time/clj-time
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
# `clj-time` <a href="http://travis-ci.org/#!/clj-time/clj-time/builds"><img src="https://secure.travis-ci.org/clj-time/clj-time.png" /></a> [![Dependency Status](https://www.versioneye.com/clojure/clj-time:clj-time/badge.png)](https://www.versioneye.com/clojure/clj-time:clj-time) [![Join the chat at https://gitter.im/clj-time/clj-time](https://badges.gitter.im/clj-time/clj-time.svg)](https://gitter.im/clj-time/clj-time?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
A date and time library for Clojure, wrapping the [Joda Time](http://www.joda.org/joda-time/) library.
## Artifacts
`clj-time` artifacts are [released to Clojars](https://clojars.org/clj-time/clj-time).
If you are using Maven, add the following repository definition to your `pom.xml`:
``` xml
<repository>
<id>clojars.org</id>
<url>http://clojars.org/repo</url>
</repository>
```
### The Most Recent Release
With Leiningen:
``` clj
[clj-time "0.14.0"]
```
With Maven:
``` xml
<dependency>
<groupId>clj-time</groupId>
<artifactId>clj-time</artifactId>
<version>0.14.0</version>
</dependency>
```
## Bugs and Enhancements
Please open issues against the [official clj-time repo on Github](https://github.com/clj-time/clj-time/issues).
## Mailing List
Please ask questions on the [clj-time mailing list](http://groups.google.com/forum/#!forum/clj-time).
## Usage
### clj-time.core
The main namespace for date-time operations in the `clj-time` library is `clj-time.core`.
``` clj
(require '[clj-time.core :as t])
```
Create a DateTime instance with date-time, specifying the year, month,
day, hour, minute, second, and millisecond:
``` clj
(t/date-time 1986 10 14 4 3 27 456)
=> #<DateTime 1986-10-14T04:03:27.456Z>
```
Less-significant fields can be omitted:
``` clj
(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:
```clojure
(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`:
``` clj
(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`:
``` clj
(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).
``` clj
(t/local-date 2013 3 20)
=> #<LocalDate 2013-03-20>
```
The functions `equal?`, `after?`, and `before?` determine the relative position
of two DateTime instances:
```clojure
(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:
``` clj
(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?`
```clojure
(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:
```clojure
(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:
``` clj
(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:
``` clj
(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`:
``` clj
(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.:
```clojure
(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:
``` clj
(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](http://www.joda.org/joda-time/key_format.html)
on the Joda Time website.
Once you have a formatter, parsing and printing are straightforward:
``` clj
(f/parse custom-formatter "20100311")
=> #<DateTime 2010-03-11T00:00:00.000Z>
```
```clojure
(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:
```clojure
(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"
```
### clj-time.coerce
The namespace `clj-time.coerce` contains utility functions for
coercing Joda `DateTime` instances to and from various other types:
``` clj
(require '[clj-time.coerce :as c])
```
For example, to convert a Joda `DateTime` to and from a Java `long`:
```clojure
(c/to-long (t/date-time 1998 4 25))
=> 893462400000
```
``` clj
(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:
```clojure
(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.
``` clj
(require '[clj-time.local :as l])
```
Get the current local time with
``` clj
(l/local-now)
```
Get a local date-time instance retaining the time fields with
``` clj
(l/to-local-date-time obj)
```
The following all return 1986-10-14 04:03:27.246 with the local time
zone.
``` clj
(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
``` clj
(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:
``` clj
(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:
``` clj
(require '[clj-time.core :as t])
(require '[clj-time.predicates :as pr])
```
``` clojure
(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:
``` clj
(require 'clj-time.jdbc)
```
In your project:
``` clj
(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](http://clj-time.github.com/clj-time/doc/index.html) is also available (codox generated).
## License
Released under the MIT License: <https://github.com/clj-time/clj-time/blob/master/MIT-LICENSE.txt>
(defproject clj-time/clj-time "0.14.0"
:description "A date and time library for Clojure, wrapping Joda Time."
:url "https://github.com/clj-time/clj-time"
:mailing-list {:name "clj-time mailing list"
:archive "https://groups.google.com/forum/?fromgroups#!forum/clj-time"
:post "clj-time@googlegroups.com"}
:license {:name "MIT License"
:url "http://www.opensource.org/licenses/mit-license.php"
:distribution :repo}
:dependencies [[joda-time "2.9.7"]
[org.clojure/clojure "1.8.0" :scope "provided"]]
:min-lein-version "2.0.0"
:global-vars {*warn-on-reflection* true}
:profiles {:dev {:dependencies [[org.clojure/java.jdbc "0.6.1"]]
:plugins [[codox "0.8.10"]]}
:midje {:dependencies [[midje "1.9.0-alpha5"]]
:plugins [[lein-midje "3.2.1"]
[midje-readme "1.0.9"]]
:midje-readme {:require "[clj-time.core :as t] [clj-time.predicates :as pr] [clj-time.format :as f] [clj-time.coerce :as c]"}}
:1.6 {:dependencies [[org.clojure/clojure "1.6.0"]]}
:1.7 {:dependencies [[org.clojure/clojure "1.7.0"]]}
:master {:repositories [["snapshots" "https://oss.sonatype.org/content/repositories/snapshots/"]]
:dependencies [[org.clojure/clojure "1.9.0-master-SNAPSHOT"]]}
:spec {:dependencies [[org.clojure/clojure "1.9.0-alpha17"]
[org.clojure/test.check "0.9.0"]]
:test-paths ["test" "test_clj_1.9"]}}
:aliases {"test-all" ["with-profile" "dev,master,default,midje:dev,default,midje:dev,1.6,midje:dev,1.7,midje" "test"]})
(ns clj-time.coerce
"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>"
(:refer-clojure :exclude [extend second])
(:require [clj-time.core :refer :all]
[clj-time.format :as time-fmt])
(:import [java.sql Timestamp]
[java.util Date]
[org.joda.time DateTime DateTimeZone DateMidnight YearMonth
LocalDate LocalDateTime]))
(defprotocol ICoerce
(^org.joda.time.DateTime
to-date-time [obj] "Convert `obj` to a Joda DateTime instance."))
(defn from-long
"Returns a DateTime instance in the UTC time zone corresponding to the given
number of milliseconds after the Unix epoch."
[^Long millis]
(DateTime. millis ^DateTimeZone utc))
(defn from-epoch
"Returns a DateTime instance in the UTC time zone
from given Unix epoch."
[^Long epoch]
(from-long (* epoch 1000)))
(defn from-string
"return DateTime instance from string using
formatters in clj-time.format, returning first
which parses"
[^String s]
(time-fmt/parse s))
(defn from-date
"Returns a DateTime instance in the UTC time zone corresponding to the given
Java Date object."
[^Date date]
(when date
(from-long (.getTime date))))
(defn from-sql-date
"Returns a DateTime instance in the UTC time zone corresponding to the given
java.sql.Date object."
[^java.sql.Date sql-date]
(when sql-date
(from-long (.getTime sql-date))))
(defn from-sql-time
"Returns a DateTime instance in the UTC time zone corresponding to the given
java.sql.Timestamp object."
[^java.sql.Timestamp sql-time]
(when sql-time
(from-long (.getTime sql-time))))
(defn to-long
"Convert `obj` to the number of milliseconds after the Unix epoch."
[obj]
(if-let [dt (to-date-time obj)]
(.getMillis dt)))
(defn to-epoch
"Convert `obj` to Unix epoch."
[obj]
(let [millis (to-long obj)]
(and millis (quot millis 1000))))
(defn to-date
"Convert `obj` to a Java Date instance."
[obj]
(if-let [dt (to-date-time obj)]
(Date. (.getMillis dt))))
(defn to-sql-date
"Convert `obj` to a java.sql.Date instance."
[obj]
(if-let [dt (to-date-time obj)]
(java.sql.Date. (.getMillis dt))))
(defn to-sql-time
"Convert `obj` to a java.sql.Timestamp instance."
[obj]
(if-let [dt (to-date-time obj)]
(java.sql.Timestamp. (.getMillis dt))))
(defn to-string
"Returns a string representation of obj in UTC time-zone
using (ISODateTimeFormat/dateTime) date-time representation."
[obj]
(if-let [^DateTime dt (to-date-time obj)]
(time-fmt/unparse (:date-time time-fmt/formatters) dt)))
(defn to-timestamp
"Convert `obj` to a Java SQL Timestamp instance."
[obj]
(if-let [dt (to-date-time obj)]
(Timestamp. (.getMillis dt))))
(defn to-local-date
"Convert `obj` to a org.joda.time.LocalDate instance"
[obj]
(if-let [dt (to-date-time obj)]
(LocalDate. (.getMillis (from-time-zone dt (default-time-zone))))))
(defn to-local-date-time
"Convert `obj` to a org.joda.time.LocalDateTime instance"
[obj]
(if-let [dt (to-date-time obj)]
(LocalDateTime. (.getMillis (from-time-zone dt (default-time-zone))))))
(defn in-time-zone
"Convert `obj` into `tz`, return org.joda.time.LocalDate instance."
[obj tz]
(if-let [dt (to-date-time obj)]
(-> dt
(to-time-zone tz)
.toLocalDate)))
(extend-protocol ICoerce
nil
(to-date-time [_]
nil)
Date
(to-date-time [date]
(from-date date))
java.sql.Date
(to-date-time [sql-date]
(from-sql-date sql-date))
java.sql.Timestamp
(to-date-time [sql-time]
(from-sql-time sql-time))