diff --git a/Classes/PHPExcel/Calculation/Engineering.php b/Classes/PHPExcel/Calculation/Engineering.php index 0e5246cd..9e26004c 100644 --- a/Classes/PHPExcel/Calculation/Engineering.php +++ b/Classes/PHPExcel/Calculation/Engineering.php @@ -49,6 +49,11 @@ define('EULER', 2.71828182845904523536); */ class PHPExcel_Calculation_Engineering { + /** + * Details of the Units of measure that can be used in CONVERTUOM() + * + * @var mixed[] + */ private static $_conversionUnits = array( 'g' => array( 'Group' => 'Mass', 'Unit Name' => 'Gram', 'AllowPrefix' => True ), 'sg' => array( 'Group' => 'Mass', 'Unit Name' => 'Slug', 'AllowPrefix' => False ), 'lbm' => array( 'Group' => 'Mass', 'Unit Name' => 'Pound mass (avoirdupois)', 'AllowPrefix' => False ), @@ -114,6 +119,11 @@ class PHPExcel_Calculation_Engineering { 'lt' => array( 'Group' => 'Liquid', 'Unit Name' => 'Litre', 'AllowPrefix' => True ) ); + /** + * Details of the Multiplier prefixes that can be used with Units of Measure in CONVERTUOM() + * + * @var mixed[] + */ private static $_conversionMultipliers = array( 'Y' => array( 'multiplier' => 1E24, 'name' => 'yotta' ), 'Z' => array( 'multiplier' => 1E21, 'name' => 'zetta' ), 'E' => array( 'multiplier' => 1E18, 'name' => 'exa' ), @@ -136,6 +146,11 @@ class PHPExcel_Calculation_Engineering { 'y' => array( 'multiplier' => 1E-24, 'name' => 'yocto' ) ); + /** + * Details of the Units of measure conversion factors, organised by group + * + * @var mixed[] + */ private static $_unitConversions = array( 'Mass' => array( 'g' => array( 'g' => 1.0, 'sg' => 6.85220500053478E-05, 'lbm' => 2.20462291469134E-03, @@ -670,6 +685,14 @@ class PHPExcel_Calculation_Engineering { ); + /** + * _parseComplex + * + * Parses a complex number into its real and imaginary parts, and an I or J suffix + * + * @param string $complexNumber The complex number + * @return string[] Indexed on "real", "imaginary" and "suffix" + */ public static function _parseComplex($complexNumber) { $workString = (string) $complexNumber; @@ -717,6 +740,14 @@ class PHPExcel_Calculation_Engineering { } // function _parseComplex() + /** + * _cleanComplex + * + * Cleans the leading characters in a complex number string + * + * @param string $complexNumber The complex number to clean + * @return string The "cleaned" complex number + */ private static function _cleanComplex($complexNumber) { if ($complexNumber{0} == '+') $complexNumber = substr($complexNumber,1); if ($complexNumber{0} == '0') $complexNumber = substr($complexNumber,1); @@ -1604,11 +1635,17 @@ class PHPExcel_Calculation_Engineering { /** * COMPLEX * - * returns a complex number of the form x + yi or x + yj. + * Converts real and imaginary coefficients into a complex number of the form x + yi or x + yj. * - * @param float $realNumber - * @param float $imaginary - * @param string $suffix + * Excel Function: + * COMPLEX(realNumber,imaginary[,places]) + * + * @access public + * @category Engineering Functions + * @param float $realNumber The real coefficient of the complex number. + * @param float $imaginary The imaginary coefficient of the complex number. + * @param string $suffix The suffix for the imaginary component of the complex number. + * If omitted, the suffix is assumed to be "i". * @return string */ public static function COMPLEX($realNumber=0.0, $imaginary=0.0, $suffix='i') { @@ -1651,8 +1688,14 @@ class PHPExcel_Calculation_Engineering { * * Returns the imaginary coefficient of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber - * @return real + * Excel Function: + * IMAGINARY(complexNumber) + * + * @access public + * @category Engineering Functions + * @param string $complexNumber The complex number for which you want the imaginary + * coefficient. + * @return float */ public static function IMAGINARY($complexNumber) { $complexNumber = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber); @@ -1667,8 +1710,13 @@ class PHPExcel_Calculation_Engineering { * * Returns the real coefficient of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber - * @return real + * Excel Function: + * IMREAL(complexNumber) + * + * @access public + * @category Engineering Functions + * @param string $complexNumber The complex number for which you want the real coefficient. + * @return float */ public static function IMREAL($complexNumber) { $complexNumber = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber); @@ -1683,8 +1731,11 @@ class PHPExcel_Calculation_Engineering { * * Returns the absolute value (modulus) of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber - * @return real + * Excel Function: + * IMABS(complexNumber) + * + * @param string $complexNumber The complex number for which you want the absolute value. + * @return float */ public static function IMABS($complexNumber) { $complexNumber = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber); @@ -1698,10 +1749,14 @@ class PHPExcel_Calculation_Engineering { /** * IMARGUMENT * - * Returns the argument theta of a complex number, i.e. the angle in radians from the real axis to the representation of the number in polar coordinates. + * Returns the argument theta of a complex number, i.e. the angle in radians from the real + * axis to the representation of the number in polar coordinates. * - * @param string $complexNumber - * @return string + * Excel Function: + * IMARGUMENT(complexNumber) + * + * @param string $complexNumber The complex number for which you want the argument theta. + * @return float */ public static function IMARGUMENT($complexNumber) { $complexNumber = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber); @@ -1731,7 +1786,10 @@ class PHPExcel_Calculation_Engineering { * * Returns the complex conjugate of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber + * Excel Function: + * IMCONJUGATE(complexNumber) + * + * @param string $complexNumber The complex number for which you want the conjugate. * @return string */ public static function IMCONJUGATE($complexNumber) { @@ -1742,7 +1800,11 @@ class PHPExcel_Calculation_Engineering { if ($parsedComplex['imaginary'] == 0.0) { return $parsedComplex['real']; } else { - return self::_cleanComplex(self::COMPLEX($parsedComplex['real'], 0 - $parsedComplex['imaginary'], $parsedComplex['suffix'])); + return self::_cleanComplex( self::COMPLEX( $parsedComplex['real'], + 0 - $parsedComplex['imaginary'], + $parsedComplex['suffix'] + ) + ); } } // function IMCONJUGATE() @@ -1752,8 +1814,11 @@ class PHPExcel_Calculation_Engineering { * * Returns the cosine of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber - * @return string + * Excel Function: + * IMCOS(complexNumber) + * + * @param string $complexNumber The complex number for which you want the cosine. + * @return string|float */ public static function IMCOS($complexNumber) { $complexNumber = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber); @@ -1773,8 +1838,11 @@ class PHPExcel_Calculation_Engineering { * * Returns the sine of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber - * @return string + * Excel Function: + * IMSIN(complexNumber) + * + * @param string $complexNumber The complex number for which you want the sine. + * @return string|float */ public static function IMSIN($complexNumber) { $complexNumber = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber); @@ -1794,7 +1862,10 @@ class PHPExcel_Calculation_Engineering { * * Returns the square root of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber + * Excel Function: + * IMSQRT(complexNumber) + * + * @param string $complexNumber The complex number for which you want the square root. * @return string */ public static function IMSQRT($complexNumber) { @@ -1820,7 +1891,10 @@ class PHPExcel_Calculation_Engineering { * * Returns the natural logarithm of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber + * Excel Function: + * IMLN(complexNumber) + * + * @param string $complexNumber The complex number for which you want the natural logarithm. * @return string */ public static function IMLN($complexNumber) { @@ -1848,7 +1922,10 @@ class PHPExcel_Calculation_Engineering { * * Returns the common logarithm (base 10) of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber + * Excel Function: + * IMLOG10(complexNumber) + * + * @param string $complexNumber The complex number for which you want the common logarithm. * @return string */ public static function IMLOG10($complexNumber) { @@ -1871,7 +1948,10 @@ class PHPExcel_Calculation_Engineering { * * Returns the common logarithm (base 10) of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber + * Excel Function: + * IMLOG2(complexNumber) + * + * @param string $complexNumber The complex number for which you want the base-2 logarithm. * @return string */ public static function IMLOG2($complexNumber) { @@ -1894,7 +1974,10 @@ class PHPExcel_Calculation_Engineering { * * Returns the exponential of a complex number in x + yi or x + yj text format. * - * @param string $complexNumber + * Excel Function: + * IMEXP(complexNumber) + * + * @param string $complexNumber The complex number for which you want the exponential. * @return string */ public static function IMEXP($complexNumber) { @@ -1923,8 +2006,11 @@ class PHPExcel_Calculation_Engineering { * * Returns a complex number in x + yi or x + yj text format raised to a power. * - * @param string $complexNumber - * @param float $realNumber + * Excel Function: + * IMPOWER(complexNumber,realNumber) + * + * @param string $complexNumber The complex number you want to raise to a power. + * @param float $realNumber The power to which you want to raise the complex number. * @return string */ public static function IMPOWER($complexNumber,$realNumber) { @@ -1955,9 +2041,12 @@ class PHPExcel_Calculation_Engineering { * * Returns the quotient of two complex numbers in x + yi or x + yj text format. * - * @param string $complexDividend - * @param string $complexDivisor - * @return real + * Excel Function: + * IMDIV(complexDividend,complexDivisor) + * + * @param string $complexDividend The complex numerator or dividend. + * @param string $complexDivisor The complex denominator or divisor. + * @return string */ public static function IMDIV($complexDividend,$complexDivisor) { $complexDividend = PHPExcel_Calculation_Functions::flattenSingleValue($complexDividend); @@ -1996,9 +2085,12 @@ class PHPExcel_Calculation_Engineering { * * Returns the difference of two complex numbers in x + yi or x + yj text format. * - * @param string $complexNumber1 - * @param string $complexNumber2 - * @return real + * Excel Function: + * IMSUB(complexNumber1,complexNumber2) + * + * @param string $complexNumber1 The complex number from which to subtract complexNumber2. + * @param string $complexNumber2 The complex number to subtract from complexNumber1. + * @return string */ public static function IMSUB($complexNumber1,$complexNumber2) { $complexNumber1 = PHPExcel_Calculation_Functions::flattenSingleValue($complexNumber1); @@ -2026,8 +2118,11 @@ class PHPExcel_Calculation_Engineering { * * Returns the sum of two or more complex numbers in x + yi or x + yj text format. * - * @param array of mixed Data Series - * @return real + * Excel Function: + * IMSUM(complexNumber[,complexNumber[,...]]) + * + * @param string $complexNumber,... Series of complex numbers to add + * @return string */ public static function IMSUM() { // Return value @@ -2059,8 +2154,11 @@ class PHPExcel_Calculation_Engineering { * * Returns the product of two or more complex numbers in x + yi or x + yj text format. * - * @param array of mixed Data Series - * @return real + * Excel Function: + * IMPRODUCT(complexNumber[,complexNumber[,...]]) + * + * @param string $complexNumber,... Series of complex numbers to multiply + * @return string */ public static function IMPRODUCT() { // Return value @@ -2091,9 +2189,15 @@ class PHPExcel_Calculation_Engineering { * DELTA * * Tests whether two values are equal. Returns 1 if number1 = number2; returns 0 otherwise. + * Use this function to filter a set of values. For example, by summing several DELTA + * functions you calculate the count of equal pairs. This function is also known as the + * Kronecker Delta function. * - * @param float $a - * @param float $b + * Excel Function: + * DELTA(a[,b]) + * + * @param float $a The first number. + * @param float $b The second number. If omitted, b is assumed to be zero. * @return int */ public static function DELTA($a, $b=0) { @@ -2107,10 +2211,16 @@ class PHPExcel_Calculation_Engineering { /** * GESTEP * - * Returns 1 if number = step; returns 0 (zero) otherwise + * Excel Function: + * GESTEP(number[,step]) * - * @param float $number - * @param float $step + * Returns 1 if number >= step; returns 0 (zero) otherwise + * Use this function to filter a set of values. For example, by summing several GESTEP + * functions you calculate the count of values that exceed a threshold. + * + * @param float $number The value to test against step. + * @param float $step The threshold value. + * If you omit a value for step, GESTEP uses zero. * @return int */ public static function GESTEP($number, $step=0) { @@ -2153,6 +2263,9 @@ class PHPExcel_Calculation_Engineering { * * Returns the error function integrated between lower_limit and upper_limit * + * Excel Function: + * ERF(lower[,upper]) + * * @param float $lower lower bound for integrating ERF * @param float $upper upper bound for integrating ERF. * If omitted, ERF integrates between zero and lower_limit @@ -2217,6 +2330,9 @@ class PHPExcel_Calculation_Engineering { * * Returns the complementary ERF function integrated between x and infinity * + * Excel Function: + * ERF(x) + * * @param float $x The lower bound for integrating ERF * @return int */ @@ -2294,9 +2410,16 @@ class PHPExcel_Calculation_Engineering { /** * CONVERTUOM * - * @param float $value - * @param string $fromUOM - * @param string $toUOM + * Converts a number from one measurement system to another. + * For example, CONVERT can translate a table of distances in miles to a table of distances + * in kilometers. + * + * Excel Function: + * CONVERT(value,fromUOM,toUOM) + * + * @param float $value The value in fromUOM to convert. + * @param string $fromUOM The units for value. + * @param string $toUOM The units for the result. * @return float */ public static function CONVERTUOM($value, $fromUOM, $toUOM) { diff --git a/Classes/PHPExcel/Calculation/Financial.php b/Classes/PHPExcel/Calculation/Financial.php index f97693c4..ee0bfb69 100644 --- a/Classes/PHPExcel/Calculation/Financial.php +++ b/Classes/PHPExcel/Calculation/Financial.php @@ -52,20 +52,36 @@ define('FINANCIAL_PRECISION', 1.0e-08); */ class PHPExcel_Calculation_Financial { - private static function _lastDayOfMonth($testDate) { - $date = clone $testDate; - $date->modify('+1 day'); - return ($date->format('d') == 1); + /** + * _lastDayOfMonth + * + * Returns a boolean TRUE/FALSE indicating if this date is the last date of the month + * + * @param DateTime $testDate The date for testing + * @return boolean + */ + private static function _lastDayOfMonth($testDate) + { + return ($testDate->format('d') == $testDate->format('t')); } // function _lastDayOfMonth() - private static function _firstDayOfMonth($testDate) { - $date = clone $testDate; - return ($date->format('d') == 1); - } // function _lastDayOfMonth() + /** + * _firstDayOfMonth + * + * Returns a boolean TRUE/FALSE indicating if this date is the first date of the month + * + * @param DateTime $testDate The date for testing + * @return boolean + */ + private static function _firstDayOfMonth($testDate) + { + return ($testDate->format('d') == 1); + } // function _firstDayOfMonth() - private static function _coupFirstPeriodDate($settlement, $maturity, $frequency, $next) { + private static function _coupFirstPeriodDate($settlement, $maturity, $frequency, $next) + { $months = 12 / $frequency; $result = PHPExcel_Shared_Date::ExcelToPHPObject($maturity); @@ -86,7 +102,8 @@ class PHPExcel_Calculation_Financial { } // function _coupFirstPeriodDate() - private static function _validFrequency($frequency) { + private static function _validFrequency($frequency) + { if (($frequency == 1) || ($frequency == 2) || ($frequency == 4)) { return true; } @@ -98,7 +115,22 @@ class PHPExcel_Calculation_Financial { } // function _validFrequency() - private static function _daysPerYear($year,$basis) { + /** + * _daysPerYear + * + * Returns the number of days in a specified year, as defined by the "basis" value + * + * @param integer $year The year against which we're testing + * @param integer $basis The type of day count: + * 0 or omitted US (NASD) 360 + * 1 Actual (365 or 366 in a leap year) + * 2 360 + * 3 365 + * 4 European 360 + * @return integer + */ + private static function _daysPerYear($year, $basis=0) + { switch ($basis) { case 0 : case 2 : @@ -109,11 +141,7 @@ class PHPExcel_Calculation_Financial { $daysPerYear = 365; break; case 1 : - if (PHPExcel_Calculation_DateTime::_isLeapYear($year)) { - $daysPerYear = 366; - } else { - $daysPerYear = 365; - } + $daysPerYear = (PHPExcel_Calculation_DateTime::_isLeapYear($year)) ? 366 : 365; break; default : return PHPExcel_Calculation_Functions::NaN(); @@ -122,7 +150,8 @@ class PHPExcel_Calculation_Financial { } // function _daysPerYear() - private static function _interestAndPrincipal($rate=0, $per=0, $nper=0, $pv=0, $fv=0, $type=0) { + private static function _interestAndPrincipal($rate=0, $per=0, $nper=0, $pv=0, $fv=0, $type=0) + { $pmt = self::PMT($rate, $nper, $pv, $fv, $type); $capital = $pv; for ($i = 1; $i<= $per; ++$i) { @@ -137,14 +166,31 @@ class PHPExcel_Calculation_Financial { /** * ACCRINT * - * Returns the discount rate for a security. + * Returns the accrued interest for a security that pays periodic interest. * - * @param mixed issue The security's issue date. - * @param mixed firstinter The security's first interest date. - * @param mixed settlement The security's settlement date. - * @param float rate The security's annual coupon rate. - * @param float par The security's par value. - * @param int basis The type of day count to use. + * Excel Function: + * ACCRINT(issue,firstinterest,settlement,rate,par,frequency[,basis]) + * + * @access public + * @category Financial Functions + * @param mixed $issue The security's issue date. + * @param mixed $firstinterest The security's first interest date. + * @param mixed $settlement The security's settlement date. + * The security settlement date is the date after the issue date + * when the security is traded to the buyer. + * @param float $rate The security's annual coupon rate. + * @param float $par The security's par value. + * If you omit par, ACCRINT uses $1,000. + * @param float $frequency the number of coupon payments per year. + * Valid frequency values are: + * 1 Annual + * 2 Semi-Annual + * 4 Quarterly + * If working in Gnumeric Mode, the following frequency options are + * also available + * 6 Bimonthly + * 12 Monthly + * @param int $basis The type of day count to use. * 0 or omitted US (NASD) 30/360 * 1 Actual/actual * 2 Actual/360 @@ -152,9 +198,10 @@ class PHPExcel_Calculation_Financial { * 4 European 30/360 * @return float */ - public static function ACCRINT($issue, $firstinter, $settlement, $rate, $par=1000, $frequency=1, $basis=0) { + public static function ACCRINT($issue, $firstinterest, $settlement, $rate, $par=1000, $frequency=1, $basis=0) + { $issue = PHPExcel_Calculation_Functions::flattenSingleValue($issue); - $firstinter = PHPExcel_Calculation_Functions::flattenSingleValue($firstinter); + $firstinterest = PHPExcel_Calculation_Functions::flattenSingleValue($firstinterest); $settlement = PHPExcel_Calculation_Functions::flattenSingleValue($settlement); $rate = (float) PHPExcel_Calculation_Functions::flattenSingleValue($rate); $par = (is_null($par)) ? 1000 : (float) PHPExcel_Calculation_Functions::flattenSingleValue($par); @@ -181,12 +228,18 @@ class PHPExcel_Calculation_Financial { /** * ACCRINTM * - * Returns the discount rate for a security. + * Returns the accrued interest for a security that pays interest at maturity. * + * Excel Function: + * ACCRINTM(issue,settlement,rate[,par[,basis]]) + * + * @access public + * @category Financial Functions * @param mixed issue The security's issue date. - * @param mixed settlement The security's settlement date. + * @param mixed settlement The security's settlement (or maturity) date. * @param float rate The security's annual coupon rate. * @param float par The security's par value. + * If you omit par, ACCRINT uses $1,000. * @param int basis The type of day count to use. * 0 or omitted US (NASD) 30/360 * 1 Actual/actual