total Received

Dependents

this module uses 8 subunits yeardateDiff360isLeapYeardateYearBasisdateYMDconstantsdaysInMonth

Interface

TotalReceived

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:

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:

<div align="center"> <table border="0"> <tr align="center"><td width="100"> <strong>Type</strong></td><td><strong>Value</strong></td><td><strong>Description</strong></td></tr> <tr><td align="center" valign="top"><em>yb_US</em></td><td valign="top">0</td><td>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.</td></tr> <tr><td align="center" valign="top"><em>yb_Act</em></td><td valign="top">1</td><td>Uses the exact number of elapsed days between the two dates, as well as the exact length of the year.</td></tr> <tr><td align="center" valign="top"><em>yb_Act360</em></td><td valign="top">2</td><td>Uses the exact number of elapsed days between two dates but assumes the year only have 360 days</td></tr> <tr><td align="center" valign="top"><em>yb_Act365</em></td><td valign="top">3</td><td>Uses the exact number of elapsed days between two dates but assumes the year always has 365 days</td></tr> <tr><td align="center" valign="top"><em>yb_EU</em></td><td valign="top">4</td><td>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.</td></tr> </table> </div>

Warning

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 every 4th year is a leap year, see isleapyear), and we also check if the 'leap day' on the 29th Feb falls between the maturity and settlement dates. Only when these two conditions are satisfied is the year assumed to have 366 days. In insances when the settlement to maturity span several years, and one or more of these years is a leap years, then the average of the year lengths is used.

Bug

We can't replicate all of Microsofts errors, and we are confussed by the difference in the follow situations, the first of which matches Bill's solution perfectly, while the second does not - both example span a leap day: Here 29 Feb in 2004 is the leap day.

totalReceived(date(2001,5,15), date(2004,3,10), 1000000, 0.0575, yb_Act, true) -> 1193529.940364
RECEIVED('15/5/2001', '10/3/2004', 1000000, 0.0575, 1) -> 1193529.94

And this situation the 29 Feb 1996 is the leap day.

totalReceived(date(1995,5,2), date(1996,3,5), 738, 0.057, yb_Act, true) -> 775.236820
RECEIVED('15/5/2001', '10/3/2004', 1000000, 0.0575, 1) -> 775.1833867

If you know the solution please let me know :)

If investment or discount is less than 0, or the settlement date is greater than the maturity date, the function will return -1.

Reference

Microsoft Excel Help File

Example 1

#include <iostream>
#include <codecogs/finance/banking/totalreceived.h>
 
int main()
{ 
  std::cout << Finance::Banking::totalReceived(Units::Date::date(1999,2,15),
Units::Date::date(1999,5,15), 1000000, 0.0575, Finance::Banking::yb_Act365);
  return(0);
}

Output:

1.01442e+006

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, whereyb_USA = US (NASD) 30/360,yb_Act = Actual/actualyb_Act360 = Actual/360yb_Act365 = Actual/365yb_EU = European 30/360
WorkLikeExcel	emulates Excel's "wrong" calculation of Actual/actual; seedocumentation for details....

Authors

Alwyn Tan, March 2005

Source Code

Source code is available when you buy a Commercial licence.

Not a member, then Register with CodeCogs. Already a Member, then Login.