Class Frequency
 java.lang.Object

 com.opengamma.strata.basics.schedule.Frequency

 All Implemented Interfaces:
java.io.Serializable
,java.time.temporal.TemporalAmount
public final class Frequency extends java.lang.Object implements java.time.temporal.TemporalAmount, java.io.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 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. Callnormalized()
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
implementsTemporalAmount
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 Static Methods Instance Methods Concrete Methods Modifier and Type Method Description java.time.temporal.Temporal
addTo(java.time.temporal.Temporal temporal)
Adds the period of this frequency to the specified date.boolean
equals(java.lang.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(java.time.temporal.TemporalUnit unit)
Gets the value of the specified unit.java.time.Period
getPeriod()
Gets the underlying period of the frequency.java.util.List<java.time.temporal.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(java.time.Period period)
Obtains an instance from aPeriod
.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(java.lang.String toParse)
Parses a formatted string representing the frequency.java.time.temporal.Temporal
subtractFrom(java.time.temporal.Temporal temporal)
Subtracts the period of this frequency from the specified date.java.lang.String
toString()
Returns a formatted string representing the periodic frequency.



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 biweekly. 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 bimonthly. 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 semiannual. 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 zerocoupon. 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(java.time.Period period)
Obtains an instance from aPeriod
.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.
 Parameters:
period
 the period to convert to a periodic frequency Returns:
 the periodic frequency
 Throws:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.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:
java.lang.IllegalArgumentException
 if years is negative, zero or over 1,000

parse
public static Frequency parse(java.lang.String toParse)
Parses a formatted string representing the frequency.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.
 Parameters:
toParse
 the string representing the frequency Returns:
 the frequency
 Throws:
java.lang.IllegalArgumentException
 if the frequency cannot be parsed

getPeriod
public java.time.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 weekbased.A weekbased frequency consists of an integral number of weeks. There must be no day, month or year element.
 Returns:
 true if this is weekbased

isMonthBased
public boolean isMonthBased()
Checks if the periodic frequency is monthbased.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.
 Returns:
 true if this is monthbased

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.
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.
 Returns:
 the number of events per year
 Throws:
java.lang.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. 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.
 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.
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.
 Parameters:
other
 the other frequency to divide into this one Returns:
 this frequency divided by the other frequency
 Throws:
java.lang.IllegalArgumentException
 if the frequency does not exactly divide into this one

get
public long get(java.time.temporal.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 interfacejava.time.temporal.TemporalAmount
 Parameters:
unit
 the unit to query Returns:
 the value of the unit
 Throws:
java.time.temporal.UnsupportedTemporalTypeException
 if the unit is not supported

getUnits
public java.util.List<java.time.temporal.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 interfacejava.time.temporal.TemporalAmount
 Returns:
 a list containing the years, months and days units

addTo
public java.time.temporal.Temporal addTo(java.time.temporal.Temporal temporal)
Adds the period of this frequency to the specified date.This method implements
TemporalAmount
. It is not intended to be called directly. UseLocalDate.plus(TemporalAmount)
instead. Specified by:
addTo
in interfacejava.time.temporal.TemporalAmount
 Parameters:
temporal
 the temporal object to add to Returns:
 the result with this frequency added
 Throws:
java.time.DateTimeException
 if unable to addjava.lang.ArithmeticException
 if numeric overflow occurs

subtractFrom
public java.time.temporal.Temporal subtractFrom(java.time.temporal.Temporal temporal)
Subtracts the period of this frequency from the specified date.This method implements
TemporalAmount
. It is not intended to be called directly. UseLocalDate.minus(TemporalAmount)
instead. Specified by:
subtractFrom
in interfacejava.time.temporal.TemporalAmount
 Parameters:
temporal
 the temporal object to subtract from Returns:
 the result with this frequency subtracted
 Throws:
java.time.DateTimeException
 if unable to subtractjava.lang.ArithmeticException
 if numeric overflow occurs

equals
public boolean equals(java.lang.Object obj)
Checks if this periodic frequency equals another periodic frequency.The comparison checks the frequency period.
 Overrides:
equals
in classjava.lang.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 classjava.lang.Object
 Returns:
 the hash code

toString
public java.lang.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 classjava.lang.Object
 Returns:
 the formatted frequency

