Frequency (OpenGamma Strata Basics)

java.lang.Object
- com.opengamma.strata.basics.schedule.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 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.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
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 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

Copyright 2009-Present by OpenGamma Inc. and individual contributors
Apache v2 licensed
Additional documentation can be found at strata.opengamma.io.

Class Frequency

Usage

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

P1D

P1W

P2W

P4W

P13W

P26W

P52W

P1M

P2M

P3M

P4M

P6M

P12M

TERM

Method Detail

of

ofDays

ofWeeks

ofMonths

ofYears

parse

getPeriod

isTerm

normalized

isWeekBased

isMonthBased

isAnnual

eventsPerYear

eventsPerYearEstimate

exactDivide

get

getUnits

addTo

subtractFrom

equals

hashCode

toString