javax.time.calendar
Enum QuarterOfYear

java.lang.Object
  extended by java.lang.Enum<QuarterOfYear>
      extended by javax.time.calendar.QuarterOfYear
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<QuarterOfYear>, Calendrical, CalendricalMatcher

public enum QuarterOfYear
extends java.lang.Enum<QuarterOfYear>
implements Calendrical, CalendricalMatcher

A quarter-of-year, such as 'Q2'.

QuarterOfYear is an enum representing the 4 quarters of the year - Q1, Q2, Q3 and Q4. These are defined as January to March, April to June, July to September and October to December.

The calendrical framework requires date-time fields to have an int value. The int value follows the quarter, from 1 (Q1) to 4 (Q4). It is recommended that applications use the enum rather than the int value to ensure code clarity.

Do not use ordinal() to obtain the numeric representation of QuarterOfYear. Use getValue() instead.

This enum represents a common concept that is found in many calendar systems. As such, this enum may be used by any calendar system that has the quarter-of-year concept defined exactly equivalent to the ISO calendar system.

This is an immutable and thread-safe enum.

Author:
Michael Nascimento Santos, Stephen Colebourne

Enum Constant Summary
Q1
          The singleton instance for the first quarter-of-year, from January to March.
Q2
          The singleton instance for the second quarter-of-year, from April to June.
Q3
          The singleton instance for the third quarter-of-year, from July to September.
Q4
          The singleton instance for the fourth quarter-of-year, from October to December.
 
Method Summary
static QuarterOfYear from(Calendrical... calendricals)
          Obtains an instance of QuarterOfYear from a set of calendricals.
<T> T
get(CalendricalRule<T> ruleToDerive)
          Gets the value of the specified calendrical rule.
 MonthOfYear getFirstMonthOfQuarter()
          Gets the first of the three months that this quarter refers to.
 java.lang.String getText(TextStyle style, java.util.Locale locale)
          Gets the textual representation, such as 'Q1' or '4th quarter'.
 int getValue()
          Gets the quarter-of-year int value.
 boolean matchesCalendrical(Calendrical calendrical)
          Checks if the quarter-of-year extracted from the calendrical matches this.
 QuarterOfYear next()
          Gets the next quarter-of-year.
static QuarterOfYear of(int quarterOfYear)
          Obtains an instance of QuarterOfYear from an int value.
 QuarterOfYear previous()
          Gets the previous quarter-of-year.
 QuarterOfYear roll(int quarters)
          Rolls the quarter-of-year, adding the specified number of quarters.
static CalendricalRule<QuarterOfYear> rule()
          Gets the rule for QuarterOfYear.
 DateTimeField toField()
          Converts this quarter-of-year to an equivalent field.
static QuarterOfYear valueOf(java.lang.String name)
          Returns the enum constant of this type with the specified name.
static QuarterOfYear[] values()
          Returns an array containing the constants of this enum type, in the order they are declared.
 
Methods inherited from class java.lang.Enum
clone, compareTo, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Enum Constant Detail

Q1

public static final QuarterOfYear Q1
The singleton instance for the first quarter-of-year, from January to March. This has the numeric value of 1.


Q2

public static final QuarterOfYear Q2
The singleton instance for the second quarter-of-year, from April to June. This has the numeric value of 2.


Q3

public static final QuarterOfYear Q3
The singleton instance for the third quarter-of-year, from July to September. This has the numeric value of 3.


Q4

public static final QuarterOfYear Q4
The singleton instance for the fourth quarter-of-year, from October to December. This has the numeric value of 4.

Method Detail

values

public static QuarterOfYear[] 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 (QuarterOfYear c : QuarterOfYear.values())
    System.out.println(c);

Returns:
an array containing the constants of this enum type, in the order they are declared

valueOf

public static QuarterOfYear valueOf(java.lang.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:
java.lang.IllegalArgumentException - if this enum type has no constant with the specified name
java.lang.NullPointerException - if the argument is null

rule

public static CalendricalRule<QuarterOfYear> rule()
Gets the rule for QuarterOfYear.

This rule is a calendrical rule based on QuarterOfYear. The equivalent date-time rule is ISODateTimeRule.QUARTER_OF_YEAR.

Returns:
the rule for the quarter-of-year, not null

of

public static QuarterOfYear of(int quarterOfYear)
Obtains an instance of QuarterOfYear from an int value.

QuarterOfYear is an enum representing the 4 quarters of the year. This factory allows the enum to be obtained from the int value. The int value follows the quarter, from 1 (Q1) to 4 (Q4).

An exception is thrown if the value is invalid. The exception uses the ISOChronology quarter-of-year rule to indicate the failed rule.

Parameters:
quarterOfYear - the quarter-of-year to represent, from 1 (Q1) to 4 (Q4)
Returns:
the QuarterOfYear singleton, not null
Throws:
IllegalCalendarFieldValueException - if the quarter-of-year is invalid

from

public static QuarterOfYear from(Calendrical... calendricals)
Obtains an instance of QuarterOfYear from a set of calendricals.

A calendrical represents some form of date and time information. This method combines the input calendricals into a quarter-of-year.

Parameters:
calendricals - the calendricals to create a quarter-of-year from, no nulls, not null
Returns:
the quarter-of-year, not null
Throws:
CalendricalException - if unable to merge to a quarter-of-year

get

public <T> T get(CalendricalRule<T> ruleToDerive)
Gets the value of the specified calendrical rule.

This will only return a value for the ISODateTimeRule.QUARTER_OF_YEAR rule, or something derivable from it.

Specified by:
get in interface Calendrical
Parameters:
ruleToDerive - the rule to derive, not null
Returns:
the value for the rule, null if the value cannot be returned

getValue

public int getValue()
Gets the quarter-of-year int value.

The values are numbered following the ISO-8601 standard, from 1 (Q1) to 4 (Q4).

Returns:
the quarter-of-year, from 1 (Q1) to 4 (Q4)

getText

public java.lang.String getText(TextStyle style,
                                java.util.Locale locale)
Gets the textual representation, such as 'Q1' or '4th quarter'.

This method is notionally specific to ISOChronology as it uses the quarter-of-year rule to obtain the text. However, it is expected that the text will be equivalent for all quarter-of-year rules, thus this aspect of the implementation should be irrelevant to applications.

If no textual mapping is found then the numeric value is returned.

Parameters:
locale - the locale to use, not null
Returns:
the short text value of the month-of-year, not null

next

public QuarterOfYear next()
Gets the next quarter-of-year.

This calculates based on the time-line, thus it rolls around the end of the week. The next quarter after Q4 is Q1.

Returns:
the next quarter-of-year, not null

previous

public QuarterOfYear previous()
Gets the previous quarter-of-year.

This calculates based on the time-line, thus it rolls around the end of the year. The previous quarter before Q1 is Q4.

Returns:
the previous quarter-of-year, not null

roll

public QuarterOfYear roll(int quarters)
Rolls the quarter-of-year, adding the specified number of quarters.

This calculates based on the time-line, thus it rolls around the end of the year from Q4 to Q1. The quarters to roll by may be negative.

This instance is immutable and unaffected by this method call.

Parameters:
quarters - the quarters to roll by, positive or negative
Returns:
the resulting quarter-of-year, not null

getFirstMonthOfQuarter

public MonthOfYear getFirstMonthOfQuarter()
Gets the first of the three months that this quarter refers to.

Q1 will return January.
Q2 will return April.
Q3 will return July.
Q4 will return October.

To obtain the other two months of the quarter, simply use MonthOfYear.next() on the returned month.

Returns:
the first month in the quarter, not null

matchesCalendrical

public boolean matchesCalendrical(Calendrical calendrical)
Checks if the quarter-of-year extracted from the calendrical matches this.

This method implements the CalendricalMatcher interface. It is intended that applications use LocalDate.matches(javax.time.calendar.CalendricalMatcher) rather than this method.

Specified by:
matchesCalendrical in interface CalendricalMatcher
Parameters:
calendrical - the calendrical to match, not null
Returns:
true if the calendrical matches, false otherwise

toField

public DateTimeField toField()
Converts this quarter-of-year to an equivalent field.

The field is based on ISODateTimeRule.QUARTER_OF_YEAR.

Returns:
the equivalent quarter-of-year field, not null