public final class Frequency extends Object implements TemporalAmount, Serializable
Frequency is primarily intended to be used to subdivide events within a year.
A frequency is allowed to be any nonnegative 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 'zerocoupon' 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.
Frequency
implements TemporalAmount
allowing it to be directly added to a date:
LocalDate later = baseDate.plus(frequency);
Modifier and Type  Field and 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.

Modifier and Type  Method and 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 monthbased.

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

boolean 
isWeekBased()
Checks if the periodic frequency is weekbased.

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.

public static final Frequency P1D
public static final Frequency P1W
public static final Frequency P2W
public static final Frequency P4W
public static final Frequency P13W
public static final Frequency P26W
public static final Frequency P52W
public static final Frequency P1M
public static final Frequency P2M
public static final Frequency P3M
public static final Frequency P4M
public static final Frequency P6M
public static final Frequency P12M
public static final Frequency TERM
public static Frequency of(Period period)
Period
.
The period normally consists of either days and weeks, or months and years. It must also be positive and nonzero.
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.
period
 the period to convert to a periodic frequencyIllegalArgumentException
 if the period is negative, zero or too largepublic static Frequency ofDays(int days)
If the number of days is an exact multiple of 7 it will be converted to weeks.
days
 the number of daysIllegalArgumentException
 if days is negative or zeropublic static Frequency ofWeeks(int weeks)
weeks
 the number of weeksIllegalArgumentException
 if weeks is negative or zeropublic static Frequency ofMonths(int months)
Months are not normalized into years.
months
 the number of monthsIllegalArgumentException
 if months is negative, zero or over 12,000public static Frequency ofYears(int years)
years
 the number of yearsIllegalArgumentException
 if years is negative, zero or over 1,000public static Frequency parse(String toParse)
The format can either be based on ISO8601, such as 'P3M' or without the 'P' prefix e.g. '2W'.
The period must be positive and nonzero.
toParse
 the string representing the frequencyIllegalArgumentException
 if the frequency cannot be parsedpublic Period getPeriod()
public boolean isTerm()
The term instance corresponds to there being no subdivisions of the entire term.
public Frequency normalized()
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.
public boolean isWeekBased()
A weekbased frequency consists of an integral number of weeks. There must be no day, month or year element.
public boolean isMonthBased()
A monthbased frequency consists of an integral number of months. Any yearbased frequency is also counted as monthbased. There must be no day or week element.
public boolean isAnnual()
An annual frequency consists of 12 months. There must be no day or week element.
public int eventsPerYear()
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.
Monthbased and yearbased 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.
Daybased and weekbased 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.
IllegalArgumentException
 if unable to calculate the number of events per yearpublic double eventsPerYearEstimate()
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. Monthbased and yearbased periodic frequencies return 12 divided by the number of months. Daybased and weekbased periodic frequencies return 364 divided by the number of days. Other frequencies are calculated using estimated durations, dividing the year by the period.
public int exactDivide(Frequency other)
This calculates the integer division of this frequency by the specified frequency. If the result is not an integer, an exception is thrown.
Monthbased and yearbased 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.
Daybased and weekbased 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.
other
 the other frequency to divide into this oneIllegalArgumentException
 if the frequency does not exactly divide into this onepublic long get(TemporalUnit 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.
get
in interface TemporalAmount
unit
 the unit to queryUnsupportedTemporalTypeException
 if the unit is not supportedpublic List<TemporalUnit> getUnits()
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.
getUnits
in interface TemporalAmount
public Temporal addTo(Temporal temporal)
This method implements TemporalAmount
.
It is not intended to be called directly.
Use LocalDate.plus(TemporalAmount)
instead.
addTo
in interface TemporalAmount
temporal
 the temporal object to add toDateTimeException
 if unable to addArithmeticException
 if numeric overflow occurspublic Temporal subtractFrom(Temporal temporal)
This method implements TemporalAmount
.
It is not intended to be called directly.
Use LocalDate.minus(TemporalAmount)
instead.
subtractFrom
in interface TemporalAmount
temporal
 the temporal object to subtract fromDateTimeException
 if unable to subtractArithmeticException
 if numeric overflow occurspublic boolean equals(Object obj)
The comparison checks the frequency period.
public int hashCode()
Copyright 2009Present by OpenGamma Inc. and individual contributors
Apache v2 licensed
Additional documentation can be found at strata.opengamma.io.