CalendarUnit (Time4J-Core 4.33 API)

java.lang.Object
- java.lang.Enum<CalendarUnit>
- - net.time4j.CalendarUnit

All Implemented Interfaces:

Serializable, Comparable<CalendarUnit>, ChronoUnit, IsoDateUnit, IsoUnit
```
public enum CalendarUnit
extends Enum<CalendarUnit>
implements IsoDateUnit
```
Represents the most common time units related to a standard ISO-8601-calendar.

Default behaviour of addition or subtraction of month-related units:

If the addition of months results in an invalid intermediate date then the final date will be just the last valid date that is the last day of current month. Example:
```
  PlainDate date = PlainDate.of(2013, 1, 31);
  System.out.println(date.plus(1, MONTHS));
  // Output: 2013-02-28
 
```
Author:

Meno Hochschild

Enum Constant Summary

Enum Constants
Enum Constant and Description
`CENTURIES` Time unit "centuries" (symbol C)
`DAYS` Time unit "days" (symbol D)
`DECADES` Time unit "decades" (symbol E)
`MILLENNIA` Time unit "millennia" (symbol I)
`MONTHS` Time unit "months" (symbol M)
`QUARTERS` Time unit "quarter years" (symbol Q)
`WEEKS` Time unit "weeks" (symbol W)
`YEARS` Time unit "calendar years" (symbol Y)

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`IsoDateUnit`	`atEndOfMonth()` Defines a variation of this unit which always sets the resulting date in additions and subtractions to the end of month even if there is no day overflow.
`<T extends TimePoint<? super CalendarUnit,T>> long`	`between(T start, T end)` Calculates the temporal distance between given calendar dates in this calendar unit.
`boolean`	`isCalendrical()` A calendar unit is always calendrical.
`IsoDateUnit`	`keepingEndOfMonth()` Defines a variation of this unit which sets the resulting date in additions and subtractions to the end of month if and only if the original date is the last day of month.
`IsoDateUnit`	`nextValidDate()` Defines a variation of this unit which resolves invalid intermediate dates in additions and subtractions to the first valid date after (the first day of following month).
`IsoDateUnit`	`unlessInvalid()` Defines a variation of this unit which handles invalid intermediate dates in additions and subtractions by throwing a `ChronoException`.
`static CalendarUnit`	`valueOf(String name)` Returns the enum constant of this type with the specified name.
`static CalendarUnit[]`	`values()` Returns an array containing the constants of this enum type, in the order they are declared.
`static IsoDateUnit`	`weekBasedYears()` Defines a special calendar unit for week-based years which are not bound to the calendar year but to the week cycle of a year preserving the day of week and (if possible) the week of year.
`IsoDateUnit`	`withCarryOver()` Defines a variation of this unit which resolves invalid intermediate dates in additions and subtractions by transferring any day overflow to the following month.
`IsoDateUnit`	`withJodaMetric()` Defines a variation of this unit which simulates the behaviour of Joda-Time.

Methods inherited from class java.lang.Enum
compareTo, equals, getDeclaringClass, hashCode, name, ordinal, toString, valueOf

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

Methods inherited from interface net.time4j.IsoUnit
getSymbol

Methods inherited from interface net.time4j.engine.ChronoUnit
getLength

- Enum Constant Detail
  - MILLENNIA
```
public static final CalendarUnit MILLENNIA
```
    Time unit "millennia" (symbol I)
  - CENTURIES
```
public static final CalendarUnit CENTURIES
```
    Time unit "centuries" (symbol C)
  - DECADES
```
public static final CalendarUnit DECADES
```
    Time unit "decades" (symbol E)
  - YEARS
```
public static final CalendarUnit YEARS
```
    Time unit "calendar years" (symbol Y)
  - QUARTERS
```
public static final CalendarUnit QUARTERS
```
    Time unit "quarter years" (symbol Q)
  - MONTHS
```
public static final CalendarUnit MONTHS
```
    Time unit "months" (symbol M)
  - WEEKS
```
public static final CalendarUnit WEEKS
```
    Time unit "weeks" (symbol W)
  - DAYS
```
public static final CalendarUnit DAYS
```
    Time unit "days" (symbol D)
- Method Detail
  - values
```
public static CalendarUnit[] values()
```
    Returns an array containing the constants of this enum type, in the order they are declared. This method may be used to iterate over the constants as follows:
```
for (CalendarUnit c : CalendarUnit.values())
    System.out.println(c);
```
    Returns:
    
    an array containing the constants of this enum type, in the order they are declared
  - valueOf
```
public static CalendarUnit valueOf(String name)
```
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
    
    Parameters:
    
    name - the name of the enum constant to be returned.
    
    Returns:
    
    the enum constant with the specified name
    
    Throws:
    
    IllegalArgumentException - if this enum type has no constant with the specified name
    
    NullPointerException - if the argument is null
  - between
```
public <T extends TimePoint<? super CalendarUnit,T>> long between(T start,
                                                                  T end)
```
    Calculates the temporal distance between given calendar dates in this calendar unit.
    
    Type Parameters:
    
    T - generic type of calendar date
    
    Parameters:
    
    start - starting date
    
    end - ending date
    
    Returns:
    
    duration as count of this unit
  - isCalendrical
```
public boolean isCalendrical()
```
    A calendar unit is always calendrical.
    
    Specified by:
    
    isCalendrical in interface ChronoUnit
    
    Returns:
    
    true
  - nextValidDate
```
public IsoDateUnit nextValidDate()
```
    Defines a variation of this unit which resolves invalid intermediate dates in additions and subtractions to the first valid date after (the first day of following month).
    
    Example for months:
```
  PlainDate date = PlainDate.of(2013, 1, 31);
  System.out.println(date.plus(1, MONTHS.nextValidDate()));
  // Output: 2013-03-01
 
```
    Note: The metric for calculation of temporal distances remains unaffected.
    Returns:
    
    calendar unit with modified addition behaviour if month-based, but still the same metric
  - withCarryOver
```
public IsoDateUnit withCarryOver()
```
    Defines a variation of this unit which resolves invalid intermediate dates in additions and subtractions by transferring any day overflow to the following month.
    
    Example for months:
```
  PlainDate date = PlainDate.of(2013, 1, 31);
  System.out.println(date.plus(1, MONTHS.withCarryOver()));
  // Output: 2013-03-03
 
```
    Note: The metric for calculation of temporal distances remains unaffected.
    Returns:
    
    calendar unit with modified addition behaviour if month-based, but still the same metric
  - unlessInvalid
```
public IsoDateUnit unlessInvalid()
```
    Defines a variation of this unit which handles invalid intermediate dates in additions and subtractions by throwing a ChronoException.
    
    Example for months:
```
  PlainDate date = PlainDate.of(2013, 1, 31);
  System.out.println(date.plus(1, MONTHS.unlessInvalid()));
  // February 31th does not exist => throws ChronoException
 
```
    Note: The metric for calculation of temporal distances remains unaffected.
    Returns:
    
    calendar unit with modified addition behaviour if month-based, but still the same metric
  - atEndOfMonth
```
public IsoDateUnit atEndOfMonth()
```
    Defines a variation of this unit which always sets the resulting date in additions and subtractions to the end of month even if there is no day overflow.
    
    Example for months:
```
  PlainDate date1 = PlainDate.of(2013, 2, 27);
  System.out.println(date1.plus(2, MONTHS.atEndOfMonth()));
  // Ausgabe: 2013-04-30
  PlainDate date2 = PlainDate.of(2013, 2, 28);
  System.out.println(date2.plus(2, MONTHS.atEndOfMonth()));
  // Ausgabe: 2013-04-30
 
```
    Note: The metric for calculation of temporal distances has been changed since v3.35/4.30: The day-of-month-criterion will no longer be directly applied but the intermediate result will be adjusted after having done an addition step.
    
    An alternative which only jumps to the end of month if the original date is the last day of month can be achieved by keepingEndOfMonth().
    Returns:
    
    calendar unit with modified addition behaviour and modified metric (if month-based)
    
    Throws:
    
    UnsupportedOperationException - if this unit is day- or week-related
  - keepingEndOfMonth
```
public IsoDateUnit keepingEndOfMonth()
```
    Defines a variation of this unit which sets the resulting date in additions and subtractions to the end of month if and only if the original date is the last day of month.
    
    Example for months:
```
  PlainDate date1 = PlainDate.of(2013, 2, 27);
  System.out.println(date1.plus(2, MONTHS.keepingEndOfMonth()));
  // Ausgabe: 2013-04-27
  PlainDate date2 = PlainDate.of(2013, 2, 28);
  System.out.println(date2.plus(2, MONTHS.keepingEndOfMonth()));
  // Ausgabe: 2013-04-30
 
```
    Note: The metric for calculation of temporal distances has been changed since v3.35/4.30: The day-of-month-criterion will no longer be directly applied but the intermediate result will be adjusted after having done an addition step.
    
    An alternative which unconditionally jumps to the end of month can be achieved by atEndOfMonth().
    Returns:
    
    calendar unit with modified addition behaviour and modified metric if month-based
    
    Throws:
    
    UnsupportedOperationException - if this unit is day- or week-related
    
    Since:
    
    2.3
  - withJodaMetric
```
public IsoDateUnit withJodaMetric()
```
    Defines a variation of this unit which simulates the behaviour of Joda-Time.
    
    Example for years:
```
  PlainDate birthDate = PlainDate.of(1996, 2, 29);
  PlainDate currentDate = PlainDate.of(2014, 2, 28);
  IsoDateUnit jodaUnit = YEARS.withJodaMetric();
  Duration<IsoDateUnit> d = Duration.in(jodaUnit).between(birthDate, currentDate);
  System.out.println(d); // Output: P18{Y-JODA_METRIC}

  assertThat(d.getPartialAmount(jodaUnit), is(18L));
  assertThat(birthDate.plus(18, jodaUnit), is(currentDate));

  assertThat(birthDate.until(currentDate, jodaUnit), is(18L)); // Joda-metric
  assertThat(birthDate.until(currentDate, CalendarUnit.YEARS), is(17L)); // standard metric
 
```
    Note: Users should not use this unit for age calculations.
    Returns:
    
    calendar unit with default addition behaviour but modified metric if month-based
    
    Since:
    
    3.35/4.30
  - weekBasedYears
```
public static IsoDateUnit weekBasedYears()
```
    Defines a special calendar unit for week-based years which are not bound to the calendar year but to the week cycle of a year preserving the day of week and (if possible) the week of year.
    
    Note: If the week of year is originally 53, but there is no such value after addition or subtraction then the week of year will be reduced to value 52.
```
  PlainDate start = PlainDate.of(2000, 2, 29); // 2000-W09-2
  System.out.println(start.plus(14, CalendarUnit.weekBasedYears()));
  // Output: 2014-02-25 (= 2014-W09-2)
 
```
    Returns:
    
    calendar unit for week-based years
    
    See Also:
    
    Weekcycle.YEARS

Enum CalendarUnit

Enum Constant Summary

Method Summary

Methods inherited from class java.lang.Enum

Methods inherited from class java.lang.Object

Methods inherited from interface net.time4j.IsoUnit

Methods inherited from interface net.time4j.engine.ChronoUnit

Enum Constant Detail

MILLENNIA

CENTURIES

DECADES

YEARS

QUARTERS

MONTHS

WEEKS

DAYS

Method Detail

values

valueOf

between

isCalendrical

nextValidDate

withCarryOver

unlessInvalid

atEndOfMonth

keepingEndOfMonth

withJodaMetric

weekBasedYears