Class Frequency

• All Implemented Interfaces:
Serializable, TemporalAmount

public final class Frequency
extends Object
implements TemporalAmount, Serializable
A periodic frequency used by financial products that have a specific event every so often.

Frequency is primarily intended to be used to subdivide events within a year.

A frequency is allowed to be any non-negative period of days, weeks, month or years. This class provides constants for common frequencies which are best used by static import.

A special value, 'Term', is provided for when there are no subdivisions of the entire term. This is also know as 'zero-coupon' or 'once'. It is represented using the period 10,000 years, which allows addition/subtraction to work, producing a date after the end of the term.

Each frequency is based on a Period. The months and years of the period are not normalized, thus it is possible to have a frequency of 12 months and a different one of 1 year. When used, standard date addition rules apply, thus there is no difference between them. Call normalized() to apply normalization.

The periodic frequency is often expressed as a number of events per year. The eventsPerYear() method can be used to obtain this for common frequencies.

Usage

Frequency implements TemporalAmount allowing it to be directly added to a date:
  LocalDate later = baseDate.plus(frequency);

See Also:
Serialized Form
• Field Summary

Fields
Modifier and Type Field Description
static Frequency P12M
A periodic frequency of 12 months (1 year).
static Frequency P13W
A periodic frequency of 13 weeks (91 days).
static Frequency P1D
A periodic frequency of one day.
static Frequency P1M
A periodic frequency of 1 month.
static Frequency P1W
A periodic frequency of 1 week (7 days).
static Frequency P26W
A periodic frequency of 26 weeks (182 days).
static Frequency P2M
A periodic frequency of 2 months.
static Frequency P2W
A periodic frequency of 2 weeks (14 days).
static Frequency P3M
A periodic frequency of 3 months.
static Frequency P4M
A periodic frequency of 4 months.
static Frequency P4W
A periodic frequency of 4 weeks (28 days).
static Frequency P52W
A periodic frequency of 52 weeks (364 days).
static Frequency P6M
A periodic frequency of 6 months.
static Frequency TERM
A periodic frequency matching the term.
• Method Summary

All Methods
Modifier and Type Method Description
Temporal addTo​(Temporal temporal)
Adds the period of this frequency to the specified date.
boolean equals​(Object obj)
Checks if this periodic frequency equals another periodic frequency.
int eventsPerYear()
Calculates the number of events that occur in a year.
double eventsPerYearEstimate()
Estimates the number of events that occur in a year.
int exactDivide​(Frequency other)
Exactly divides this frequency by another.
long get​(TemporalUnit unit)
Gets the value of the specified unit.
Period getPeriod()
Gets the underlying period of the frequency.
List<TemporalUnit> getUnits()
Gets the unit of this periodic frequency.
int hashCode()
Returns a suitable hash code for the periodic frequency.
boolean isAnnual()
Checks if the periodic frequency is annual.
boolean isMonthBased()
Checks if the periodic frequency is month-based.
boolean isTerm()
Checks if the periodic frequency is the 'Term' instance.
boolean isWeekBased()
Checks if the periodic frequency is week-based.
Frequency normalized()
Normalizes the months and years of this tenor.
static Frequency of​(Period period)
Obtains an instance from a Period.
static Frequency ofDays​(int days)
Obtains an instance backed by a period of days.
static Frequency ofMonths​(int months)
Obtains an instance backed by a period of months.
static Frequency ofWeeks​(int weeks)
Obtains an instance backed by a period of weeks.
static Frequency ofYears​(int years)
Obtains an instance backed by a period of years.
static Frequency parse​(String toParse)
Parses a formatted string representing the frequency.
Temporal subtractFrom​(Temporal temporal)
Subtracts the period of this frequency from the specified date.
String toString()
Returns a formatted string representing the periodic frequency.
• Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait
• Field Detail

• P1D

public static final Frequency P1D
A periodic frequency of one day. Also known as daily. There are considered to be 364 events per year with this frequency.
• P1W

public static final Frequency P1W
A periodic frequency of 1 week (7 days). Also known as weekly. There are considered to be 52 events per year with this frequency.
• P2W

public static final Frequency P2W
A periodic frequency of 2 weeks (14 days). Also known as bi-weekly. There are considered to be 26 events per year with this frequency.
• P4W

public static final Frequency P4W
A periodic frequency of 4 weeks (28 days). Also known as lunar. There are considered to be 13 events per year with this frequency.
• P13W

public static final Frequency P13W
A periodic frequency of 13 weeks (91 days). There are considered to be 4 events per year with this frequency.
• P26W

public static final Frequency P26W
A periodic frequency of 26 weeks (182 days). There are considered to be 2 events per year with this frequency.
• P52W

public static final Frequency P52W
A periodic frequency of 52 weeks (364 days). There is considered to be 1 event per year with this frequency.
• P1M

public static final Frequency P1M
A periodic frequency of 1 month. Also known as monthly. There are 12 events per year with this frequency.
• P2M

public static final Frequency P2M
A periodic frequency of 2 months. Also known as bi-monthly. There are 6 events per year with this frequency.
• P3M

public static final Frequency P3M
A periodic frequency of 3 months. Also known as quarterly. There are 4 events per year with this frequency.
• P4M

public static final Frequency P4M
A periodic frequency of 4 months. There are 3 events per year with this frequency.
• P6M

public static final Frequency P6M
A periodic frequency of 6 months. Also known as semi-annual. There are 2 events per year with this frequency.
• P12M

public static final Frequency P12M
A periodic frequency of 12 months (1 year). Also known as annual. There is 1 event per year with this frequency.
• TERM

public static final Frequency TERM
A periodic frequency matching the term. Also known as zero-coupon. This is represented using the period 10,000 years. There are no events per year with this frequency.
• Method Detail

• of

public static Frequency of​(Period period)
Obtains an instance from a Period.

The period normally consists of either days and weeks, or months and years. It must also be positive and non-zero.

If the number of days is an exact multiple of 7 it will be converted to weeks. Months are not normalized into years.

The maximum tenor length is 1,000 years.

Parameters:
period - the period to convert to a periodic frequency
Returns:
the periodic frequency
Throws:
IllegalArgumentException - if the period is negative, zero or too large
• ofDays

public static Frequency ofDays​(int days)
Obtains an instance backed by a period of days.

If the number of days is an exact multiple of 7 it will be converted to weeks.

Parameters:
days - the number of days
Returns:
the periodic frequency
Throws:
IllegalArgumentException - if days is negative or zero
• ofWeeks

public static Frequency ofWeeks​(int weeks)
Obtains an instance backed by a period of weeks.
Parameters:
weeks - the number of weeks
Returns:
the periodic frequency
Throws:
IllegalArgumentException - if weeks is negative or zero
• ofMonths

public static Frequency ofMonths​(int months)
Obtains an instance backed by a period of months.

Months are not normalized into years.

Parameters:
months - the number of months
Returns:
the periodic frequency
Throws:
IllegalArgumentException - if months is negative, zero or over 12,000
• ofYears

public static Frequency ofYears​(int years)
Obtains an instance backed by a period of years.
Parameters:
years - the number of years
Returns:
the periodic frequency
Throws:
IllegalArgumentException - if years is negative, zero or over 1,000
• parse

public static Frequency parse​(String toParse)
Parses a formatted string representing the frequency.

The format can either be based on ISO-8601, such as 'P3M' or without the 'P' prefix e.g. '2W'.

The period must be positive and non-zero.

Parameters:
toParse - the string representing the frequency
Returns:
the frequency
Throws:
IllegalArgumentException - if the frequency cannot be parsed
• getPeriod

public Period getPeriod()
Gets the underlying period of the frequency.
Returns:
the period
• isTerm

public boolean isTerm()
Checks if the periodic frequency is the 'Term' instance.

The term instance corresponds to there being no subdivisions of the entire term.

Returns:
true if this is the 'Term' instance
• normalized

public Frequency normalized()
Normalizes the months and years of this tenor.

This method returns a tenor of an equivalent length but with any number of months greater than 12 normalized into a combination of months and years.

Returns:
the normalized tenor
• isWeekBased

public boolean isWeekBased()
Checks if the periodic frequency is week-based.

A week-based frequency consists of an integral number of weeks. There must be no day, month or year element.

Returns:
true if this is week-based
• isMonthBased

public boolean isMonthBased()
Checks if the periodic frequency is month-based.

A month-based frequency consists of an integral number of months. Any year-based frequency is also counted as month-based. There must be no day or week element.

Returns:
true if this is month-based
• isAnnual

public boolean isAnnual()
Checks if the periodic frequency is annual.

An annual frequency consists of 12 months. There must be no day or week element.

Returns:
true if this is annual
• eventsPerYear

public int eventsPerYear()
Calculates the number of events that occur in a year.

The number of events per year is the number of times that the period occurs per year. Not all periodic frequency instances can be converted to an integer events per year. All constants declared on this class will return a result.

Month-based and year-based periodic frequencies are converted by dividing 12 by the number of months. Only the following periodic frequencies return a value - P1M, P2M, P3M, P4M, P6M, P1Y.

Day-based and week-based periodic frequencies are converted by dividing 364 by the number of days. Only the following periodic frequencies return a value - P1D, P2D, P4D, P1W, P2W, P4W, P13W, P26W, P52W.

The 'Term' periodic frequency returns zero.

Returns:
the number of events per year
Throws:
IllegalArgumentException - if unable to calculate the number of events per year
• eventsPerYearEstimate

public double eventsPerYearEstimate()
Estimates the number of events that occur in a year.

The number of events per year is the number of times that the period occurs per year. This method returns an estimate without throwing an exception. The exact number of events is returned by eventsPerYear().

The 'Term' periodic frequency returns zero. Month-based and year-based periodic frequencies return 12 divided by the number of months. Day-based and week-based periodic frequencies return 364 divided by the number of days. Other frequencies are calculated using estimated durations, dividing the year by the period.

Returns:
the estimated number of events per year
• exactDivide

public int exactDivide​(Frequency other)
Exactly divides this frequency by another.

This calculates the integer division of this frequency by the specified frequency. If the result is not an integer, an exception is thrown.

Month-based and year-based periodic frequencies are calculated by dividing the total number of months. For example, P6M divided by P3M results in 2, and P2Y divided by P6M returns 4.

Day-based and week-based periodic frequencies are calculated by dividing the total number of days. For example, P26W divided by P13W results in 2, and P2W divided by P1D returns 14.

The 'Term' frequency throws an exception.

Parameters:
other - the other frequency to divide into this one
Returns:
this frequency divided by the other frequency
Throws:
IllegalArgumentException - if the frequency does not exactly divide into this one
• get

public long get​(TemporalUnit unit)
Gets the value of the specified unit.

This will return a value for the years, months and days units. Note that weeks are not included. All other units throw an exception.

The 'Term' period is returned as a period of 10,000 years.

This method implements TemporalAmount. It is not intended to be called directly.

Specified by:
get in interface TemporalAmount
Parameters:
unit - the unit to query
Returns:
the value of the unit
Throws:
UnsupportedTemporalTypeException - if the unit is not supported
• getUnits

public List<TemporalUnit> getUnits()
Gets the unit of this periodic frequency.

This returns a list containing years, months and days. Note that weeks are not included.

The 'Term' period is returned as a period of 10,000 years.

This method implements TemporalAmount. It is not intended to be called directly.

Specified by:
getUnits in interface TemporalAmount
Returns:
a list containing the years, months and days units
• addTo

public Temporal addTo​(Temporal temporal)
Adds the period of this frequency to the specified date.

This method implements TemporalAmount. It is not intended to be called directly. Use LocalDate.plus(TemporalAmount) instead.

Specified by:
addTo in interface TemporalAmount
Parameters:
temporal - the temporal object to add to
Returns:
the result with this frequency added
Throws:
DateTimeException - if unable to add
ArithmeticException - if numeric overflow occurs
• subtractFrom

public Temporal subtractFrom​(Temporal temporal)
Subtracts the period of this frequency from the specified date.

This method implements TemporalAmount. It is not intended to be called directly. Use LocalDate.minus(TemporalAmount) instead.

Specified by:
subtractFrom in interface TemporalAmount
Parameters:
temporal - the temporal object to subtract from
Returns:
the result with this frequency subtracted
Throws:
DateTimeException - if unable to subtract
ArithmeticException - if numeric overflow occurs
• equals

public boolean equals​(Object obj)
Checks if this periodic frequency equals another periodic frequency.

The comparison checks the frequency period.

Overrides:
equals in class Object
Parameters:
obj - the other frequency, null returns false
Returns:
true if equal
• hashCode

public int hashCode()
Returns a suitable hash code for the periodic frequency.
Overrides:
hashCode in class Object
Returns:
the hash code
• toString

public String toString()
Returns a formatted string representing the periodic frequency.

The format is a combination of the quantity and unit, such as P1D, P2W, P3M, P4Y. The 'Term' amount is returned as 'Term'.

Overrides:
toString in class Object
Returns:
the formatted frequency