http://www.joda.org/joda-time/: Date and time library to replace JDK date handling (Joda.org) 
/*
 *  Copyright 2001-2005 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;

import java.io.Serializable;

import org.joda.time.base.BaseInterval;
import org.joda.time.field.FieldUtils;
import org.joda.time.format.ISODateTimeFormat;
import org.joda.time.format.ISOPeriodFormat;


MutableInterval is the standard implementation of a mutable time interval.


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 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 ReadablePeriod. This represents the difference between the start and end points in terms of fields such as years and days. 

If performing significant calculations on an interval, it may be faster to
convert an Interval object to a MutableInterval one.


MutableInterval is mutable and not thread-safe, unless concurrent threads
are not invoking mutator methods.

Author:Stephen Colebourne, Brian S O'Neill
Since:1.0
/**
 * MutableInterval is the standard implementation of a mutable time interval.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * If performing significant calculations on an interval, it may be faster to
 * convert an Interval object to a MutableInterval one.
 * <p>
 * MutableInterval is mutable and not thread-safe, unless concurrent threads
 * are not invoking mutator methods.
 *
 * @author Stephen Colebourne
 * @author Brian S O'Neill
 * @since 1.0
 */
public class MutableInterval
        extends BaseInterval
        implements ReadWritableInterval, Cloneable, Serializable {

    
Serialization version 
/** Serialization version */
    private static final long serialVersionUID = -5982824024992428470L;

    //-----------------------------------------------------------------------
    
Parses a MutableInterval from the specified string. 
 The String formats are described by ISODateTimeFormat.dateTimeParser() and ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'. 
Params:
  • str –  the string to parse, not null
Since:2.0
/**
     * Parses a {@code MutableInterval} from the specified string.
     * <p>
     * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}
     * and {@link ISOPeriodFormat#standard()}, and may be 'datetime/datetime',
     * 'datetime/period' or 'period/datetime'.
     * 
     * @param str  the string to parse, not null
     * @since 2.0
     */
    public static MutableInterval parse(String str) {
        return new MutableInterval(str);
    }

    //-----------------------------------------------------------------------
    
Constructs a zero length time interval from 1970-01-01 to 1970-01-01.

/**
     * Constructs a zero length time interval from 1970-01-01 to 1970-01-01.
     */
    public MutableInterval() {
        super(0L, 0L, null);
    }

    
Constructs an interval from a start and end instant with the ISO default chronology.

Params:
  • startInstant –  start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
  • endInstant –  end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
Throws:
/**
     * Constructs an interval from a start and end instant with the ISO default chronology.
     * 
     * @param startInstant  start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
     * @param endInstant  end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
     * @throws IllegalArgumentException if the end is before the start
     */
    public MutableInterval(long startInstant, long endInstant) {
        super(startInstant, endInstant, null);
    }

    
Constructs an interval from a start and end instant with a chronology.

Params:
  • chronology –  the chronology to use, null is ISO default
  • startInstant –  start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
  • endInstant –  end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
Throws:
/**
     * Constructs an interval from a start and end instant with a chronology.
     * 
     * @param chronology  the chronology to use, null is ISO default
     * @param startInstant  start of this interval, as milliseconds from 1970-01-01T00:00:00Z.
     * @param endInstant  end of this interval, as milliseconds from 1970-01-01T00:00:00Z.
     * @throws IllegalArgumentException if the end is before the start
     */
    public MutableInterval(long startInstant, long endInstant, Chronology chronology) {
        super(startInstant, endInstant, chronology);
    }

    
Constructs an interval from a start and end instant.


The chronology used is that of the start instant.

Params:
  • start –  start of this interval, null means now
  • end –  end of this interval, null means now
Throws:
/**
     * Constructs an interval from a start and end instant.
     * <p>
     * The chronology used is that of the start instant.
     * 
     * @param start  start of this interval, null means now
     * @param end  end of this interval, null means now
     * @throws IllegalArgumentException if the end is before the start
     */
    public MutableInterval(ReadableInstant start, ReadableInstant end) {
        super(start, end);
    }

    
Constructs an interval from a start instant and a duration.

Params:
  • start –  start of this interval, null means now
  • duration –  the duration of this interval, null means zero length
Throws:
/**
     * Constructs an interval from a start instant and a duration.
     * 
     * @param start  start of this interval, null means now
     * @param duration  the duration of this interval, null means zero length
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the end instant exceeds the capacity of a long
     */
    public MutableInterval(ReadableInstant start, ReadableDuration duration) {
        super(start, duration);
    }

    
Constructs an interval from a millisecond duration and an end instant.

Params:
  • duration –  the duration of this interval, null means zero length
  • end –  end of this interval, null means now
Throws:
/**
     * Constructs an interval from a millisecond duration and an end instant.
     * 
     * @param duration  the duration of this interval, null means zero length
     * @param end  end of this interval, null means now
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the start instant exceeds the capacity of a long
     */
    public MutableInterval(ReadableDuration duration, ReadableInstant end) {
        super(duration, end);
    }

    
Constructs an interval from a start instant and a time period.


When forming the interval, the chronology from the instant is used
if present, otherwise the chronology of the period is used.

Params:
  • start –  start of this interval, null means now
  • period –  the period of this interval, null means zero length
Throws:
/**
     * Constructs an interval from a start instant and a time period.
     * <p>
     * When forming the interval, the chronology from the instant is used
     * if present, otherwise the chronology of the period is used.
     * 
     * @param start  start of this interval, null means now
     * @param period  the period of this interval, null means zero length
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the end instant exceeds the capacity of a long
     */
    public MutableInterval(ReadableInstant start, ReadablePeriod period) {
        super(start, period);
    }

    
Constructs an interval from a time period and an end instant.


When forming the interval, the chronology from the instant is used
if present, otherwise the chronology of the period is used.

Params:
  • period –  the period of this interval, null means zero length
  • end –  end of this interval, null means now
Throws:
/**
     * Constructs an interval from a time period and an end instant.
     * <p>
     * When forming the interval, the chronology from the instant is used
     * if present, otherwise the chronology of the period is used.
     * 
     * @param period  the period of this interval, null means zero length
     * @param end  end of this interval, null means now
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the start instant exceeds the capacity of a long
     */
    public MutableInterval(ReadablePeriod period, ReadableInstant end) {
        super(period, end);
    }

    
Constructs a time interval by converting or copying from another object.

 The recognised object types are defined in ConverterManager and include ReadableInterval and String. The String formats are described by ISODateTimeFormat.dateTimeParser() and ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'. 
Params:
  • interval –  the time interval to copy
Throws:
/**
     * Constructs a time interval by converting or copying from another object.
     * <p>
     * The recognised object types are defined in
     * {@link org.joda.time.convert.ConverterManager ConverterManager} and
     * include ReadableInterval and String.
     * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}
     * and {@link ISOPeriodFormat#standard()}, and may be 'datetime/datetime',
     * 'datetime/period' or 'period/datetime'.
     * 
     * @param interval  the time interval to copy
     * @throws IllegalArgumentException if the interval is invalid
     */
    public MutableInterval(Object interval) {
        super(interval, null);
    }

    
Constructs a time interval by converting or copying from another object,
overriding the chronology.

 The recognised object types are defined in ConverterManager and include ReadableInterval and String. The String formats are described by ISODateTimeFormat.dateTimeParser() and ISOPeriodFormat.standard(), and may be 'datetime/datetime', 'datetime/period' or 'period/datetime'. 
Params:
  • interval –  the time interval to copy
  • chronology –  the chronology to use, null means ISO default
Throws:
/**
     * Constructs a time interval by converting or copying from another object,
     * overriding the chronology.
     * <p>
     * The recognised object types are defined in
     * {@link org.joda.time.convert.ConverterManager ConverterManager} and
     * include ReadableInterval and String.
     * The String formats are described by {@link ISODateTimeFormat#dateTimeParser()}
     * and {@link ISOPeriodFormat#standard()}, and may be 'datetime/datetime',
     * 'datetime/period' or 'period/datetime'.
     * 
     * @param interval  the time interval to copy
     * @param chronology  the chronology to use, null means ISO default
     * @throws IllegalArgumentException if the interval is invalid
     */
    public MutableInterval(Object interval, Chronology chronology) {
        super(interval, chronology);
    }

    //-----------------------------------------------------------------------
    
Sets this interval from two millisecond instants retaining the chronology.

Params:
  • startInstant –  the start of the time interval
  • endInstant –  the start of the time interval
Throws:
/**
     * Sets this interval from two millisecond instants retaining the chronology.
     *
     * @param startInstant  the start of the time interval
     * @param endInstant  the start of the time interval
     * @throws IllegalArgumentException if the end is before the start
     */
    public void setInterval(long startInstant, long endInstant) {
        super.setInterval(startInstant, endInstant, getChronology());
    }

    
Sets this interval to be the same as another.

Params:
  • interval –  the interval to copy
Throws:
/**
     * Sets this interval to be the same as another.
     *
     * @param interval  the interval to copy
     * @throws IllegalArgumentException if the interval is null
     */
    public void setInterval(ReadableInterval interval) {
        if (interval == null) {
            throw new IllegalArgumentException("Interval must not be null");
        }
        long startMillis = interval.getStartMillis();
        long endMillis = interval.getEndMillis();
        Chronology chrono = interval.getChronology();
        super.setInterval(startMillis, endMillis, chrono);
    }

    
Sets this interval from two instants, replacing the chronology with
that from the start instant.

Params:
  • start –  the start of the time interval
  • end –  the start of the time interval
Throws:
/**
     * Sets this interval from two instants, replacing the chronology with
     * that from the start instant.
     *
     * @param start  the start of the time interval
     * @param end  the start of the time interval
     * @throws IllegalArgumentException if the end is before the start
     */
    public void setInterval(ReadableInstant start, ReadableInstant end) {
        if (start == null && end == null) {
            long now = DateTimeUtils.currentTimeMillis();
            setInterval(now, now);
        } else {
            long startMillis = DateTimeUtils.getInstantMillis(start);
            long endMillis = DateTimeUtils.getInstantMillis(end);
            Chronology chrono = DateTimeUtils.getInstantChronology(start);
            super.setInterval(startMillis, endMillis, chrono);
        }
    }

    //-----------------------------------------------------------------------
    
Sets the chronology of this time interval.

Params:
  • chrono –  the chronology to use, null means ISO default
/**
     * Sets the chronology of this time interval.
     *
     * @param chrono  the chronology to use, null means ISO default
     */
    public void setChronology(Chronology chrono) {
        super.setInterval(getStartMillis(), getEndMillis(), chrono);
    }

    
Sets the start of this time interval.

Params:
  • startInstant –  the start of the time interval,
 millisecond instant from 1970-01-01T00:00:00Z
Throws:
/**
     * Sets the start of this time interval.
     *
     * @param startInstant  the start of the time interval,
     *  millisecond instant from 1970-01-01T00:00:00Z
     * @throws IllegalArgumentException if the end is before the start
     */
    public void setStartMillis(long startInstant) {
        super.setInterval(startInstant, getEndMillis(), getChronology());
    }

    
Sets the start of this time interval as an Instant.

Params:
  • start –  the start of the time interval, null means now
Throws:
/**
     * Sets the start of this time interval as an Instant.
     *
     * @param start  the start of the time interval, null means now
     * @throws IllegalArgumentException if the end is before the start
     */
    public void setStart(ReadableInstant start) {
        long startMillis = DateTimeUtils.getInstantMillis(start);
        super.setInterval(startMillis, getEndMillis(), getChronology());
    }

    
Sets the end of this time interval.

Params:
  • endInstant –  the end of the time interval,
 millisecond instant from 1970-01-01T00:00:00Z
Throws:
/** 
     * Sets the end of this time interval.
     *
     * @param endInstant  the end of the time interval,
     *  millisecond instant from 1970-01-01T00:00:00Z
     * @throws IllegalArgumentException if the end is before the start
     */
    public void setEndMillis(long endInstant) {
        super.setInterval(getStartMillis(), endInstant, getChronology());
    }

    
Sets the end of this time interval as an Instant.

Params:
  • end –  the end of the time interval, null means now
Throws:
/** 
     * Sets the end of this time interval as an Instant.
     *
     * @param end  the end of the time interval, null means now
     * @throws IllegalArgumentException if the end is before the start
     */
    public void setEnd(ReadableInstant end) {
        long endMillis = DateTimeUtils.getInstantMillis(end);
        super.setInterval(getStartMillis(), endMillis, getChronology());
    }

    //-----------------------------------------------------------------------
    
Sets the duration of this time interval, preserving the start instant.

Params:
  • duration –  new duration for interval
Throws:
/**
     * Sets the duration of this time interval, preserving the start instant.
     *
     * @param duration  new duration for interval
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the end instant exceeds the capacity of a long
     */
    public void setDurationAfterStart(long duration) {
        setEndMillis(FieldUtils.safeAdd(getStartMillis(), duration));
    }

    
Sets the duration of this time interval, preserving the end instant.

Params:
  • duration –  new duration for interval
Throws:
/**
     * Sets the duration of this time interval, preserving the end instant.
     *
     * @param duration  new duration for interval
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the start instant exceeds the capacity of a long
     */
    public void setDurationBeforeEnd(long duration) {
        setStartMillis(FieldUtils.safeAdd(getEndMillis(), -duration));
    }

    //-----------------------------------------------------------------------
    
Sets the duration of this time interval, preserving the start instant.

Params:
  • duration –  new duration for interval, null means zero length
Throws:
/**
     * Sets the duration of this time interval, preserving the start instant.
     *
     * @param duration  new duration for interval, null means zero length
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the end instant exceeds the capacity of a long
     */
    public void setDurationAfterStart(ReadableDuration duration) {
        long durationMillis = DateTimeUtils.getDurationMillis(duration);
        setEndMillis(FieldUtils.safeAdd(getStartMillis(), durationMillis));
    }

    
Sets the duration of this time interval, preserving the end instant.

Params:
  • duration –  new duration for interval, null means zero length
Throws:
/**
     * Sets the duration of this time interval, preserving the end instant.
     *
     * @param duration  new duration for interval, null means zero length
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the start instant exceeds the capacity of a long
     */
    public void setDurationBeforeEnd(ReadableDuration duration) {
        long durationMillis = DateTimeUtils.getDurationMillis(duration);
        setStartMillis(FieldUtils.safeAdd(getEndMillis(), -durationMillis));
    }

    //-----------------------------------------------------------------------
    
Sets the period of this time interval, preserving the start instant
and using the ISOChronology in the default zone for calculations.

Params:
  • period –  new period for interval, null means zero length
Throws:
/**
     * Sets the period of this time interval, preserving the start instant
     * and using the ISOChronology in the default zone for calculations.
     *
     * @param period  new period for interval, null means zero length
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the end instant exceeds the capacity of a long
     */
    public void setPeriodAfterStart(ReadablePeriod period) {
        if (period == null) {
            setEndMillis(getStartMillis());
        } else {
            setEndMillis(getChronology().add(period, getStartMillis(), 1));
        }
    }

    
Sets the period of this time interval, preserving the end instant
and using the ISOChronology in the default zone for calculations.

Params:
  • period –  new period for interval, null means zero length
Throws:
/**
     * Sets the period of this time interval, preserving the end instant
     * and using the ISOChronology in the default zone for calculations.
     *
     * @param period  new period for interval, null means zero length
     * @throws IllegalArgumentException if the end is before the start
     * @throws ArithmeticException if the start instant exceeds the capacity of a long
     */
    public void setPeriodBeforeEnd(ReadablePeriod period) {
        if (period == null) {
            setStartMillis(getEndMillis());
        } else {
            setStartMillis(getChronology().add(period, getEndMillis(), -1));
        }
    }

    //-----------------------------------------------------------------------
    
Clone this object without having to cast the returned object.

Returns:a clone of the this object.
/**
     * Clone this object without having to cast the returned object.
     *
     * @return a clone of the this object.
     */
    public MutableInterval copy() {
        return (MutableInterval) clone();
    }

    
Clone this object.

Returns:a clone of this object.
/**
     * Clone this object.
     *
     * @return a clone of this object.
     */
    public Object clone() {
        try {
            return super.clone();
        } catch (CloneNotSupportedException ex) {
            throw new InternalError("Clone error");
        }
    }

}