cfdates

Cash flow dates for fixed-income security

Syntax

``CFlowDates = cfdates(Settle,Maturity)``
``CFlowDates = cfdates(___,Period,Basis,EndMonthRule,IssueDate,FirstCouponDate,LastCouponDate)``

Description

example

````CFlowDates = cfdates(Settle,Maturity)` generates a matrix of actual cash flow payment dates for `NUMBONDS` fixed income securities. All cash flow dates are determined regardless of whether the first and last coupon periods are normal, long or short.```

example

````CFlowDates = cfdates(___,Period,Basis,EndMonthRule,IssueDate,FirstCouponDate,LastCouponDate)` specifies options using one or more optional arguments in addition to the input arguments in the previous syntax. ```

Examples

collapse all

Compute the cash flow dates given the `Settle` and `Maturity` dates.

`CFlowDates = cfdates('14 Mar 1997', '30 Nov 1998', 2, 0, 1)`
```CFlowDates = 1×4 729541 729724 729906 730089 ```
`datestr(CFlowDates)`
```ans = 4x11 char array '31-May-1997' '30-Nov-1997' '31-May-1998' '30-Nov-1998' ```

If any of the inputs for `Settle`, `Maturity`, `IssueDate`, `FirstCouponDate`, or `LastCouponDate` are datetime arrays, then `CFlowDates` is returned as a datetime array. For example:

`CFlowDates = cfdates('14-Mar-1997', datetime('30-Nov-1998','Locale','en_US'), 2, 0, 1)`
```CFlowDates = 1x4 datetime 31-May-1997 30-Nov-1997 31-May-1998 30-Nov-1998 ```

Given three securities with different maturity dates and the same default arguments:

```Maturity = ['30-Sep-1997'; '31-Oct-1998'; '30-Nov-1998']; CFlowDates = cfdates('14-Mar-1997', Maturity)```
```CFlowDates = 3×4 729480 729663 NaN NaN 729510 729694 729875 730059 729541 729724 729906 730089 ```

To look at the cash-flow dates for the last security:

`datestr(CFlowDates(3,:))`
```ans = 4x11 char array '31-May-1997' '30-Nov-1997' '31-May-1998' '30-Nov-1998' ```

Input Arguments

collapse all

Settlement date, specified as an `NINST`-by-`1` vector using a datetime array, string array, or date character vectors. `Settle` must be earlier than `Maturity`.

To support existing code, `cfdates` also accepts serial date numbers as inputs, but they are not recommended.

Data Types: `char` | `string` | `datetime`

Maturity date, specified as an `NINST`-by-`1` vector using a datetime array, string array, or date character vectors.

To support existing code, `cfdates` also accepts serial date numbers as inputs, but they are not recommended.

Data Types: `char` | `string` | `datetime`

(Optional) Coupons per year of the bond, specified as a vector of positive integers from the set `[1,2,3,4,6,12]`.

Data Types: `double`

(Optional) Day-count basis, specified as positive integers using a `NINST`-by-`1` vector.

• 0 = actual/actual

• 1 = 30/360 (SIA)

• 2 = actual/360

• 3 = actual/365

• 4 = 30/360 (PSA)

• 5 = 30/360 (ISDA)

• 6 = 30/360 (European)

• 7 = actual/365 (Japanese)

• 8 = actual/actual (ICMA)

• 9 = actual/360 (ICMA)

• 10 = actual/365 (ICMA)

• 11 = 30/360E (ICMA)

• 12 = actual/365 (ISDA)

• 13 = BUS/252

Data Types: `double`

(Optional) End-of-month rule flag, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector. This rule applies only when `Maturity` is an end-of-month date for a month having 30 or fewer days.

• `0` = Ignore rule, meaning that a bond coupon payment date is always the same numerical day of the month.

• `1` = Set rule on, meaning that a bond coupon payment date is always the last actual day of the month.

Data Types: `logical`

(Optional) Bond Issue date, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using a datetime array, string array, or date character vectors.

If you do not specify an `IssueDate`, the cash flow payment dates are determined from other inputs.

To support existing code, `cfdates` also accepts serial date numbers as inputs, but they are not recommended.

Data Types: `char` | `string` | `datetime`

Irregular or normal first coupon date, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using a datetime array, string array, or date character vectors.

If you do not specify a `FirstCouponDate`, the cash flow payment dates are determined from other inputs.

To support existing code, `cfdates` also accepts serial date numbers as inputs, but they are not recommended.

Data Types: `char` | `string` | `datetime`

Irregular or normal last coupon date, specified as a scalar or a `NUMBONDS`-by-`1` or `1`-by-`NUMBONDS` vector using a datetime array, string array, or date character vectors.

If you do not specify a `LastCouponDate`, the cash flow payment dates are determined from other inputs.

To support existing code, `cfdates` also accepts serial date numbers as inputs, but they are not recommended.

Data Types: `char` | `string` | `datetime`

Output Arguments

collapse all

Actual cash flow payment dates, returned as a `N`-row matrix of dates in datetime format (if inputs are in datetime format). `CFlowDates` has `NUMBONDS` rows and the number of columns is determined by the maximum number of cash flow payment dates required to hold the bond portfolio. `NaN`s are padded for bonds which have less than the maximum number of cash flow payment dates.

If all of the inputs for `Settle`, `Maturity`, `IssueDate`, `FirstCouponDate`, or `LastCouponDate` are either strings or date character vectors, then `CFlowDates` is returned as a serial date number. Use the function `datestr` to convert serial date numbers to formatted date character vectors.

If any of the inputs for `Settle`, `Maturity`, `IssueDate`, `FirstCouponDate`, or `LastCouponDate` are datetime arrays, then `CFlowDates` is returned as a datetime array.

Note

The cash flow flags for a portfolio of bonds were formerly available as the `cfdates` second output argument, `CFlowFlags`. You can now use `cfamounts` to get these flags. If you specify a `CFlowFlags` argument, `cfdates` displays a message directing you to use `cfamounts`.

Version History

Introduced before R2006a

expand all