Clojure.joda-time 0.7.0 API documentation

Returns the absolute value of a period or a duration.

(abs (negate x)) == (abs x)

True if this interval abut with the other one.

Returns non-nil if time entities are ordered from the latest to the earliest
(same as `>`):

  (after? (date-time "2011") (date-time "2010") (date-time "2009"))
  => true

  (after? (interval (date-time "2009") (date-time "2010"))
          (date-time "2008"))
  => truthy...

Works with instants, date-times, partials and intervals.

Converts a period or a partial into a map representation.

A period is converted into a map where keys correspond to names of
`DurationFieldTypes`. Only durations supported by the provided period are
included in the result.

A partial is converted into a map where keys correspond to
`DateTimeFieldTypes`.

An instant/date-time is converted into a map where keys correspond to
`DateTimeFieldTypes`. Every date-time field type will be present in the
result.

Returns non-nil if time entities are ordered from the earliest to the latest
(same as `<`):

  (before? (date-time "2009") (date-time "2010") (date-time "2011"))
  => truthy...

  (before? (interval (date-time "2009") (date-time "2010"))
           (date-time "2011"))
  => truthy...

Works with instants, date-times, partials and intervals.

Produces a chronology of the specified type (lowercase) and the given time
zone (optional):

  (chronology :coptic)
  => #<CopticChronology CopticChronology [Europe/Vilnius]>

  (chronology :coptic :UTC)
  => #<CopticChronology CopticChronology [UTC]>

Time zones are resolved through the `timezone` function.

True if the interval contains the given
instant/partial/interval.

Constructs a DateTime out of:

* another instant, a number of milliseconds or a partial date
* a java (util/sql) Date/Timestamp or a Calendar
* an ISO formatted string
* a map with keys corresponding to the names of date-time field types
and an (optional) chronology.
* a map with keys `partial` representing any partial date and `base`
representing a date-time to be used for fields missing in the partial
(defaults to epoch).
* different arities accepting a number of fields in order of Year, Month,
Day, Hour, Minute, Second, Millis. The fields not specified will be defaulted
to the minimum field value.

When called with no arguments produces a value of `DateTime/now`.

Constructs a Days period representing the given number of days. Given a time entity tries to extract the number of days. Given another period, extracts its days part.

Number of days in the given period/interval/pair of
instants, date-times or partials.

Constructs a Duration out of a number, interval, string, other duration or a
map containing:

  - start and end instants
  - start instant and a period
  - end instant and a period

  (duration 1000)
  => #<Duration PT1S>

  (duration (interval 0 1000))
  => #<Duration PT1S>

  (duration "PT1S")
  => #<Duration PT1S>

  (duration (duration 1000))
  => #<Duration PT1S>

  (duration {:start 0, :end 1000})
  => #<Duration PT1S>

  (duration {:start 0, :period (seconds 1)})
  => #<Duration PT1S>

  (duration {:end 0, :period (seconds 1)})
  => #<Duration PT1S>

True if the given object is an instance of `ReadableDuration`.

Gets the end of the interval.

Constructs a DateTimeFormatter out of a number of

* format strings - "YYYY/mm/DD", "YYY HH:MM", etc.
* ISODateTimeFormat formatter names - :date, :time-no-millis, etc.
* other DateTimeFormatter instances

The resulting formatter will parse all of the requested formats and print
using the first one.

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a friday.

Gets the gap between this interval and the other one.

Constructs a Hours period representing the given number of hours. Given a time entity tries to extract the number of hours. Given another period, extracts its hours part.

Number of hours in the given period/interval/pair of
instants, date-times or partials. Also handles durations.

Constructs an Instant out of another instant, java date, calendar, number of
millis or a formatted string:

  (instant)
  => #<Instant ...now...>

  (instant (java.util.Date.))
  => #<Instant ...now...>

  (instant 1000)
  => #<Instant 1970-01-01T00:00:01.000Z>

  (j/instant "1970-01-01T00:00:01.000Z")
  => #<Instant 1970-01-01T00:00:01.000Z>

True if the given object is an instance of `ReadableInstant`.

Constructs an interval out of another interval, a string,
start and end instants/date-times or a map with the
following keys (where start/end may be instants, date-times
or number of milliseconds):

* start/end
* start/period
* period/end
* start/duration
* duration/end

  (j/interval "2010/2013")
  => #<Interval 2010-01-01T00:00:00.000+02:00/2013-01-01T00:00:00.000+02:00>

  (j/interval (j/date-time "2010") (j/date-time "2013"))
  => #<Interval 2010-01-01T00:00:00.000+02:00/2013-01-01T00:00:00.000+02:00>

  (j/interval {:start (j/date-time "2010"), :end (j/date-time "2013")})
  => #<Interval 2010-01-01T00:00:00.000+02:00/2013-01-01T00:00:00.000+02:00>

  (j/interval {:start (j/date-time "2010"), :period (j/years 3)})
  => #<Interval 2010-01-01T00:00:00.000+02:00/2013-01-01T00:00:00.000+02:00>

True if the given object is an instance of `ReadableInterval`.

Returns a lazy sequence of `initial` , `(apply f initial v vs)`, etc.

Useful when you want to produce a sequence of dates/periods/intervals, for
example:

  (iterate plus (millis 0) 1)
  => (#<Period PT0S> #<Period PT0.001S> #<Period PT0.002S> ...)

  (iterate plus (local-date "2010-01-01") (years 1))
  => (#<LocalDate 2010-01-01> #<LocalDate 2011-01-01> ...)

  (iterate move-end-by (interval 0 1000) (seconds 1))
  => (#<Interval 00.000/01.000> #<Interval 00.000/02.000> ...)

Constructs a LocalDate out of 

* another partial (which must have all of the needed fields)
* an instant or a number of milliseconds
* a java (util/sql) Date/Timestamp or a Calendar
* an ISO formatted string
* a map with keys corresponding to the names of date-time field types
  and an (optional) chronology.
* a number of ints for the multi-argument varieties of partial constructors.

When called with no arguments produces a value of `LocalDate/now`.

Constructs a LocalDateTime out of 

* another partial (which must have all of the needed fields)
* an instant or a number of milliseconds
* a java (util/sql) Date/Timestamp or a Calendar
* an ISO formatted string
* a map with keys corresponding to the names of date-time field types
  and an (optional) chronology.
* a number of ints for the multi-argument varieties of partial constructors.

When called with no arguments produces a value of `LocalDateTime/now`.

Constructs a LocalTime out of 

* another partial (which must have all of the needed fields)
* an instant or a number of milliseconds
* a java (util/sql) Date/Timestamp or a Calendar
* an ISO formatted string
* a map with keys corresponding to the names of date-time field types
  and an (optional) chronology.
* a number of ints for the multi-argument varieties of partial constructors.

When called with no arguments produces a value of `LocalTime/now`.

Maximum of the given date-times/instants/partials/periods/intervals.

The maximum value of a property.

Merges two or more periods or partials together.

## Periods

Merges periods together to produce a Period. Type of the resulting period is
an aggregate of all period types participating in a merge.

Periods further in the arglist will overwrite earlier ones having overlapping
period types.

  (merge (years 2) (months 3))
  => #<Period P2Y3M>

  (merge (years 2) (years 3))
  => #<Period P3Y>

## Partials

Merges partials into an instance of Partial using the chronology of the
first partial:

  (merge (partial {:year 5}) (partial {:year 3, :monthOfYear 4}))
  => #<Partial 0003-04>

Will throw an exception if the resulting partial is invalid:

  (merge (local-date "2008-02-29") (partial {:year 2010}))
  => Exception ...

Constructs a Period representing the given number of milliseconds.  Given a
time entity tries to extract the number of millis. Given another period,
extracts it's millis part.

Number of millis in the given period/interval/pair of
instants, date-times or partials. Also handles durations.

Minimum of the given date-times/instants/partials/periods/intervals.

The minimum value of a property.

Subtracts one or more time entity from the first entity. Minus is defined
for the following entities:

* periods: period - {period, number}
* durations: duration - {duration, number}
* partials: partial - period
* instants: instant - {duration, period}

Calling `minus` with a single argument has the same effect as `negate` (for
durations and periods).  `(minus x y z)` has the same effect as `(plus x
(negate y) (negate z))`.

Constructs a Minutes period representing the given number of minutes. Given a time entity tries to extract the number of minutes. Given another period, extracts its minutes part.

Number of minutes in the given period/interval/pair of
instants, date-times or partials. Also handles durations.

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a monday.

Constructs a MonthDay out of 

* another partial (which must have all of the needed fields)
* an instant or a number of milliseconds
* a java (util/sql) Date/Timestamp or a Calendar
* an ISO formatted string
* a map with keys corresponding to the names of date-time field types
  and an (optional) chronology.
* a number of ints for the multi-argument varieties of partial constructors.

When called with no arguments produces a value of `MonthDay/now`.

Constructs a Months period representing the given number of months. Given a time entity tries to extract the number of months. Given another period, extracts its months part.

Number of months in the given period/interval/pair of
instants, date-times or partials.

Moves the end instant of the interval by the sum of given
periods/durations/numbers of milliseconds.

  (move-end-by (interval 0 10000) 3000 (duration 1000) (seconds 1))
  => #<Interval 00.000/15.000>

Accepts negative values:

  (move-end-by (interval 0 10000) -5000)
  => #<Interval 00.000/05.000>

Fails if the new end instant falls before the start instant.

  (move-end-by (interval 0 10000) -11000)
  => IllegalArgumentException...

Moves the end of the interval to the given instant/partial.

 (move-end-to (interval 0 10000) (instant 15000))
 => #<Interval 00.000/15.000>

Fails if the new end instant/partial falls before the start instant.

 (move-end-to (interval 0 10000) -1)
 => IllegalArgumentException...

Moves the start instant of the interval by the sum of given
periods/durations/numbers of milliseconds:

  (move-start-by (interval 0 10000) 3000 (duration 1000) (seconds 1))
  => #<Interval 05.000/10.000>

Accepts negative values:

  (move-start-by (interval 0 10000) -5000)
  => #<Interval 00.000/10.000>

Fails if the new start instant falls after the end instant.

  (move-start-by (interval 0 10000) 11000)
  ; => IllegalArgumentException...

Moves the start instant of the interval to the given instant.

 (move-start-to (interval 0 10000) (instant 5000))
 => #<Interval 05.000/10.000>

Fails if the new start instant falls after the end instant.

 (move-start-to (interval 0 10000) 15000)
 => IllegalArgumentException...

Negates a period or a duration.

(negate (negate x)) == x

Gets the overlap between this interval and the other one.

True if this interval overlaps the other one.

Parses an instance of DateTime with the given parsing formatter.
To parse an ISO-formatted string you can simply invoke the `date-time` constructor.

Parses an instance of LocalDate with the given parsing formatter.
To parse an ISO-formatted string you can simply invoke the `local-date` constructor.

Parses an instance of LocalDateTime with the given parsing formatter.
To parse an ISO-formatted string you can simply invoke the `local-date-time` constructor.

Parses an instance of LocalTime with the given parsing formatter.
To parse an ISO-formatted string you can simply invoke the `local-time` constructor.

Parses an instance of MutableDateTime with the given parsing formatter.
To parse an ISO-formatted string you can simply invoke the `mutable-date-time` constructor.

Constructs a Partial out of another partial or a map with keys corresponding
to the names of date-time field types and an (optional) chronology.

  (partial {})
  ; => #<Partial []>

  (partial {:year 5})
  ; => #<Partial 0005>

  (partial {:year 5, :chronology (ISOChronology/getInstanceUTC)})
  ; => #<Partial 0005>

  (partial {:era 1, :centuryOfEra 2, :yearOfEra 3, :dayOfYear 5})
  ; => #<Partial [era=1, centuryOfEra=2, yearOfEra=3, dayOfYear=5]>

Constructs an interval from two partials or a map containing:

* start and end keys
* start and a period
* end and a period

Partials must have equal type (contain an equal set of
DateTimeFieldTypes) and be contiguous:

  (partial-interval (local-date "2010-01-01")
                    (local-date "2011-02-01"))

Intervals are inclusive of the start partial and exclusive of the end
partial.

True if the given object is an instance of `PartialInterval`.

True if the given object is an instance of `ReadablePartial` (includes local
dates/times).

Constructs a Period. Takes a number, duration, string,
interval, another period or a map.

  (period {:years 2, :months 3})
  => #<Period P1Y3M>

  (period {:start 0, :end 1000})
  => #<Period PT1S>

  (period {:start 0, :duration 1000})
  => #<Period PT1S>

  (period {:duration 1000, :end 0})
  => #<Period PT1S>

  (period 1000)
  => #<Period PT1S>

  (period "PT1S")
  => #<Period PT1S>

  (period (duration 1000))
  => #<Period PT1S>

  (period (interval 0 1000))
  => #<Period PT1S>

Accepts two arguments where the second one is the desired type of the period
(either an instance of `PeriodType` or a vector of duration type keywords,
e.g. `[:seconds, :millis]`):

  (period {:start 0, :duration (* 1000 1000 1000)} [:days])
  => #<Period P11D>

  (period {:start 0, :duration (* 1000 1000 1000)} (period-type :weeks))
  => #<Period P1W>)

Either gets the period type of the given `ReadablePeriod` or constructs a
`PeriodType` out of the provided duration types.

  (period-type :years :months :weeks :days :hours :minutes :seconds :millis)
  => #<PeriodType PeriodType[Standard]>

  (period-type (years 1))
  => #<PeriodType PeriodType[Years]>

Constructs a sequence of duration type names out of a PeriodType.

(period-type->seq standard-period-type)
=> [:years :months :weeks :days :hours :minutes :seconds :millis]

(period-type->seq (period-type (years 1))
=> [:years]

True if the given object is an instance of `ReadablePeriod`.

Sums two or more time entities together. Plus is defined for the following
entities:

* periods: period + {period, number}
* durations: duration + {duration, number}
* partials: partial + period
* instants: instant + {duration, period}

## Periods

Sums periods and numbers together to produce a Period. No period
normalization or field overflows happen in the `plus` function.

  (plus (years 1) (years 1) (months 1))
  => #<Period P2Y1M>

Numbers are only allowed if type of the sum of the periods preceding the
number is single (e.g. years or months).

  (plus (years 1) 10)
  => #<Period P11Y>

  (plus (years 1) (months 1) 10)
  => Exception ...

  (plus (years 1) 10 (months 1))
  => #<Period P11Y1M>

Will always return the result of type `Period`, albeit with the most specific
`PeriodType`.

## Durations

Sums durations and numbers of milliseconds together to produce a Duration.

  (plus (duration 10) (duration 10) 10)
  => #<Duration PT0.030S>

## Partials

Sums a partial and periods together to produce a partial. Produces the most
specific type:

  (plus (local-date "2010-01-01") (years 2))
  => #<LocalDate 2012-01-01>

  (plus (partial {:year 2010}) (years 2))
  => #<Partial 2012>

Discards periods which aren't supported by the partial:

  (plus (partial {:year 2010}) (days 500))
  => #<Partial 2010>

## Instants

Sums an instant and periods, durations and numbers of milliseconds together
to produce an instant. Works with Instants and DateTimes.  Returns the most
specific type:

  (plus (date-time 0) 1000 (duration 1000) (years 40))
  => #<DateTime 2010-01-01T03:00:02.000+02:00>

  (plus (instant 0) 1000 (duration 1000) (years 40))
  => #<Instant 2010-01-01T00:00:02.000Z>

Prints a date entity using the provided formatter. Without the formatter
prints in ISO format.

Retrieves properties of a Partial or a DateTime.

For example, get a date with the last day of month:

  (-> (properties date) :dayOfMonth with-max-value)

or get maximum values for all of the properties:

  (->> (properties date)
       (map (comp max-value val))

Retrieves a property with the given key. Nil if the property doesn't
exist.

For example:

  (-> date properties :dayOfMonth value)

can be achieved efficiently by:

  (-> date (property :dayOfMonth) value)

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a saturday.

Constructs a Seconds period representing the given number of seconds. Given a time entity tries to extract the number of seconds. Given another period, extracts its seconds part.

Number of seconds in the given period/interval/pair of
instants, date-times or partials. Also handles durations.

Standard period type. Alias to `PeriodType/standard`.

Gets the start of the interval.

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a sunday.

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a thursday.

Produces a `DateTimeZone` out of a `java.util.TimeZone` or a timezone ID - a
case-sensitive string, keyword or symbol:

  (timezone :UTC)
  => #<FixedDateTimeZone UTC>

Default time zone is returned when called with no arguments:

  (timezone)
  => #<CachedDateTimeZone Europe/Vilnius>

Converts (almost) anything to a `java.util.Date`. By
default conversion will happen in the default time zone,
i.e.:

  ; In +02:00 zone
  (to-java-date "2013-12-10")
  => #inst "2013-12-09T22:00:00.000-00:00"

  ; In UTC
  (to-java-date "2013-12-10")
  => #inst "2013-12-10T00:00:00.000-00:00"

Converts a date entity to a `java.sql.Date`.

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a tuesday.

Value of this property.

Returns true if the given instant/date-time/partial with the
`dayOfWeek` property represents a wednesday.

Constructs a Weeks period representing the given number of weeks. Given a time entity tries to extract the number of weeks. Given another period, extracts its weeks part.

Number of weeks in the given period/interval/pair of
instants, date-times or partials.

Instant, partial or a period with the value of the property set to the
`max-value`.

Instant, partial or a period with the value of the property set to the
`min-value`.

Instant, partial or a period with the property set to the provided
value.

Set the time zone for the given date-time or a formatter.
Argument `zone` might be a `DateTimeZone` or a (case-sensitive)
name of the time zone.

Constructs a YearMonth out of 

* another partial (which must have all of the needed fields)
* an instant or a number of milliseconds
* a java (util/sql) Date/Timestamp or a Calendar
* an ISO formatted string
* a map with keys corresponding to the names of date-time field types
  and an (optional) chronology.
* a number of ints for the multi-argument varieties of partial constructors.

When called with no arguments produces a value of `YearMonth/now`.

Constructs a Years period representing the given number of years. Given a time entity tries to extract the number of years. Given another period, extracts its years part.

Number of years in the given period/interval/pair of
instants, date-times or partials.