Documentation - Example 3
DOCUMENTATION FOR Finance::Banking::totalReceived_Maturity
This example shows how a table can be added to the documentation:
Brief Description
Returns the total amount received from a financial security at maturity
Gives this:
Interface | ||
| #include <codecogs/finance/banking/banking.h> | ||
| double | Finance::Banking::totalReceived_Maturity (int settlement, int maturity, double investment, double discount, YearBasis basis=yb_USA, bool WorkLikeExcel=false) | |
| Returns the total amount received from a financial security at maturity Excel: RECEIVED. | ||
Detailed Description
Calculates the total amount received from a financial security at maturity.
The settlement date is the date a buyer purchases a coupon, such as a bond. The maturity date is the date when a coupon expires. For example, suppose a 30-year bond is issued on January 1, 1996, and is purchased by a buyer six months later. The settlement date is taken to be July 1, 1996, and the maturity date would be January 1, 2026, which is 30 years after the January 1, 1996 issue date.
The function is based on the following equation:
\[ Received = \frac{investment}{1-(discount \frac{DIM}{B}} \]
Where
- investment is the value of the investment,
- discount is the discount rate,
- DIM is the days from investment settlement to maturity, and
- B is the number of days in a year, depending on the year basis.
The code defines a enum type, YearBasis, using the following sequence of values:
\copydoc YearBasis
This function differs from its Excel cousin in that it performs a more accurate calculation of securities using the Actual/Actual day count basis, when WorkLikeExcel=false. Specifically, it accurately determines if the settlement date falls in a leap year (Excel thinks that 1900 is a leap year), and also whether February 29th falls between the maturity and settlement dates. Only when these two conditions are satisfied is B (number of days in year) set to 366.
In insances when the settlement to maturity span several years, where one or more are leap years, then the average year length is used.
For example, for the following:
- Settlement date - 15/04/2000
- Maturity date - 15/05/2000
- Investment - 1,000,000
- Discount rate - 0.05
- Day count basis - Actual/actual
the amount received should be 1,004,126.5 and not 1,004,115 as calculated by Excel, since Feb 29th does not fall within the period.
If investment or discount is less than 0, or the settlement date is greater than the maturity date, the function will return a value of -1.
Gives this:
Detailed Description
Calculates the total amount received from a financial security at maturity.The settlement date is the date a buyer purchases a coupon, such as a bond. The maturity date is the date when a coupon expires. For example, suppose a 30-year bond is issued on January 1, 1996, and is purchased by a buyer six months later. The settlement date is taken to be July 1, 1996, and the maturity date would be January 1, 2026, which is 30 years after the January 1, 1996 issue date.
The function is based on the following equation:
![\[ Received = \frac{investment}{1-(discount*frac{DIM}{B}} \]](form_34.png)
Where
- investment is the value of the investment,
- discount is the discount rate,
- DIM is the days from investment settlement to maturity, and
- B is the number of days in a year, depending on the year basis.
The code defines a enum type, YearBasis, using the following sequence of values: 0 - US (NASD) 30/360 1 - Actual/actual 2 - Actual/360 3 - Actual/365 4 - European 30/360
| Type | Description |
| yb_EU | European 30/360 - Each month is assumed to have 30 days, such that the year has only 360 days. Start and end dates that occur on the 31st of a month become equal to the 30th of the same month. |
| yb_US | US (NASD) 30/360 - As with the European 30/360 (yb_EU_, with the additional provision that if the end date occurs on the 31st of a month it is moved to the 1st of the next month if the start date is earlier than the 30th. |
| yb_Act | Uses the exact number of elapsed days between the two dates, as well as the exact length of the year. |
| yb_Act360 | Uses the exact number of elapsed days between two dates but assumes the year only have 360 days |
| yb_Act365 | Uses the exact number of elapsed days between two dates but assumes the year always has 365 days |
This function differs from its Excel cousin in that it performs a more accurate calculation of securities using the Actual/Actual day count basis, when WorkLikeExcel=false. Specifically, it accurately determines if the settlement date falls in a leap year (Excel thinks that 1900 is a leap year), and also whether February 29th falls between the maturity and settlement dates. Only when these two conditions are satisfied is B (number of days in year) set to 366.
In insances when the settlement to maturity span several years, where one or more are leap years, then the average year length is used.
For example, for the following:
- Settlement date - 15/04/2000
- Maturity date - 15/05/2000
- Investment - 1,000,000
- Discount rate - 0.05
- Day count basis - Actual/actual
the amount received should be 1,004,126.5 and not 1,004,115 as calculated by Excel, since Feb 29th does not fall within the period.
If investment or discount is less than 0, or the settlement date is greater than the maturity date, the function will return a value of -1.
Function Documentation
The Source Code (+ Function Description)
//!Returns the total amount received from a financial security at maturity //! Excel: RECEIVED /*! Calculates the amount received at maturity for a fully invested security \param settlement is the date date after the issue date when the security is traded to the buyer in Julian date form \param maturity is security's maturity date, expressed as a serial Julian date number \param investment is the value of the investment \param discount is the security's discount rate \param basis is the day count basis, where yb_USA = US (NASD) 30/360, yb_Act = Actual/actual yb_Act360 = Actual/360 yb_Act365 = Actual/365 yb_EU = European 30/360 \param WorkLikeExcel emulates Excel's "wrong" calculation of Actual/actual; see documentation for details.... \Example: \code #include#include "totalReceive_Maturity.h" int main(){ cout << totalReceive_Maturity(date(1999,2,15),date(1999,5,15),1000000,0.0575,Act365); return(0); } \endcode \Output \code 1.01442e+006 \endcode \author Alwyn Tan, March 2005 \References Microsoft Excel Help File */ double totalReceived_Maturity(int settlement, int maturity, double investment, double discount, YearBasis basis=yb_USA, bool WorkLikeExcel=false) { ... }
Gives this:
|
||||||||||||||||||||||||||||
Calculates the amount received at maturity for a fully invested security
- Parameters:
-
settlement is the date date after the issue date when the security is traded to the buyer in Julian date form maturity is security's maturity date, expressed as a serial Julian date number investment is the value of the investment discount is the security's discount rate basis is the day count basis, where yb_USA = US (NASD) 30/360, yb_Act = Actual/actual yb_Act360 = Actual/360 yb_Act365 = Actual/365 yb_EU = European 30/360 WorkLikeExcel emulates Excel's "wrong" calculation of Actual/actual; see documentation for details....
- Example:
#include <iostream.h> #include "totalReceive_Maturity.h" int main(){ cout << totalReceive_Maturity(date(1999,2,15),date(1999,5,15),1000000,0.0575,Act365); return(0); }
- Example Output:
1.01442e+006
- Author:
- Alwyn Tan, March 2005
- References:
- Microsoft Excel Help File
- Source Code:
-
You only own a GNU GPL licence for this module.
You do not own any licences for this module.
