Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.joda.time
Class Years

    java.lang.Object
      org.joda.time.base.BaseSingleFieldPeriod
          org.joda.time.Years

All Implemented Interfaces:
  java.io.Serializable, java.lang.Comparable, ReadablePeriod

    public final class Years

extends BaseSingleFieldPeriod

An immutable time period representing a number of years.

`Years` is an immutable period that can only store years. It does not store years, days or hours for example. As such it is a type-safe way of representing a number of years in an application.

The number of years is set in the constructor, and may be queried using `getYears()`. Basic mathematical operations are provided - `plus()`, `minus()`, `multipliedBy()` and `dividedBy()`.

`Years` is thread-safe and immutable.

Since:
  1.4
Author:
  Stephen Colebourne
See Also:
  Serialized Form

Field Summary
`static Years` | `MAX_VALUE` Constant representing the maximum nuber of years that can be stored in this object.
`static Years` | `MIN_VALUE` Constant representing the minimum nuber of years that can be stored in this object.
`static Years` | `ONE` Constant representing one day.
`static Years` | `THREE` Constant representing three years.
`static Years` | `TWO` Constant representing two years.
`static Years` | `ZERO` Constant representing zero years.

Method Summary
`Years` | `dividedBy(int divisor)` Returns a new instance with the years divided by the specified divisor.
`DurationFieldType` | `getFieldType()` Gets the duration field type, which is `years`.
`PeriodType` | `getPeriodType()` Gets the period type, which is `years`.
`int` | `getYears()` Gets the number of years that this period represents.
`boolean` | `isGreaterThan(Years other)` Is this years instance greater than the specified number of years.
`boolean` | `isLessThan(Years other)` Is this years instance less than the specified number of years.
`Years` | `minus(int years)` Returns a new instance with the specified number of years taken away.
`Years` | `minus(Years years)` Returns a new instance with the specified number of years taken away.
`Years` | `multipliedBy(int scalar)` Returns a new instance with the years multiplied by the specified scalar.
`Years` | `negated()` Returns a new instance with the years value negated.
`static Years` | `parseYears(java.lang.String periodStr)` Creates a new `Years` by parsing a string in the ISO8601 format 'PnY'.
`Years` | `plus(int years)` Returns a new instance with the specified number of years added.
`Years` | `plus(Years years)` Returns a new instance with the specified number of years added.
`java.lang.String` | `toString()` Gets this instance as a String in the ISO8601 duration format.
`static Years` | `years(int years)` Obtains an instance of `Years` that may be cached.
`static Years` | `yearsBetween(ReadableInstant start, ReadableInstant end)` Creates a `Years` representing the number of whole years between the two specified datetimes.
`static Years` | `yearsBetween(ReadablePartial start, ReadablePartial end)` Creates a `Years` representing the number of whole years between the two specified partial datetimes.
`static Years` | `yearsIn(ReadableInterval interval)` Creates a `Years` representing the number of whole years in the specified interval.

Methods inherited from class org.joda.time.base.BaseSingleFieldPeriod
`between, between, compareTo, equals, get, getFieldType, getValue, getValue, hashCode, isSupported, setValue, size, standardPeriodIn, toMutablePeriod, toPeriod`

Methods inherited from class java.lang.Object
`clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

Field Detail

### ZERO

    public static final Years ZERO

  Constant representing zero years.

### ONE

    public static final Years ONE

  Constant representing one day.

### TWO

    public static final Years TWO

  Constant representing two years.

### THREE

    public static final Years THREE

  Constant representing three years.

### MAX_VALUE

    public static final Years MAX_VALUE

  Constant representing the maximum nuber of years that can be stored in this object.

### MIN_VALUE

    public static final Years MIN_VALUE

  Constant representing the minimum nuber of years that can be stored in this object.

Method Detail

### years

    public static Years years(int years)

  Obtains an instance of `Years` that may be cached. `Years` is immutable, so instances can be cached and shared. This factory method provides access to shared instances.

  Parameters:
    `years` - the number of years to obtain an instance for
  Returns:
    the instance of Years

### yearsBetween

    public static Years yearsBetween(ReadableInstant start,
                                     ReadableInstant end)

  Creates a `Years` representing the number of whole years between the two specified datetimes. This method corectly handles any daylight savings time changes that may occur during the interval.

  Parameters:
    `start` - the start instant, must not be null
    `end` - the end instant, must not be null
  Returns:
    the period in years
  Throws:
    `java.lang.IllegalArgumentException` - if the instants are null or invalid

### yearsBetween

    public static Years yearsBetween(ReadablePartial start,
                                     ReadablePartial end)

  Creates a `Years` representing the number of whole years between the two specified partial datetimes.

  The two partials must contain the same fields, for example you can specify two `LocalDate` objects.

  Parameters:
    `start` - the start partial date, must not be null
    `end` - the end partial date, must not be null
  Returns:
    the period in years
  Throws:
    `java.lang.IllegalArgumentException` - if the partials are null or invalid

### yearsIn

    public static Years yearsIn(ReadableInterval interval)

  Creates a `Years` representing the number of whole years in the specified interval. This method corectly handles any daylight savings time changes that may occur during the interval.

  Parameters:
    `interval` - the interval to extract years from, null returns zero
  Returns:
    the period in years
  Throws:
    `java.lang.IllegalArgumentException` - if the partials are null or invalid

### parseYears

    public static Years parseYears(java.lang.String periodStr)

  Creates a new `Years` by parsing a string in the ISO8601 format 'PnY'.

  The parse will accept the full ISO syntax of PnYnMnWnDTnHnMnS however only the years component may be non-zero. If any other component is non-zero, an exception will be thrown.

  Parameters:
    `periodStr` - the period string, null returns zero
  Returns:
    the period in years
  Throws:
    `java.lang.IllegalArgumentException` - if the string format is invalid

### getFieldType

    public DurationFieldType getFieldType()

  Gets the duration field type, which is `years`.

  Specified by:
    `getFieldType` in class `BaseSingleFieldPeriod`
  Returns:
    the period type

### getPeriodType

    public PeriodType getPeriodType()

  Gets the period type, which is `years`.

  Specified by:
    `getPeriodType` in interface `ReadablePeriod`
  Specified by:
    `getPeriodType` in class `BaseSingleFieldPeriod`
  Returns:
    the period type

### getYears

    public int getYears()

  Gets the number of years that this period represents.

  Returns:
    the number of years in the period

### plus

    public Years plus(int years)

  Returns a new instance with the specified number of years added.

  This instance is immutable and unaffected by this method call.

  Parameters:
    `years` - the amount of years to add, may be negative
  Returns:
    the new period plus the specified number of years
  Throws:
    `java.lang.ArithmeticException` - if the result overflows an int

### plus

    public Years plus(Years years)

  Returns a new instance with the specified number of years added.

  This instance is immutable and unaffected by this method call.

  Parameters:
    `years` - the amount of years to add, may be negative, null means zero
  Returns:
    the new period plus the specified number of years
  Throws:
    `java.lang.ArithmeticException` - if the result overflows an int

### minus

    public Years minus(int years)

  Returns a new instance with the specified number of years taken away.

  This instance is immutable and unaffected by this method call.

  Parameters:
    `years` - the amount of years to take away, may be negative
  Returns:
    the new period minus the specified number of years
  Throws:
    `java.lang.ArithmeticException` - if the result overflows an int

### minus

    public Years minus(Years years)

  Returns a new instance with the specified number of years taken away.

  This instance is immutable and unaffected by this method call.

  Parameters:
    `years` - the amount of years to take away, may be negative, null means zero
  Returns:
    the new period minus the specified number of years
  Throws:
    `java.lang.ArithmeticException` - if the result overflows an int

### multipliedBy

    public Years multipliedBy(int scalar)

  Returns a new instance with the years multiplied by the specified scalar.

  This instance is immutable and unaffected by this method call.

  Parameters:
    `scalar` - the amount to multiply by, may be negative
  Returns:
    the new period multiplied by the specified scalar
  Throws:
    `java.lang.ArithmeticException` - if the result overflows an int

### dividedBy

    public Years dividedBy(int divisor)

  Returns a new instance with the years divided by the specified divisor. The calculation uses integer division, thus 3 divided by 2 is 1.

  This instance is immutable and unaffected by this method call.

  Parameters:
    `divisor` - the amount to divide by, may be negative
  Returns:
    the new period divided by the specified divisor
  Throws:
    `java.lang.ArithmeticException` - if the divisor is zero

### negated

    public Years negated()

  Returns a new instance with the years value negated.

  Returns:
    the new period with a negated value
  Throws:
    `java.lang.ArithmeticException` - if the result overflows an int

### isGreaterThan

    public boolean isGreaterThan(Years other)

  Is this years instance greater than the specified number of years.

  Parameters:
    `other` - the other period, null means zero
  Returns:
    true if this years instance is greater than the specified one

### isLessThan

    public boolean isLessThan(Years other)

  Is this years instance less than the specified number of years.

  Parameters:
    `other` - the other period, null means zero
  Returns:
    true if this years instance is less than the specified one

### toString

    public java.lang.String toString()

  Gets this instance as a String in the ISO8601 duration format.

  For example, "P4Y" represents 4 years.

  Specified by:
    `toString` in interface `ReadablePeriod`
  Overrides:
    `toString` in class `java.lang.Object`
  Returns:
    the value as an ISO8601 string

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD