Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   *  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.goda.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(s):
Stephen Colebourne
Brian S O'Neill
Since:
1.0
 
 public abstract class DurationField extends Field implements Comparable {

    
Get the type of the field.

Returns:
field type
 
     public abstract DurationFieldType getType();

    
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.

Returns:
true if precise
See also:
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.

Returns:
the unit size of this field, in milliseconds
See also:
isPrecise()
 
     public abstract long getUnitMillis();
 
     //------------------------------------------------------------------------
     
Get the value of this field from the milliseconds, which is approximate if this field is imprecise.

Parameters:
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
Throws:
java.lang.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.

Parameters:
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
 
     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".

Parameters:
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
Throws:
java.lang.ArithmeticException if the value is too large for an int
 
     public abstract int getValue(long durationlong 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".

Parameters:
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
    public abstract long getValueAsLong(long durationlong instant);
    //------------------------------------------------------------------------
    
Get the millisecond duration of this field from its value, which is approximate if this field is imprecise.

Parameters:
value the value of the field, which may be negative
Returns:
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.

Parameters:
value the value of the field, which may be negative
Returns:
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".

Parameters:
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
    public abstract long getMillis(int valuelong 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".

Parameters:
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
    public abstract long getMillis(long valuelong instant);

    
Adds a duration value (which may be negative) to the instant.

Parameters:
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
    public abstract long add(long instantint value);

    
Adds a duration value (which may be negative) to the instant.

Parameters:
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
    public abstract long add(long instantlong value);

    
Subtracts a duration value (which may be negative) from the instant.

Parameters:
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
    public long subtract(long instantint value) {
        if (value == .) {
            return subtract(instant, (longvalue);
        }
        return add(instant, -value);
    }

    
Subtracts a duration value (which may be negative) from the instant.

Parameters:
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
    public long subtract(long instantlong value) {
        if (value == .) {
            throw new ArithmeticException("Long.MIN_VALUE cannot be negated");
        }
        return add(instant, -value);
    }

    
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.

Parameters:
durationField a duration field to check against
Returns:
negative value if this is less, 0 if equal, or positive value if greater
Throws:
java.lang.NullPointerException if the object is null
java.lang.ClassCastException if the object type is not supported
    public abstract int compareTo(Object 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.

Parameters:
value the duration value to use for selecting a unit name
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.

Parameters:
value the duration value to use for selecting a unit name
    //String getUnitName(long value);

    
Get the maximum length string returned by getUnitName.

Parameters:
locale the locale to use for selecting a unit name, null for default
Returns:
the maximum name length
    //int getMaximumUnitNameLength(Locale locale);
    //------------------------------------------------------------------------
    
Get a suitable debug string.

Returns:
debug string
    public abstract String toString();
    
New to GrepCode? Check out our FAQ X