net.time4j

Enum CalendarUnit

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

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 CalendarUnit.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 CalendarUnit.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