/*
 *  Copyright 2001-2009 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;

Defines the calculation engine for duration fields.
The interface defines a set of methods that manipulate a millisecond duration
with regards to a single field, such as months or seconds.

This design is extensible so, if you wish, you can extract a different field from
the millisecond duration. A number of standard implementations are provided to assist.
Author:
Stephen Colebourne, Brian S O'Neill
Since:
1.0/**
 * Defines the calculation engine for duration fields.
 * The interface defines a set of methods that manipulate a millisecond duration
 * with regards to a single field, such as months or seconds.
 * <p>
 * This design is extensible so, if you wish, you can extract a different field from
 * the millisecond duration. A number of standard implementations are provided to assist.
 *
 * @author Stephen Colebourne
 * @author Brian S O'Neill
 * @since 1.0
 */
public abstract class DurationField implements Comparable<DurationField> {

    
Get the type of the field.
Returns:
field type/**
     * Get the type of the field.
     * 
     * @return field type
     */
    public abstract DurationFieldType getType();

    
Get the name of the field.

By convention, names are plural.
Returns:
field name/**
     * Get the name of the field.
     * <p>
     * By convention, names are plural.
     * 
     * @return field name
     */
    public abstract String getName();

    
Returns true if this field is supported.
Returns:
true if this field is supported/**
     * Returns true if this field is supported.
     * 
     * @return true if this field is supported
     */
    public abstract boolean isSupported();

    
Is this field precise. A precise field can calculate its value from
milliseconds without needing a reference date. Put another way, a
precise field's unit size is not variable.
See Also:
getUnitMillis()
Returns:
true if precise/**
     * Is this field precise. A precise field can calculate its value from
     * milliseconds without needing a reference date. Put another way, a
     * precise field's unit size is not variable.
     * 
     * @return true if precise
     * @see #getUnitMillis()
     */
    public abstract boolean isPrecise();
    
    
Returns the amount of milliseconds per unit value of this field. For
example, if this field represents "seconds", then this returns the
milliseconds in one second.

For imprecise fields, the unit size is variable, and so this method
returns a suitable average value.
See Also:
isPrecise()
Returns:
the unit size of this field, in milliseconds/**
     * Returns the amount of milliseconds per unit value of this field. For
     * example, if this field represents "seconds", then this returns the
     * milliseconds in one second.
     * <p>
     * For imprecise fields, the unit size is variable, and so this method
     * returns a suitable average value.
     *
     * @return the unit size of this field, in milliseconds
     * @see #isPrecise()
     */
    public abstract long getUnitMillis();

    //------------------------------------------------------------------------
    
Get the value of this field from the milliseconds, which is approximate
if this field is imprecise.
Params:
duration –  the milliseconds to query, which may be negative
Throws:
ArithmeticException – if the value is too large for an int
Returns:
the value of the field, in the units of the field, which may be
negative/**
     * Get the value of this field from the milliseconds, which is approximate
     * if this field is imprecise.
     *
     * @param duration  the milliseconds to query, which may be negative
     * @return the value of the field, in the units of the field, which may be
     * negative
     * @throws ArithmeticException if the value is too large for an int
     */
    public abstract int getValue(long duration);

    
Get the value of this field from the milliseconds, which is approximate
if this field is imprecise.
Params:
duration –  the milliseconds to query, which may be negative
Returns:
the value of the field, in the units of the field, which may be
negative/**
     * Get the value of this field from the milliseconds, which is approximate
     * if this field is imprecise.
     *
     * @param duration  the milliseconds to query, which may be negative
     * @return the value of the field, in the units of the field, which may be
     * negative
     */
    public abstract long getValueAsLong(long duration);

    
Get the value of this field from the milliseconds relative to an
instant. For precise fields this method produces the same result as for
the single argument get method.

If the millisecond duration is positive, then the instant is treated as a
"start instant". If negative, the instant is treated as an "end instant".
Params:
duration –  the milliseconds to query, which may be negative
instant –  the start instant to calculate relative to
Throws:
ArithmeticException – if the value is too large for an int
Returns:
the value of the field, in the units of the field, which may be
negative/**
     * Get the value of this field from the milliseconds relative to an
     * instant. For precise fields this method produces the same result as for
     * the single argument get method.
     * <p>
     * If the millisecond duration is positive, then the instant is treated as a
     * "start instant". If negative, the instant is treated as an "end instant".
     * 
     * @param duration  the milliseconds to query, which may be negative
     * @param instant  the start instant to calculate relative to
     * @return the value of the field, in the units of the field, which may be
     * negative
     * @throws ArithmeticException if the value is too large for an int
     */
    public abstract int getValue(long duration, long instant);

    
Get the value of this field from the milliseconds relative to an
instant. For precise fields this method produces the same result as for
the single argument get method.

If the millisecond duration is positive, then the instant is treated as a
"start instant". If negative, the instant is treated as an "end instant".
Params:
duration –  the milliseconds to query, which may be negative
instant –  the start instant to calculate relative to
Returns:
the value of the field, in the units of the field, which may be
negative/**
     * Get the value of this field from the milliseconds relative to an
     * instant. For precise fields this method produces the same result as for
     * the single argument get method.
     * <p>
     * If the millisecond duration is positive, then the instant is treated as a
     * "start instant". If negative, the instant is treated as an "end instant".
     * 
     * @param duration  the milliseconds to query, which may be negative
     * @param instant  the start instant to calculate relative to
     * @return the value of the field, in the units of the field, which may be
     * negative
     */
    public abstract long getValueAsLong(long duration, long instant);

    //------------------------------------------------------------------------
    
Get the millisecond duration of this field from its value, which is
approximate if this field is imprecise.
Params:
value –  the value of the field, which may be negative
Returns:
the milliseconds that the field represents, which may be
negative/**
     * Get the millisecond duration of this field from its value, which is
     * approximate if this field is imprecise.
     * 
     * @param value  the value of the field, which may be negative
     * @return the milliseconds that the field represents, which may be
     * negative
     */
    public abstract long getMillis(int value);

    
Get the millisecond duration of this field from its value, which is
approximate if this field is imprecise.
Params:
value –  the value of the field, which may be negative
Returns:
the milliseconds that the field represents, which may be
negative/**
     * Get the millisecond duration of this field from its value, which is
     * approximate if this field is imprecise.
     * 
     * @param value  the value of the field, which may be negative
     * @return the milliseconds that the field represents, which may be
     * negative
     */
    public abstract long getMillis(long value);

    
Get the millisecond duration of this field from its value relative to an
instant. For precise fields this method produces the same result as for
the single argument getMillis method.

If the value is positive, then the instant is treated as a "start
instant". If negative, the instant is treated as an "end instant".
Params:
value –  the value of the field, which may be negative
instant –  the instant to calculate relative to
Returns:
the millisecond duration that the field represents, which may be
negative/**
     * Get the millisecond duration of this field from its value relative to an
     * instant. For precise fields this method produces the same result as for
     * the single argument getMillis method.
     * <p>
     * If the value is positive, then the instant is treated as a "start
     * instant". If negative, the instant is treated as an "end instant".
     *
     * @param value  the value of the field, which may be negative
     * @param instant  the instant to calculate relative to
     * @return the millisecond duration that the field represents, which may be
     * negative
     */
    public abstract long getMillis(int value, long instant);

    
Get the millisecond duration of this field from its value relative to an
instant. For precise fields this method produces the same result as for
the single argument getMillis method.

If the value is positive, then the instant is treated as a "start
instant". If negative, the instant is treated as an "end instant".
Params:
value –  the value of the field, which may be negative
instant –  the instant to calculate relative to
Returns:
the millisecond duration that the field represents, which may be
negative/**
     * Get the millisecond duration of this field from its value relative to an
     * instant. For precise fields this method produces the same result as for
     * the single argument getMillis method.
     * <p>
     * If the value is positive, then the instant is treated as a "start
     * instant". If negative, the instant is treated as an "end instant".
     *
     * @param value  the value of the field, which may be negative
     * @param instant  the instant to calculate relative to
     * @return the millisecond duration that the field represents, which may be
     * negative
     */
    public abstract long getMillis(long value, long instant);

    
Adds a duration value (which may be negative) to the instant.
Params:
instant –  the milliseconds from 1970-01-01T00:00:00Z to add to
value –  the value to add, in the units of the field
Returns:
the updated milliseconds/**
     * Adds a duration value (which may be negative) to the instant.
     * 
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z to add to
     * @param value  the value to add, in the units of the field
     * @return the updated milliseconds
     */
    public abstract long add(long instant, int value);

    
Adds a duration value (which may be negative) to the instant.
Params:
instant –  the milliseconds from 1970-01-01T00:00:00Z to add to
value –  the value to add, in the units of the field
Returns:
the updated milliseconds/**
     * Adds a duration value (which may be negative) to the instant.
     * 
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z to add to
     * @param value  the value to add, in the units of the field
     * @return the updated milliseconds
     */
    public abstract long add(long instant, long value);

    
Subtracts a duration value (which may be negative) from the instant.
Params:
instant –  the milliseconds from 1970-01-01T00:00:00Z to subtract from
value –  the value to subtract, in the units of the field
Returns:
the updated milliseconds
Since:
1.1/**
     * Subtracts a duration value (which may be negative) from the instant.
     * 
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z to subtract from
     * @param value  the value to subtract, in the units of the field
     * @return the updated milliseconds
     * @since 1.1
     */
    public long subtract(long instant, int value) {
        if (value == Integer.MIN_VALUE) {
            return subtract(instant, (long) value);
        }
        return add(instant, -value);
    }

    
Subtracts a duration value (which may be negative) from the instant.
Params:
instant –  the milliseconds from 1970-01-01T00:00:00Z to subtract from
value –  the value to subtract, in the units of the field
Returns:
the updated milliseconds
Since:
1.1/**
     * Subtracts a duration value (which may be negative) from the instant.
     * 
     * @param instant  the milliseconds from 1970-01-01T00:00:00Z to subtract from
     * @param value  the value to subtract, in the units of the field
     * @return the updated milliseconds
     * @since 1.1
     */
    public long subtract(long instant, long value) {
        if (value == Long.MIN_VALUE) {
            throw new ArithmeticException("Long.MIN_VALUE cannot be negated");
        }
        return add(instant, -value);
    }

    
Computes the difference between two instants, as measured in the units
of this field. Any fractional units are dropped from the result. Calling
getDifference reverses the effect of calling add. In the following code:
long instant = ...
int v = ...
int age = getDifference(add(instant, v), instant);

The value 'age' is the same as the value 'v'.
Params:
minuendInstant – the milliseconds from 1970-01-01T00:00:00Z to
subtract from
subtrahendInstant – the milliseconds from 1970-01-01T00:00:00Z to
subtract off the minuend
Returns:
the difference in the units of this field/**
     * Computes the difference between two instants, as measured in the units
     * of this field. Any fractional units are dropped from the result. Calling
     * getDifference reverses the effect of calling add. In the following code:
     *
     * <pre>
     * long instant = ...
     * int v = ...
     * int age = getDifference(add(instant, v), instant);
     * </pre>
     *
     * The value 'age' is the same as the value 'v'.
     *
     * @param minuendInstant the milliseconds from 1970-01-01T00:00:00Z to
     * subtract from
     * @param subtrahendInstant the milliseconds from 1970-01-01T00:00:00Z to
     * subtract off the minuend
     * @return the difference in the units of this field
     */
    public abstract int getDifference(long minuendInstant, long subtrahendInstant);

    
Computes the difference between two instants, as measured in the units
of this field. Any fractional units are dropped from the result. Calling
getDifference reverses the effect of calling add. In the following code:
long instant = ...
long v = ...
long age = getDifferenceAsLong(add(instant, v), instant);

The value 'age' is the same as the value 'v'.
Params:
minuendInstant – the milliseconds from 1970-01-01T00:00:00Z to
subtract from
subtrahendInstant – the milliseconds from 1970-01-01T00:00:00Z to
subtract off the minuend
Returns:
the difference in the units of this field/**
     * Computes the difference between two instants, as measured in the units
     * of this field. Any fractional units are dropped from the result. Calling
     * getDifference reverses the effect of calling add. In the following code:
     *
     * <pre>
     * long instant = ...
     * long v = ...
     * long age = getDifferenceAsLong(add(instant, v), instant);
     * </pre>
     *
     * The value 'age' is the same as the value 'v'.
     *
     * @param minuendInstant the milliseconds from 1970-01-01T00:00:00Z to
     * subtract from
     * @param subtrahendInstant the milliseconds from 1970-01-01T00:00:00Z to
     * subtract off the minuend
     * @return the difference in the units of this field
     */
    public abstract long getDifferenceAsLong(long minuendInstant, long subtrahendInstant);

    // Adding this definition would be backwards incompatible with earlier subclasses
    // This definition of compareTo was present in previous versions, and still applies
//    /**
//     * Compares this duration field with another duration field for ascending
//     * unit millisecond order. This ordering is inconsistent with equals, as it
//     * ignores name and precision.
//     *
//     * @param durationField  a duration field to check against
//     * @return negative value if this is less, 0 if equal, or positive value if greater
//     * @throws NullPointerException if the object is null
//     * @throws ClassCastException if the object type is not supported
//     */
//    public abstract int compareTo(DurationField durationField);

    /**
     * Returns a localized unit name of this field, using the given value as an
     * aid. For example, the unit name may differ if it is plural.
     *
     * @param value the duration value to use for selecting a unit name
     * @param locale the locale to use for selecting a name, null for default
     */
    //String getUnitName(long value, Locale locale);

    /**
     * Returns a localized unit name of this field, using the given value as an
     * aid. For example, the unit name may differ if it is plural.
     *
     * @param value the duration value to use for selecting a unit name
     */
    //String getUnitName(long value);

    /**
     * Get the maximum length string returned by getUnitName.
     * 
     * @param locale the locale to use for selecting a unit name, null for
     * default
     * @return the maximum name length
     */
    //int getMaximumUnitNameLength(Locale locale);

    //------------------------------------------------------------------------
    
Get a suitable debug string.
Returns:
debug string/**
     * Get a suitable debug string.
     * 
     * @return debug string
     */
    public abstract String toString();
    
}