All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.joda.time.ReadableInterval Maven / Gradle / Ivy

There is a newer version: 2.12.15
Show newest version
/*
 *  Copyright 2001-2006 Stephen Colebourne
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package org.joda.time;

/** 
 * Readable interface for an interval of time between two instants.
 * 

* A time interval represents a period of time between two instants. * Intervals are inclusive of the start instant and exclusive of the end. * The end instant is always greater than or equal to the start instant. *

* Intervals have a fixed millisecond duration. * This is the difference between the start and end instants. * The duration is represented separately by {@link ReadableDuration}. * As a result, intervals are not comparable. * To compare the length of two intervals, you should compare their durations. *

* An interval can also be converted to a {@link ReadablePeriod}. * This represents the difference between the start and end points in terms of fields * such as years and days. *

* Methods that are passed an interval as a parameter will treat null * as a zero length interval at the current instant in time. * * @author Sean Geoghegan * @author Brian S O'Neill * @author Stephen Colebourne * @since 1.0 */ public interface ReadableInterval { /** * Gets the chronology of the interval, which is the chronology of the first datetime. * * @return the chronology of the interval */ Chronology getChronology(); /** * Gets the start of this time interval which is inclusive. * * @return the start of the time interval, * millisecond instant from 1970-01-01T00:00:00Z */ long getStartMillis(); /** * Gets the start of this time interval, which is inclusive, as a DateTime. * * @return the start of the time interval */ DateTime getStart(); /** * Gets the end of this time interval which is exclusive. * * @return the end of the time interval, * millisecond instant from 1970-01-01T00:00:00Z */ long getEndMillis(); /** * Gets the end of this time interval, which is exclusive, as a DateTime. * * @return the end of the time interval */ DateTime getEnd(); //----------------------------------------------------------------------- /** * Does this time interval contain the specified instant. *

* Non-zero duration intervals are inclusive of the start instant and * exclusive of the end. A zero duration interval cannot contain anything. *

* For example: *

     * [09:00 to 10:00) contains 08:59  = false (before start)
     * [09:00 to 10:00) contains 09:00  = true
     * [09:00 to 10:00) contains 09:59  = true
     * [09:00 to 10:00) contains 10:00  = false (equals end)
     * [09:00 to 10:00) contains 10:01  = false (after end)
     * 
     * [14:00 to 14:00) contains 14:00  = false (zero duration contains nothing)
     * 
* * @param instant the instant, null means now * @return true if this time interval contains the instant */ boolean contains(ReadableInstant instant); /** * Does this time interval contain the specified time interval. *

* Non-zero duration intervals are inclusive of the start instant and * exclusive of the end. The other interval is contained if this interval * wholly contains, starts, finishes or equals it. * A zero duration interval cannot contain anything. *

* When two intervals are compared the result is one of three states: * (a) they abut, (b) there is a gap between them, (c) they overlap. * The contains method is not related to these states. * In particular, a zero duration interval is contained at the start of * a larger interval, but does not overlap (it abuts instead). *

* For example: *

     * [09:00 to 10:00) contains [09:00 to 10:00)  = true
     * [09:00 to 10:00) contains [09:00 to 09:30)  = true
     * [09:00 to 10:00) contains [09:30 to 10:00)  = true
     * [09:00 to 10:00) contains [09:15 to 09:45)  = true
     * [09:00 to 10:00) contains [09:00 to 09:00)  = true
     * 
     * [09:00 to 10:00) contains [08:59 to 10:00)  = false (otherStart before thisStart)
     * [09:00 to 10:00) contains [09:00 to 10:01)  = false (otherEnd after thisEnd)
     * [09:00 to 10:00) contains [10:00 to 10:00)  = false (otherStart equals thisEnd)
     * 
     * [14:00 to 14:00) contains [14:00 to 14:00)  = false (zero duration contains nothing)
     * 
* * @param interval the time interval to compare to, null means a zero duration interval now * @return true if this time interval contains the time interval */ boolean contains(ReadableInterval interval); /** * Does this time interval overlap the specified time interval. *

* Intervals are inclusive of the start instant and exclusive of the end. * An interval overlaps another if it shares some common part of the * datetime continuum. *

* When two intervals are compared the result is one of three states: * (a) they abut, (b) there is a gap between them, (c) they overlap. * The abuts state takes precedence over the other two, thus a zero duration * interval at the start of a larger interval abuts and does not overlap. *

* For example: *

     * [09:00 to 10:00) overlaps [08:00 to 08:30)  = false (completely before)
     * [09:00 to 10:00) overlaps [08:00 to 09:00)  = false (abuts before)
     * [09:00 to 10:00) overlaps [08:00 to 09:30)  = true
     * [09:00 to 10:00) overlaps [08:00 to 10:00)  = true
     * [09:00 to 10:00) overlaps [08:00 to 11:00)  = true
     * 
     * [09:00 to 10:00) overlaps [09:00 to 09:00)  = false (abuts before)
     * [09:00 to 10:00) overlaps [09:00 to 09:30)  = true
     * [09:00 to 10:00) overlaps [09:00 to 10:00)  = true
     * [09:00 to 10:00) overlaps [09:00 to 11:00)  = true
     * 
     * [09:00 to 10:00) overlaps [09:30 to 09:30)  = true
     * [09:00 to 10:00) overlaps [09:30 to 10:00)  = true
     * [09:00 to 10:00) overlaps [09:30 to 11:00)  = true
     * 
     * [09:00 to 10:00) overlaps [10:00 to 10:00)  = false (abuts after)
     * [09:00 to 10:00) overlaps [10:00 to 11:00)  = false (abuts after)
     * 
     * [09:00 to 10:00) overlaps [10:30 to 11:00)  = false (completely after)
     * 
     * [14:00 to 14:00) overlaps [14:00 to 14:00)  = false (abuts before and after)
     * [14:00 to 14:00) overlaps [13:00 to 15:00)  = true
     * 
* * @param interval the time interval to compare to, null means a zero length interval now * @return true if the time intervals overlap */ boolean overlaps(ReadableInterval interval); //----------------------------------------------------------------------- /** * Is this time interval after the specified instant. *

* Intervals are inclusive of the start instant and exclusive of the end. * * @param instant the instant to compare to, null means now * @return true if this time interval is after the instant */ boolean isAfter(ReadableInstant instant); /** * Is this time interval entirely after the specified interval. *

* Intervals are inclusive of the start instant and exclusive of the end. * * @param interval the interval to compare to, null means now * @return true if this time interval is after the interval specified */ boolean isAfter(ReadableInterval interval); /** * Is this time interval before the specified instant. *

* Intervals are inclusive of the start instant and exclusive of the end. * * @param instant the instant to compare to, null means now * @return true if this time interval is before the instant */ boolean isBefore(ReadableInstant instant); /** * Is this time interval entirely before the specified interval. *

* Intervals are inclusive of the start instant and exclusive of the end. * * @param interval the interval to compare to, null means now * @return true if this time interval is before the interval specified */ boolean isBefore(ReadableInterval interval); //----------------------------------------------------------------------- /** * Get this interval as an immutable Interval object. *

* This will either typecast this instance, or create a new Interval. * * @return the interval as an Interval object */ Interval toInterval(); /** * Get this time interval as a MutableInterval. *

* This will always return a new MutableInterval with the same interval. * * @return the time interval as a MutableInterval object */ MutableInterval toMutableInterval(); //----------------------------------------------------------------------- /** * Gets the millisecond duration of this time interval. * * @return the millisecond duration of the time interval * @throws ArithmeticException if the duration exceeds the capacity of a long */ Duration toDuration(); /** * Gets the millisecond duration of this time interval. * * @return the millisecond duration of the time interval * @throws ArithmeticException if the duration exceeds the capacity of a long */ long toDurationMillis(); /** * Converts the duration of the interval to a period using the * standard period type. *

* This method should be used to extract the field values describing the * difference between the start and end instants. * * @return a time period derived from the interval */ Period toPeriod(); /** * Converts the duration of the interval to a period using the * specified period type. *

* This method should be used to extract the field values describing the * difference between the start and end instants. * * @param type the requested type of the duration, null means standard * @return a time period derived from the interval */ Period toPeriod(PeriodType type); //----------------------------------------------------------------------- /** * Compares this object with the specified object for equality based * on start and end millis plus the chronology. * All ReadableInterval instances are accepted. *

* To compare the duration of two time intervals, use {@link #toDuration()} * to get the durations and compare those. * * @param readableInterval a readable interval to check against * @return true if the start and end millis are equal */ boolean equals(Object readableInterval); /** * Gets a hash code for the time interval that is compatible with the * equals method. *

* The formula used must be as follows: *

int result = 97;
     * result = 31 * result + ((int) (getStartMillis() ^ (getStartMillis() >>> 32)));
     * result = 31 * result + ((int) (getEndMillis() ^ (getEndMillis() >>> 32)));
     * result = 31 * result + getChronology().hashCode();
     * return result;
* * @return a hash code */ int hashCode(); //----------------------------------------------------------------------- /** * Get the value as a String in the ISO8601 interval format. *

* For example, "2004-06-09T12:30:00.000/2004-07-10T13:30:00.000". * * @return the value as an ISO8601 string */ String toString(); }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy