Financial functions more rationalization (#1990)

* Additional unit tests and rationalisation for Financial Functions
* Providing a series of sample files for Financial functions
* Refactor the last of the existing Financial functions
* Some more unit tests with default assignments from null arguments

Co-authored-by: Adrien Crivelli <[email protected]>

samples/Calculations/Financial/ACCRINT.php

@@ -0,0 +1,35 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the accrued interest for a security that pays periodic interest.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Issue Date', DateHelper::getDateValue('01-Jan-2012')],
+    ['First Interest Date', DateHelper::getDateValue('01-Apr-2012')],
+    ['Settlement Date', DateHelper::getDateValue('31-Dec-2013')],
+    ['Annual Coupon Rate', 0.08],
+    ['Par Value', 10000],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B3')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+$worksheet->getStyle('B4')->getNumberFormat()->setFormatCode('0.00%');
+$worksheet->getStyle('B5')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+// Now the formula
+$worksheet->setCellValue('B10', '=ACCRINT(B1, B2, B3, B4, B5, B6)');
+$worksheet->getStyle('B10')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+$helper->log($worksheet->getCell('B10')->getValue());
+$helper->log('ACCRINT() Result is ' . $worksheet->getCell('B10')->getFormattedValue());

samples/Calculations/Financial/ACCRINTM.php

@@ -0,0 +1,33 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the accrued interest for a security that pays interest at maturity.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Issue Date', DateHelper::getDateValue('01-Jan-2012')],
+    ['Settlement Date', DateHelper::getDateValue('31-Dec-2012')],
+    ['Annual Coupon Rate', 0.08],
+    ['Par Value', 10000],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+$worksheet->getStyle('B3')->getNumberFormat()->setFormatCode('0.00%');
+$worksheet->getStyle('B4')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=ACCRINTM(B1, B2, B3, B4)');
+$worksheet->getStyle('B6')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('ACCRINTM() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/AMORDEGRC.php

@@ -0,0 +1,38 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Calculation\Financial\Constants as FinancialConstants;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the prorated linear depreciation of an asset for a specified accounting period.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Cost', 150.00],
+    ['Date Purchased', DateHelper::getDateValue('01-Jan-2015')],
+    ['First Period Date', DateHelper::getDateValue('30-Sep-2015')],
+    ['Salvage Value', 20.00],
+    ['Number of Periods', 1],
+    ['Depreciation Rate', 0.20],
+    ['Basis', FinancialConstants::BASIS_DAYS_PER_YEAR_360_EUROPEAN],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1')->getNumberFormat()->setFormatCode('$#,##0.00');
+$worksheet->getStyle('B2:B3')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+$worksheet->getStyle('B4')->getNumberFormat()->setFormatCode('$#,##0.00');
+$worksheet->getStyle('B6')->getNumberFormat()->setFormatCode('0.00%');
+
+// Now the formula
+$worksheet->setCellValue('B10', '=AMORDEGRC(B1, B2, B3, B4, B5, B6, B7)');
+$worksheet->getStyle('B10')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+$helper->log($worksheet->getCell('B10')->getValue());
+$helper->log('AMORDEGRC() Result is ' . $worksheet->getCell('B10')->getFormattedValue());

samples/Calculations/Financial/AMORLINC.php

@@ -0,0 +1,38 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Calculation\Financial\Constants as FinancialConstants;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the prorated linear depreciation of an asset for a specified accounting period.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Cost', 150.00],
+    ['Date Purchased', DateHelper::getDateValue('01-Jan-2015')],
+    ['First Period Date', DateHelper::getDateValue('30-Sep-2015')],
+    ['Salvage Value', 20.00],
+    ['Period', 1],
+    ['Depreciation Rate', 0.20],
+    ['Basis', FinancialConstants::BASIS_DAYS_PER_YEAR_360_EUROPEAN],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1')->getNumberFormat()->setFormatCode('$#,##0.00');
+$worksheet->getStyle('B2:B3')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+$worksheet->getStyle('B4')->getNumberFormat()->setFormatCode('$#,##0.00');
+$worksheet->getStyle('B6')->getNumberFormat()->setFormatCode('0.00%');
+
+// Now the formula
+$worksheet->setCellValue('B10', '=AMORLINC(B1, B2, B3, B4, B5, B6, B7)');
+$worksheet->getStyle('B10')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+$helper->log($worksheet->getCell('B10')->getValue());
+$helper->log('AMORLINC() Result is ' . $worksheet->getCell('B10')->getFormattedValue());

samples/Calculations/Financial/COUPDAYBS.php

@@ -0,0 +1,29 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the number of days from the beginning of a coupon\'s period to the settlement date.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Settlement Date', DateHelper::getDateValue('01-Jan-2011')],
+    ['Maturity Date', DateHelper::getDateValue('25-Oct-2012')],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=COUPDAYBS(B1, B2, B3)');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('COUPDAYBS() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/COUPDAYS.php

@@ -0,0 +1,29 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the number of days in the coupon period that contains the settlement date.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Settlement Date', DateHelper::getDateValue('01-Jan-2011')],
+    ['Maturity Date', DateHelper::getDateValue('25-Oct-2012')],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=COUPDAYS(B1, B2, B3)');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('COUPDAYS() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/COUPDAYSNC.php

@@ -0,0 +1,29 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the number of days from the settlement date to the next coupon date.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Settlement Date', DateHelper::getDateValue('01-Jan-2011')],
+    ['Maturity Date', DateHelper::getDateValue('25-Oct-2012')],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=COUPDAYSNC(B1, B2, B3)');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('COUPDAYSNC() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/COUPNCD.php

@@ -0,0 +1,30 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the next coupon date, after the settlement date.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Settlement Date', DateHelper::getDateValue('01-Jan-2011')],
+    ['Maturity Date', DateHelper::getDateValue('25-Oct-2012')],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=COUPNCD(B1, B2, B3)');
+$worksheet->getStyle('B6')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('COUPNCD() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/COUPNUM.php

@@ -0,0 +1,30 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the number of coupons payable, between a security\'s settlement date and maturity date,');
+$helper->log('rounded up to the nearest whole coupon.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Settlement Date', DateHelper::getDateValue('01-Jan-2011')],
+    ['Maturity Date', DateHelper::getDateValue('25-Oct-2012')],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=COUPNUM(B1, B2, B3)');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('COUPNUM() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/COUPPCD.php

@@ -0,0 +1,30 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Calculation\DateTimeExcel\Helpers as DateHelper;
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the previous coupon date, before the settlement date for a security.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Settlement Date', DateHelper::getDateValue('01-Jan-2011')],
+    ['Maturity Date', DateHelper::getDateValue('25-Oct-2012')],
+    ['Frequency', 4],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1:B2')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+// Now the formula
+$worksheet->setCellValue('B6', '=COUPPCD(B1, B2, B3)');
+$worksheet->getStyle('B6')->getNumberFormat()->setFormatCode('dd-mmm-yyyy');
+
+$helper->log($worksheet->getCell('B6')->getValue());
+$helper->log('COUPPCD() Result is ' . $worksheet->getCell('B6')->getFormattedValue());

samples/Calculations/Financial/CUMIPMT.php

@@ -0,0 +1,38 @@
+<?php
+
+use PhpOffice\PhpSpreadsheet\Spreadsheet;
+
+require __DIR__ . '/../../Header.php';
+
+$helper->log('Returns the cumulative interest paid on a loan or investment, between two specified periods.');
+
+// Create new PhpSpreadsheet object
+$spreadsheet = new Spreadsheet();
+$worksheet = $spreadsheet->getActiveSheet();
+
+// Add some data
+$arguments = [
+    ['Interest Rate (per period)', 0.05 / 12],
+    ['Number of Periods', 5 * 12],
+    ['Present Value', 50000],
+];
+
+// Some basic formatting for the data
+$worksheet->fromArray($arguments, null, 'A1');
+$worksheet->getStyle('B1')->getNumberFormat()->setFormatCode('0.00%');
+$worksheet->getStyle('B3')->getNumberFormat()->setFormatCode('$#,##0.00');
+
+// Now the formula
+$baseRow = 5;
+for ($year = 1; $year <= 5; ++$year) {
+    $row = (string) ($baseRow + $year);
+    $yearStartPeriod = (int) $year * 12 - 11;
+    $yearEndPeriod = (int) $year * 12;
+
+    $worksheet->setCellValue("A{$row}", "Yr {$year}");
+    $worksheet->setCellValue("B{$row}", "=CUMIPMT(\$B\$1, \$B\$2, \$B\$3, {$yearStartPeriod}, {$yearEndPeriod}, 0)");
+    $worksheet->getStyle("B{$row}")->getNumberFormat()->setFormatCode('$#,##0.00;-$#,##0.00');
+
+    $helper->log($worksheet->getCell("B{$row}")->getValue());
+    $helper->log("CUMIPMT() Year {$year} Result is " . $worksheet->getCell("B{$row}")->getFormattedValue());
+}