From 699467cd0f69624ca8f70eb7c2ef3f068d3ef66f Mon Sep 17 00:00:00 2001 From: Mark Baker Date: Fri, 23 Mar 2012 18:03:25 +0000 Subject: [PATCH] Doc Block changes git-svn-id: https://phpexcel.svn.codeplex.com/svn/trunk@88243 2327b42d-5241-43d6-9e2a-de5ac946f064 --- Classes/PHPExcel/Calculation/Database.php | 381 ++++++++++++++++++- Classes/PHPExcel/Calculation/DateTime.php | 366 +++++++++++++++--- Classes/PHPExcel/Calculation/Engineering.php | 373 +++++++++++++++--- 3 files changed, 1003 insertions(+), 117 deletions(-) diff --git a/Classes/PHPExcel/Calculation/Database.php b/Classes/PHPExcel/Calculation/Database.php index bb2cfec0..e9b73709 100644 --- a/Classes/PHPExcel/Calculation/Database.php +++ b/Classes/PHPExcel/Calculation/Database.php @@ -46,6 +46,22 @@ if (!defined('PHPEXCEL_ROOT')) { class PHPExcel_Calculation_Database { + /** + * __fieldExtract + * + * @access private + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @return string|NULL + * + */ private static function __fieldExtract($database,$field) { $field = strtoupper(PHPExcel_Calculation_Functions::flattenSingleValue($field)); $fieldNames = array_map('strtoupper',array_shift($database)); @@ -58,6 +74,22 @@ class PHPExcel_Calculation_Database { return ($key) ? $key : null; } + /** + * __filter + * + * @access private + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return array of mixed + * + */ private static function __filter($database,$criteria) { $fieldNames = array_shift($database); $criteriaNames = array_shift($criteria); @@ -113,7 +145,32 @@ class PHPExcel_Calculation_Database { /** - * DAVERAGE + * DAVERAGE + * + * Averages the values in a column of a list or database that match conditions you specify. + * + * Excel Function: + * DAVERAGE(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DAVERAGE($database,$field,$criteria) { @@ -134,8 +191,38 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::AVERAGE($colData); } // function DAVERAGE() + /** - * DCOUNT + * DCOUNT + * + * Counts the cells that contain numbers in a column of a list or database that match conditions + * that you specify. + * + * Excel Function: + * DCOUNT(database,[field],criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return integer + * + * @TODO The field argument is optional. If field is omitted, DCOUNT counts all records in the + * database that match the criteria. + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DCOUNT($database,$field,$criteria) { @@ -156,8 +243,37 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::COUNT($colData); } // function DCOUNT() + /** - * DCOUNTA + * DCOUNTA + * + * Counts the nonblank cells in a column of a list or database that match conditions that you specify. + * + * Excel Function: + * DCOUNTA(database,[field],criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return integer + * + * @TODO The field argument is optional. If field is omitted, DCOUNT counts all records in the + * database that match the criteria. + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DCOUNTA($database,$field,$criteria) { @@ -178,8 +294,35 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::COUNTA($colData); } // function DCOUNTA() + /** - * DGET + * DGET + * + * Extracts a single value from a column of a list or database that matches conditions that you + * specify. + * + * Excel Function: + * DGET(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return mixed + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DGET($database,$field,$criteria) { @@ -204,8 +347,35 @@ class PHPExcel_Calculation_Database { return $colData[0]; } // function DGET() + /** - * DMAX + * DMAX + * + * Returns the largest number in a column of a list or database that matches conditions you that + * specify. + * + * Excel Function: + * DMAX(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DMAX($database,$field,$criteria) { @@ -226,8 +396,35 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::MAX($colData); } // function DMAX() + /** - * DMIN + * DMIN + * + * Returns the smallest number in a column of a list or database that matches conditions you that + * specify. + * + * Excel Function: + * DMIN(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DMIN($database,$field,$criteria) { @@ -248,8 +445,34 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::MIN($colData); } // function DMIN() + /** - * DPRODUCT + * DPRODUCT + * + * Multiplies the values in a column of a list or database that match conditions that you specify. + * + * Excel Function: + * DPRODUCT(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DPRODUCT($database,$field,$criteria) { @@ -270,8 +493,35 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_MathTrig::PRODUCT($colData); } // function DPRODUCT() + /** - * DSTDEV + * DSTDEV + * + * Estimates the standard deviation of a population based on a sample by using the numbers in a + * column of a list or database that match conditions that you specify. + * + * Excel Function: + * DSTDEV(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DSTDEV($database,$field,$criteria) { @@ -292,8 +542,35 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::STDEV($colData); } // function DSTDEV() + /** - * DSTDEVP + * DSTDEVP + * + * Calculates the standard deviation of a population based on the entire population by using the + * numbers in a column of a list or database that match conditions that you specify. + * + * Excel Function: + * DSTDEVP(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DSTDEVP($database,$field,$criteria) { @@ -314,8 +591,34 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::STDEVP($colData); } // function DSTDEVP() + /** - * DSUM + * DSUM + * + * Adds the numbers in a column of a list or database that match conditions that you specify. + * + * Excel Function: + * DSUM(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DSUM($database,$field,$criteria) { @@ -336,8 +639,35 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_MathTrig::SUM($colData); } // function DSUM() + /** - * DVAR + * DVAR + * + * Estimates the variance of a population based on a sample by using the numbers in a column + * of a list or database that match conditions that you specify. + * + * Excel Function: + * DVAR(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DVAR($database,$field,$criteria) { @@ -358,8 +688,35 @@ class PHPExcel_Calculation_Database { return PHPExcel_Calculation_Statistical::VARFunc($colData); } // function DVAR() + /** - * DVARP + * DVARP + * + * Calculates the variance of a population based on the entire population by using the numbers + * in a column of a list or database that match conditions that you specify. + * + * Excel Function: + * DVARP(database,field,criteria) + * + * @access public + * @category Database Functions + * @param mixed[] $database The range of cells that makes up the list or database. + * A database is a list of related data in which rows of related + * information are records, and columns of data are fields. The + * first row of the list contains labels for each column. + * @param mixed[] $field Indicates which column is used in the function. Enter the + * column label enclosed between double quotation marks, such as + * "Age" or "Yield," or a number (without quotation marks) that + * represents the position of the column within the list: 1 for + * the first column, 2 for the second column, and so on. + * @param mixed[] $criteria The range of cells that contains the conditions you specify. + * You can use any range for the criteria argument, as long as it + * includes at least one column label and at least one cell below + * the column label in which you specify a condition for the + * column. + * @return float + * + * @TODO Numeric value in $field to reference a column position rather than a name. * */ public static function DVARP($database,$field,$criteria) { diff --git a/Classes/PHPExcel/Calculation/DateTime.php b/Classes/PHPExcel/Calculation/DateTime.php index e6c0befb..85313af6 100644 --- a/Classes/PHPExcel/Calculation/DateTime.php +++ b/Classes/PHPExcel/Calculation/DateTime.php @@ -45,6 +45,12 @@ if (!defined('PHPEXCEL_ROOT')) { */ class PHPExcel_Calculation_DateTime { + /** + * Identify if a year is a leap year or not + * + * @param integer $year The year to test + * @return boolean TRUE if the year is a leap year, otherwise FALSE + */ public static function _isLeapYear($year) { return ((($year % 4) == 0) && (($year % 100) != 0) || (($year % 400) == 0)); } // function _isLeapYear() @@ -82,7 +88,8 @@ class PHPExcel_Calculation_DateTime { */ public static function _getDateValue($dateValue) { if (!is_numeric($dateValue)) { - if ((is_string($dateValue)) && (PHPExcel_Calculation_Functions::getCompatibilityMode() == PHPExcel_Calculation_Functions::COMPATIBILITY_GNUMERIC)) { + if ((is_string($dateValue)) && + (PHPExcel_Calculation_Functions::getCompatibilityMode() == PHPExcel_Calculation_Functions::COMPATIBILITY_GNUMERIC)) { return PHPExcel_Calculation_Functions::VALUE(); } if ((is_object($dateValue)) && ($dateValue instanceof PHPExcel_Shared_Date::$dateTimeObjectType)) { @@ -142,6 +149,19 @@ class PHPExcel_Calculation_DateTime { /** * DATETIMENOW * + * Returns the current date and time. + * The NOW function is useful when you need to display the current date and time on a worksheet or + * calculate a value based on the current date and time, and have that value updated each time you + * open the worksheet. + * + * NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the date + * and time format of your regional settings. PHPExcel does not change cell formatting in this way. + * + * Excel Function: + * NOW() + * + * @access public + * @category Date/Time Functions * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, * depending on the value of the ReturnDateType flag */ @@ -169,6 +189,19 @@ class PHPExcel_Calculation_DateTime { /** * DATENOW * + * Returns the current date. + * The NOW function is useful when you need to display the current date and time on a worksheet or + * calculate a value based on the current date and time, and have that value updated each time you + * open the worksheet. + * + * NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the date + * and time format of your regional settings. PHPExcel does not change cell formatting in this way. + * + * Excel Function: + * TODAY() + * + * @access public + * @category Date/Time Functions * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, * depending on the value of the ReturnDateType flag */ @@ -197,9 +230,46 @@ class PHPExcel_Calculation_DateTime { /** * DATE * - * @param long $year - * @param long $month - * @param long $day + * The DATE function returns a value that represents a particular date. + * + * NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the date + * format of your regional settings. PHPExcel does not change cell formatting in this way. + * + * Excel Function: + * DATE(year,month,day) + * + * @access public + * @category Date/Time Functions + * @param int|mixed[] $year The value of the year argument can include one to four digits. + * Excel interprets the year argument according to the configured + * date system: 1900 or 1904. + * If year is between 0 (zero) and 1899 (inclusive), Excel adds that + * value to 1900 to calculate the year. For example, DATE(108,1,2) + * returns January 2, 2008 (1900+108). + * If year is between 1900 and 9999 (inclusive), Excel uses that + * value as the year. For example, DATE(2008,1,2) returns January 2, + * 2008. + * If year is less than 0 or is 10000 or greater, Excel returns the + * #NUM! error value. + * @param int|mixed[] $month A positive or negative integer representing the month of the year + * from 1 to 12 (January to December). + * If month is greater than 12, month adds that number of months to + * the first month in the year specified. For example, DATE(2008,14,2) + * returns the serial number representing February 2, 2009. + * If month is less than 1, month subtracts the magnitude of that + * number of months, plus 1, from the first month in the year + * specified. For example, DATE(2008,-3,2) returns the serial number + * representing September 2, 2007. + * @param int|mixed[] $day A positive or negative integer representing the day of the month + * from 1 to 31. + * If day is greater than the number of days in the month specified, + * day adds that number of days to the first day in the month. For + * example, DATE(2008,1,35) returns the serial number representing + * February 4, 2008. + * If day is less than 1, day subtracts the magnitude that number of + * days, plus one, from the first day of the month specified. For + * example, DATE(2008,1,-15) returns the serial number representing + * December 16, 2007. * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, * depending on the value of the ReturnDateType flag */ @@ -265,9 +335,27 @@ class PHPExcel_Calculation_DateTime { /** * TIME * - * @param long $hour - * @param long $minute - * @param long $second + * The TIME function returns a value that represents a particular time. + * + * NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the time + * format of your regional settings. PHPExcel does not change cell formatting in this way. + * + * Excel Function: + * TIME(hour,minute,second) + * + * @access public + * @category Date/Time Functions + * @param int|mixed[] $hour A number from 0 (zero) to 32767 representing the hour. + * Any value greater than 23 will be divided by 24 and the remainder + * will be treated as the hour value. For example, TIME(27,0,0) = + * TIME(3,0,0) = .125 or 3:00 AM. + * @param int|mixed[] $minute A number from 0 to 32767 representing the minute. + * Any value greater than 59 will be converted to hours and minutes. + * For example, TIME(0,750,0) = TIME(12,30,0) = .520833 or 12:30 PM. + * @param int|mixed[] $second A number from 0 to 32767 representing the second. + * Any value greater than 59 will be converted to hours, minutes, + * and seconds. For example, TIME(0,0,2000) = TIME(0,33,22) = .023148 + * or 12:33:20 AM * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, * depending on the value of the ReturnDateType flag */ @@ -343,7 +431,26 @@ class PHPExcel_Calculation_DateTime { /** * DATEVALUE * - * @param string $dateValue + * Returns a value that represents a particular date. + * Use DATEVALUE to convert a date represented by a text string to an Excel or PHP date/time stamp + * value. + * + * NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the date + * format of your regional settings. PHPExcel does not change cell formatting in this way. + * + * Excel Function: + * DATEVALUE(dateValue) + * + * @access public + * @category Date/Time Functions + * @param string $dateValue Text that represents a date in a Microsoft Excel date format. + * For example, "1/30/2008" or "30-Jan-2008" are text strings within + * quotation marks that represent dates. Using the default date + * system in Excel for Windows, date_text must represent a date from + * January 1, 1900, to December 31, 9999. Using the default date + * system in Excel for the Macintosh, date_text must represent a date + * from January 1, 1904, to December 31, 9999. DATEVALUE returns the + * #VALUE! error value if date_text is out of this range. * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, * depending on the value of the ReturnDateType flag */ @@ -430,7 +537,22 @@ class PHPExcel_Calculation_DateTime { /** * TIMEVALUE * - * @param string $timeValue + * Returns a value that represents a particular time. + * Use TIMEVALUE to convert a time represented by a text string to an Excel or PHP date/time stamp + * value. + * + * NOTE: When used in a Cell Formula, MS Excel changes the cell format so that it matches the time + * format of your regional settings. PHPExcel does not change cell formatting in this way. + * + * Excel Function: + * TIMEVALUE(timeValue) + * + * @access public + * @category Date/Time Functions + * @param string $timeValue A text string that represents a time in any one of the Microsoft + * Excel time formats; for example, "6:45 PM" and "18:45" text strings + * within quotation marks that represent time. + * Date information in time_text is ignored. * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, * depending on the value of the ReturnDateType flag */ @@ -462,10 +584,12 @@ class PHPExcel_Calculation_DateTime { /** * DATEDIF * - * @param long $startDate Excel date serial value or a standard date string - * @param long $endDate Excel date serial value or a standard date string + * @param mixed $startDate Excel date serial value, PHP date/time stamp, PHP DateTime object + * or a standard date string + * @param mixed $endDate Excel date serial value, PHP date/time stamp, PHP DateTime object + * or a standard date string * @param string $unit - * @return long Interval between the dates + * @return integer Interval between the dates */ public static function DATEDIF($startDate = 0, $endDate = 0, $unit = 'D') { $startDate = PHPExcel_Calculation_Functions::flattenSingleValue($startDate); @@ -559,10 +683,31 @@ class PHPExcel_Calculation_DateTime { /** * DAYS360 * - * @param long $startDate Excel date serial value or a standard date string - * @param long $endDate Excel date serial value or a standard date string - * @param boolean $method US or European Method - * @return long PHP date/time serial + * Returns the number of days between two dates based on a 360-day year (twelve 30-day months), + * which is used in some accounting calculations. Use this function to help compute payments if + * your accounting system is based on twelve 30-day months. + * + * Excel Function: + * DAYS360(startDate,endDate[,method]) + * + * @access public + * @category Date/Time Functions + * @param mixed $startDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param mixed $endDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param boolean $method US or European Method + * FALSE or omitted: U.S. (NASD) method. If the starting date is + * the last day of a month, it becomes equal to the 30th of the + * same month. If the ending date is the last day of a month and + * the starting date is earlier than the 30th of a month, the + * ending date becomes equal to the 1st of the next month; + * otherwise the ending date becomes equal to the 30th of the + * same month. + * TRUE: European method. Starting dates and ending dates that + * occur on the 31st of a month become equal to the 30th of the + * same month. + * @return integer Number of days between start date and end date */ public static function DAYS360($startDate = 0, $endDate = 0, $method = false) { $startDate = PHPExcel_Calculation_Functions::flattenSingleValue($startDate); @@ -593,12 +738,20 @@ class PHPExcel_Calculation_DateTime { /** * YEARFRAC * - * Calculates the fraction of the year represented by the number of whole days between two dates (the start_date and the - * end_date). Use the YEARFRAC worksheet function to identify the proportion of a whole year's benefits or obligations - * to assign to a specific term. + * Calculates the fraction of the year represented by the number of whole days between two dates + * (the start_date and the end_date). + * Use the YEARFRAC worksheet function to identify the proportion of a whole year's benefits or + * obligations to assign to a specific term. * - * @param mixed $startDate Excel date serial value (float), PHP date timestamp (integer) or date object, or a standard date string - * @param mixed $endDate Excel date serial value (float), PHP date timestamp (integer) or date object, or a standard date string + * Excel Function: + * YEARFRAC(startDate,endDate[,method]) + * + * @access public + * @category Date/Time Functions + * @param mixed $startDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param mixed $endDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string * @param integer $method Method used for the calculation * 0 or omitted US (NASD) 30/360 * 1 Actual/actual @@ -682,10 +835,25 @@ class PHPExcel_Calculation_DateTime { /** * NETWORKDAYS * - * @param mixed Start date - * @param mixed End date - * @param array of mixed Optional Date Series - * @return long Interval between the dates + * Returns the number of whole working days between start_date and end_date. Working days + * exclude weekends and any dates identified in holidays. + * Use NETWORKDAYS to calculate employee benefits that accrue based on the number of days + * worked during a specific term. + * + * Excel Function: + * NETWORKDAYS(startDate,endDate[,holidays[,holiday[,...]]]) + * + * @access public + * @category Date/Time Functions + * @param mixed $startDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param mixed $endDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param mixed $holidays,... Optional series of Excel date serial value (float), PHP date + * timestamp (integer), PHP DateTime object, or a standard date + * strings that will be excluded from the working calendar, such + * as state and federal holidays and floating holidays. + * @return integer Interval between the dates */ public static function NETWORKDAYS($startDate,$endDate) { // Retrieve the mandatory start and end date that are referenced in the function definition @@ -747,10 +915,27 @@ class PHPExcel_Calculation_DateTime { /** * WORKDAY * - * @param mixed Start date - * @param mixed number of days for adjustment - * @param array of mixed Optional Date Series - * @return long Interval between the dates + * Returns the date that is the indicated number of working days before or after a date (the + * starting date). Working days exclude weekends and any dates identified as holidays. + * Use WORKDAY to exclude weekends or holidays when you calculate invoice due dates, expected + * delivery times, or the number of days of work performed. + * + * Excel Function: + * WORKDAY(startDate,endDays[,holidays[,holiday[,...]]]) + * + * @access public + * @category Date/Time Functions + * @param mixed $startDate Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param integer $endDays The number of nonweekend and nonholiday days before or after + * startDate. A positive value for days yields a future date; a + * negative value yields a past date. + * @param mixed $holidays,... Optional series of Excel date serial value (float), PHP date + * timestamp (integer), PHP DateTime object, or a standard date + * strings that will be excluded from the working calendar, such + * as state and federal holidays and floating holidays. + * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, + * depending on the value of the ReturnDateType flag */ public static function WORKDAY($startDate,$endDays) { // Retrieve the mandatory start date and days that are referenced in the function definition @@ -845,8 +1030,15 @@ class PHPExcel_Calculation_DateTime { /** * DAYOFMONTH * - * @param long $dateValue Excel date serial value or a standard date string - * @return int Day + * Returns the day of the month, for a specified date. The day is given as an integer + * ranging from 1 to 31. + * + * Excel Function: + * DAY(dateValue) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @return int Day of the month */ public static function DAYOFMONTH($dateValue = 1) { $dateValue = PHPExcel_Calculation_Functions::flattenSingleValue($dateValue); @@ -869,8 +1061,19 @@ class PHPExcel_Calculation_DateTime { /** * DAYOFWEEK * - * @param long $dateValue Excel date serial value or a standard date string - * @return int Day + * Returns the day of the week for a specified date. The day is given as an integer + * ranging from 0 to 7 (dependent on the requested style). + * + * Excel Function: + * WEEKDAY(dateValue[,style]) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param int $style A number that determines the type of return value + * 1 or omitted Numbers 1 (Sunday) through 7 (Saturday). + * 2 Numbers 1 (Monday) through 7 (Sunday). + * 3 Numbers 0 (Monday) through 6 (Sunday). + * @return int Day of the week value */ public static function DAYOFWEEK($dateValue = 1, $style = 1) { $dateValue = PHPExcel_Calculation_Functions::flattenSingleValue($dateValue); @@ -921,8 +1124,21 @@ class PHPExcel_Calculation_DateTime { /** * WEEKOFYEAR * - * @param long $dateValue Excel date serial value or a standard date string + * Returns the week of the year for a specified date. + * The WEEKNUM function considers the week containing January 1 to be the first week of the year. + * However, there is a European standard that defines the first week as the one with the majority + * of days (four or more) falling in the new year. This means that for years in which there are + * three days or less in the first week of January, the WEEKNUM function returns week numbers + * that are incorrect according to the European standard. + * + * Excel Function: + * WEEKNUM(dateValue[,style]) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string * @param boolean $method Week begins on Sunday or Monday + * 1 or omitted Week begins on Sunday. + * 2 Week begins on Monday. * @return int Week Number */ public static function WEEKOFYEAR($dateValue = 1, $method = 1) { @@ -959,8 +1175,15 @@ class PHPExcel_Calculation_DateTime { /** * MONTHOFYEAR * - * @param long $dateValue Excel date serial value or a standard date string - * @return int Month + * Returns the month of a date represented by a serial number. + * The month is given as an integer, ranging from 1 (January) to 12 (December). + * + * Excel Function: + * MONTH(dateValue) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @return int Month of the year */ public static function MONTHOFYEAR($dateValue = 1) { $dateValue = PHPExcel_Calculation_Functions::flattenSingleValue($dateValue); @@ -981,7 +1204,14 @@ class PHPExcel_Calculation_DateTime { /** * YEAR * - * @param long $dateValue Excel date serial value or a standard date string + * Returns the year corresponding to a date. + * The year is returned as an integer in the range 1900-9999. + * + * Excel Function: + * YEAR(dateValue) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string * @return int Year */ public static function YEAR($dateValue = 1) { @@ -1003,7 +1233,14 @@ class PHPExcel_Calculation_DateTime { /** * HOUROFDAY * - * @param mixed $timeValue Excel time serial value or a standard time string + * Returns the hour of a time value. + * The hour is given as an integer, ranging from 0 (12:00 A.M.) to 23 (11:00 P.M.). + * + * Excel Function: + * HOUR(timeValue) + * + * @param mixed $timeValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard time string * @return int Hour */ public static function HOUROFDAY($timeValue = 0) { @@ -1036,7 +1273,14 @@ class PHPExcel_Calculation_DateTime { /** * MINUTEOFHOUR * - * @param long $timeValue Excel time serial value or a standard time string + * Returns the minutes of a time value. + * The minute is given as an integer, ranging from 0 to 59. + * + * Excel Function: + * MINUTE(timeValue) + * + * @param mixed $timeValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard time string * @return int Minute */ public static function MINUTEOFHOUR($timeValue = 0) { @@ -1069,7 +1313,14 @@ class PHPExcel_Calculation_DateTime { /** * SECONDOFMINUTE * - * @param long $timeValue Excel time serial value or a standard time string + * Returns the seconds of a time value. + * The second is given as an integer in the range 0 (zero) to 59. + * + * Excel Function: + * SECOND(timeValue) + * + * @param mixed $timeValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard time string * @return int Second */ public static function SECONDOFMINUTE($timeValue = 0) { @@ -1102,12 +1353,21 @@ class PHPExcel_Calculation_DateTime { /** * EDATE * - * Returns the serial number that represents the date that is the indicated number of months before or after a specified date - * (the start_date). Use EDATE to calculate maturity dates or due dates that fall on the same day of the month as the date of issue. + * Returns the serial number that represents the date that is the indicated number of months + * before or after a specified date (the start_date). + * Use EDATE to calculate maturity dates or due dates that fall on the same day of the month + * as the date of issue. * - * @param long $dateValue Excel date serial value or a standard date string - * @param int $adjustmentMonths Number of months to adjust by - * @return long Excel date serial value + * Excel Function: + * EDATE(dateValue,adjustmentMonths) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param int $adjustmentMonths The number of months before or after start_date. + * A positive value for months yields a future date; + * a negative value yields a past date. + * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, + * depending on the value of the ReturnDateType flag */ public static function EDATE($dateValue = 1, $adjustmentMonths = 0) { $dateValue = PHPExcel_Calculation_Functions::flattenSingleValue($dateValue); @@ -1139,12 +1399,20 @@ class PHPExcel_Calculation_DateTime { /** * EOMONTH * - * Returns the serial number for the last day of the month that is the indicated number of months before or after start_date. + * Returns the date value for the last day of the month that is the indicated number of months + * before or after start_date. * Use EOMONTH to calculate maturity dates or due dates that fall on the last day of the month. * - * @param long $dateValue Excel date serial value or a standard date string - * @param int $adjustmentMonths Number of months to adjust by - * @return long Excel date serial value + * Excel Function: + * EOMONTH(dateValue,adjustmentMonths) + * + * @param mixed $dateValue Excel date serial value (float), PHP date timestamp (integer), + * PHP DateTime object, or a standard date string + * @param int $adjustmentMonths The number of months before or after start_date. + * A positive value for months yields a future date; + * a negative value yields a past date. + * @return mixed Excel date/time serial value, PHP date/time serial value or PHP date/time object, + * depending on the value of the ReturnDateType flag */ public static function EOMONTH($dateValue = 1, $adjustmentMonths = 0) { $dateValue = PHPExcel_Calculation_Functions::flattenSingleValue($dateValue); diff --git a/Classes/PHPExcel/Calculation/Engineering.php b/Classes/PHPExcel/Calculation/Engineering.php index de0af755..0e5246cd 100644 --- a/Classes/PHPExcel/Calculation/Engineering.php +++ b/Classes/PHPExcel/Calculation/Engineering.php @@ -742,39 +742,49 @@ class PHPExcel_Calculation_Engineering { /** * BESSELI * - * Returns the modified Bessel function, which is equivalent to the Bessel function evaluated for purely imaginary arguments + * Returns the modified Bessel function, which is equivalent to the Bessel function evaluated for + * purely imaginary arguments + * + * Excel Function: + * BESSELI(x,ord) + * + * @access public + * @category Engineering Functions + * @param float $x The value at which to evaluate the function. + * If x is nonnumeric, BESSELI returns the #VALUE! error value. + * @param integer $ord The order of the Bessel function. If n is not an integer, it is truncated. + * If $ord is nonnumeric, BESSELI returns the #VALUE! error value. + * If $ord < 0, BESSELI returns the #NUM! error value. + * @return float * * @TODO Better handling of the approximation method to support the differences between Excel/Gnumeric and Open/Libre Office * - * @param float $x - * @param float $n - * @return float */ - public static function BESSELI($x, $n) { + public static function BESSELI($x, $ord) { $x = (is_null($x)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($x); - $n = (is_null($n)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($n); + $ord = (is_null($ord)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($ord); - if ((is_numeric($x)) && (is_numeric($n))) { - $n = floor($n); - if ($n < 0) { + if ((is_numeric($x)) && (is_numeric($ord))) { + $ord = floor($ord); + if ($ord < 0) { return PHPExcel_Calculation_Functions::NaN(); } if (abs($x) <= 30) { - $fResult = $fTerm = pow($x / 2, $n) / PHPExcel_Calculation_MathTrig::FACT($n); - $nK = 1; + $fResult = $fTerm = pow($x / 2, $ord) / PHPExcel_Calculation_MathTrig::FACT($ord); + $ordK = 1; $fSqrX = ($x * $x) / 4; do { $fTerm *= $fSqrX; - $fTerm /= ($nK * ($nK + $n)); + $fTerm /= ($ordK * ($ordK + $ord)); $fResult += $fTerm; - } while ((abs($fTerm) > 1e-12) && (++$nK < 100)); + } while ((abs($fTerm) > 1e-12) && (++$ordK < 100)); } else { $f_2_PI = 2 * M_PI; $fXAbs = abs($x); $fResult = exp($fXAbs) / sqrt($f_2_PI * $fXAbs); - if (($n & 1) && ($x < 0)) { + if (($ord & 1) && ($x < 0)) { $fResult = -$fResult; } } @@ -789,39 +799,48 @@ class PHPExcel_Calculation_Engineering { * * Returns the Bessel function * + * Excel Function: + * BESSELJ(x,ord) + * + * @access public + * @category Engineering Functions + * @param float $x The value at which to evaluate the function. + * If x is nonnumeric, BESSELJ returns the #VALUE! error value. + * @param integer $ord The order of the Bessel function. If n is not an integer, it is truncated. + * If $ord is nonnumeric, BESSELJ returns the #VALUE! error value. + * If $ord < 0, BESSELJ returns the #NUM! error value. + * @return float + * * @TODO Better handling of the approximation method to support the differences between Excel/Gnumeric and Open/Libre Office * - * @param float $x - * @param float $n - * @return float */ - public static function BESSELJ($x, $n) { + public static function BESSELJ($x, $ord) { $x = (is_null($x)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($x); - $n = (is_null($n)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($n); + $ord = (is_null($ord)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($ord); - if ((is_numeric($x)) && (is_numeric($n))) { - $n = floor($n); - if ($n < 0) { + if ((is_numeric($x)) && (is_numeric($ord))) { + $ord = floor($ord); + if ($ord < 0) { return PHPExcel_Calculation_Functions::NaN(); } $fResult = 0; if (abs($x) <= 30) { - $fResult = $fTerm = pow($x / 2, $n) / PHPExcel_Calculation_MathTrig::FACT($n); - $nK = 1; + $fResult = $fTerm = pow($x / 2, $ord) / PHPExcel_Calculation_MathTrig::FACT($ord); + $ordK = 1; $fSqrX = ($x * $x) / -4; do { $fTerm *= $fSqrX; - $fTerm /= ($nK * ($nK + $n)); + $fTerm /= ($ordK * ($ordK + $ord)); $fResult += $fTerm; - } while ((abs($fTerm) > 1e-12) && (++$nK < 100)); + } while ((abs($fTerm) > 1e-12) && (++$ordK < 100)); } else { $f_PI_DIV_2 = M_PI / 2; $f_PI_DIV_4 = M_PI / 4; $fXAbs = abs($x); - $fResult = sqrt(M_2DIVPI / $fXAbs) * cos($fXAbs - $n * $f_PI_DIV_2 - $f_PI_DIV_4); - if (($n & 1) && ($x < 0)) { + $fResult = sqrt(M_2DIVPI / $fXAbs) * cos($fXAbs - $ord * $f_PI_DIV_2 - $f_PI_DIV_4); + if (($ord & 1) && ($x < 0)) { $fResult = -$fResult; } } @@ -868,11 +887,23 @@ class PHPExcel_Calculation_Engineering { /** * BESSELK * - * Returns the modified Bessel function, which is equivalent to the Bessel functions evaluated for purely imaginary arguments. + * Returns the modified Bessel function, which is equivalent to the Bessel functions evaluated + * for purely imaginary arguments. * - * @param float $x - * @param float $ord + * Excel Function: + * BESSELK(x,ord) + * + * @access public + * @category Engineering Functions + * @param float $x The value at which to evaluate the function. + * If x is nonnumeric, BESSELK returns the #VALUE! error value. + * @param integer $ord The order of the Bessel function. If n is not an integer, it is truncated. + * If $ord is nonnumeric, BESSELK returns the #VALUE! error value. + * If $ord < 0, BESSELK returns the #NUM! error value. * @return float + * + * @TODO Better handling of the approximation method to support the differences between Excel/Gnumeric and Open/Libre Office + * */ public static function BESSELK($x, $ord) { $x = (is_null($x)) ? 0.0 : PHPExcel_Calculation_Functions::flattenSingleValue($x); @@ -948,8 +979,19 @@ class PHPExcel_Calculation_Engineering { * * Returns the Bessel function, which is also called the Weber function or the Neumann function. * - * @param float $x - * @param float $n + * Excel Function: + * BESSELY(x,ord) + * + * @access public + * @category Engineering Functions + * @param float $x The value at which to evaluate the function. + * If x is nonnumeric, BESSELK returns the #VALUE! error value. + * @param integer $ord The order of the Bessel function. If n is not an integer, it is truncated. + * If $ord is nonnumeric, BESSELK returns the #VALUE! error value. + * If $ord < 0, BESSELK returns the #NUM! error value. + * + * @TODO Better handling of the approximation method to support the differences between Excel/Gnumeric and Open/Libre Office + * * @return float */ public static function BESSELY($x, $ord) { @@ -984,9 +1026,19 @@ class PHPExcel_Calculation_Engineering { /** * BINTODEC * - * Return a binary value as Decimal. + * Return a binary value as decimal. * - * @param string $x + * Excel Function: + * BIN2DEC(x) + * + * @access public + * @category Engineering Functions + * @param string $x The binary number (as a string) that you want to convert. The number + * cannot contain more than 10 characters (10 bits). The most significant + * bit of number is the sign bit. The remaining 9 bits are magnitude bits. + * Negative numbers are represented using two's-complement notation. + * If number is not a valid binary number, or if number contains more than + * 10 characters (10 bits), BIN2DEC returns the #NUM! error value. * @return string */ public static function BINTODEC($x) { @@ -1020,12 +1072,28 @@ class PHPExcel_Calculation_Engineering { /** * BINTOHEX * - * Return a binary value as Hex. + * Return a binary value as hex. * - * @param string $x + * Excel Function: + * BIN2HEX(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The binary number (as a string) that you want to convert. The number + * cannot contain more than 10 characters (10 bits). The most significant + * bit of number is the sign bit. The remaining 9 bits are magnitude bits. + * Negative numbers are represented using two's-complement notation. + * If number is not a valid binary number, or if number contains more than + * 10 characters (10 bits), BIN2HEX returns the #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, BIN2HEX uses the + * minimum number of characters necessary. Places is useful for padding the + * return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, BIN2HEX returns the #VALUE! error value. + * If places is negative, BIN2HEX returns the #NUM! error value. * @return string */ - public static function BINTOHEX($x, $places=null) { + public static function BINTOHEX($x, $places=NULL) { $x = PHPExcel_Calculation_Functions::flattenSingleValue($x); $places = PHPExcel_Calculation_Functions::flattenSingleValue($places); @@ -1058,12 +1126,28 @@ class PHPExcel_Calculation_Engineering { /** * BINTOOCT * - * Return a binary value as Octal. + * Return a binary value as octal. * - * @param string $x + * Excel Function: + * BIN2OCT(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The binary number (as a string) that you want to convert. The number + * cannot contain more than 10 characters (10 bits). The most significant + * bit of number is the sign bit. The remaining 9 bits are magnitude bits. + * Negative numbers are represented using two's-complement notation. + * If number is not a valid binary number, or if number contains more than + * 10 characters (10 bits), BIN2OCT returns the #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, BIN2OCT uses the + * minimum number of characters necessary. Places is useful for padding the + * return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, BIN2OCT returns the #VALUE! error value. + * If places is negative, BIN2OCT returns the #NUM! error value. * @return string */ - public static function BINTOOCT($x, $places=null) { + public static function BINTOOCT($x, $places=NULL) { $x = PHPExcel_Calculation_Functions::flattenSingleValue($x); $places = PHPExcel_Calculation_Functions::flattenSingleValue($places); @@ -1096,12 +1180,32 @@ class PHPExcel_Calculation_Engineering { /** * DECTOBIN * - * Return an octal value as binary. + * Return a decimal value as binary. * - * @param string $x + * Excel Function: + * DEC2BIN(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The decimal integer you want to convert. If number is negative, + * valid place values are ignored and DEC2BIN returns a 10-character + * (10-bit) binary number in which the most significant bit is the sign + * bit. The remaining 9 bits are magnitude bits. Negative numbers are + * represented using two's-complement notation. + * If number < -512 or if number > 511, DEC2BIN returns the #NUM! error + * value. + * If number is nonnumeric, DEC2BIN returns the #VALUE! error value. + * If DEC2BIN requires more than places characters, it returns the #NUM! + * error value. + * @param integer $places The number of characters to use. If places is omitted, DEC2BIN uses + * the minimum number of characters necessary. Places is useful for + * padding the return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, DEC2BIN returns the #VALUE! error value. + * If places is zero or negative, DEC2BIN returns the #NUM! error value. * @return string */ - public static function DECTOBIN($x, $places=null) { + public static function DECTOBIN($x, $places=NULL) { $x = PHPExcel_Calculation_Functions::flattenSingleValue($x); $places = PHPExcel_Calculation_Functions::flattenSingleValue($places); @@ -1132,9 +1236,29 @@ class PHPExcel_Calculation_Engineering { /** * DECTOHEX * - * Return an octal value as binary. + * Return a decimal value as hex. * - * @param string $x + * Excel Function: + * DEC2HEX(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The decimal integer you want to convert. If number is negative, + * places is ignored and DEC2HEX returns a 10-character (40-bit) + * hexadecimal number in which the most significant bit is the sign + * bit. The remaining 39 bits are magnitude bits. Negative numbers + * are represented using two's-complement notation. + * If number < -549,755,813,888 or if number > 549,755,813,887, + * DEC2HEX returns the #NUM! error value. + * If number is nonnumeric, DEC2HEX returns the #VALUE! error value. + * If DEC2HEX requires more than places characters, it returns the + * #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, DEC2HEX uses + * the minimum number of characters necessary. Places is useful for + * padding the return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, DEC2HEX returns the #VALUE! error value. + * If places is zero or negative, DEC2HEX returns the #NUM! error value. * @return string */ public static function DECTOHEX($x, $places=null) { @@ -1166,9 +1290,29 @@ class PHPExcel_Calculation_Engineering { /** * DECTOOCT * - * Return an octal value as binary. + * Return an decimal value as octal. * - * @param string $x + * Excel Function: + * DEC2OCT(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The decimal integer you want to convert. If number is negative, + * places is ignored and DEC2OCT returns a 10-character (30-bit) + * octal number in which the most significant bit is the sign bit. + * The remaining 29 bits are magnitude bits. Negative numbers are + * represented using two's-complement notation. + * If number < -536,870,912 or if number > 536,870,911, DEC2OCT + * returns the #NUM! error value. + * If number is nonnumeric, DEC2OCT returns the #VALUE! error value. + * If DEC2OCT requires more than places characters, it returns the + * #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, DEC2OCT uses + * the minimum number of characters necessary. Places is useful for + * padding the return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, DEC2OCT returns the #VALUE! error value. + * If places is zero or negative, DEC2OCT returns the #NUM! error value. * @return string */ public static function DECTOOCT($x, $places=null) { @@ -1202,7 +1346,30 @@ class PHPExcel_Calculation_Engineering { * * Return a hex value as binary. * - * @param string $x + * Excel Function: + * HEX2BIN(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x the hexadecimal number you want to convert. Number cannot + * contain more than 10 characters. The most significant bit of + * number is the sign bit (40th bit from the right). The remaining + * 9 bits are magnitude bits. Negative numbers are represented + * using two's-complement notation. + * If number is negative, HEX2BIN ignores places and returns a + * 10-character binary number. + * If number is negative, it cannot be less than FFFFFFFE00, and + * if number is positive, it cannot be greater than 1FF. + * If number is not a valid hexadecimal number, HEX2BIN returns + * the #NUM! error value. + * If HEX2BIN requires more than places characters, it returns + * the #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, + * HEX2BIN uses the minimum number of characters necessary. Places + * is useful for padding the return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, HEX2BIN returns the #VALUE! error value. + * If places is negative, HEX2BIN returns the #NUM! error value. * @return string */ public static function HEXTOBIN($x, $places=null) { @@ -1225,9 +1392,20 @@ class PHPExcel_Calculation_Engineering { /** * HEXTODEC * - * Return a hex value as octal. + * Return a hex value as decimal. * - * @param string $x + * Excel Function: + * HEX2DEC(x) + * + * @access public + * @category Engineering Functions + * @param string $x The hexadecimal number you want to convert. This number cannot + * contain more than 10 characters (40 bits). The most significant + * bit of number is the sign bit. The remaining 39 bits are magnitude + * bits. Negative numbers are represented using two's-complement + * notation. + * If number is not a valid hexadecimal number, HEX2DEC returns the + * #NUM! error value. * @return string */ public static function HEXTODEC($x) { @@ -1249,7 +1427,31 @@ class PHPExcel_Calculation_Engineering { * * Return a hex value as octal. * - * @param string $x + * Excel Function: + * HEX2OCT(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The hexadecimal number you want to convert. Number cannot + * contain more than 10 characters. The most significant bit of + * number is the sign bit. The remaining 39 bits are magnitude + * bits. Negative numbers are represented using two's-complement + * notation. + * If number is negative, HEX2OCT ignores places and returns a + * 10-character octal number. + * If number is negative, it cannot be less than FFE0000000, and + * if number is positive, it cannot be greater than 1FFFFFFF. + * If number is not a valid hexadecimal number, HEX2OCT returns + * the #NUM! error value. + * If HEX2OCT requires more than places characters, it returns + * the #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, HEX2OCT + * uses the minimum number of characters necessary. Places is + * useful for padding the return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, HEX2OCT returns the #VALUE! error + * value. + * If places is negative, HEX2OCT returns the #NUM! error value. * @return string */ public static function HEXTOOCT($x, $places=null) { @@ -1274,7 +1476,33 @@ class PHPExcel_Calculation_Engineering { * * Return an octal value as binary. * - * @param string $x + * Excel Function: + * OCT2BIN(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The octal number you want to convert. Number may not + * contain more than 10 characters. The most significant + * bit of number is the sign bit. The remaining 29 bits + * are magnitude bits. Negative numbers are represented + * using two's-complement notation. + * If number is negative, OCT2BIN ignores places and returns + * a 10-character binary number. + * If number is negative, it cannot be less than 7777777000, + * and if number is positive, it cannot be greater than 777. + * If number is not a valid octal number, OCT2BIN returns + * the #NUM! error value. + * If OCT2BIN requires more than places characters, it + * returns the #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, + * OCT2BIN uses the minimum number of characters necessary. + * Places is useful for padding the return value with + * leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, OCT2BIN returns the #VALUE! + * error value. + * If places is negative, OCT2BIN returns the #NUM! error + * value. * @return string */ public static function OCTTOBIN($x, $places=null) { @@ -1297,9 +1525,20 @@ class PHPExcel_Calculation_Engineering { /** * OCTTODEC * - * Return an octal value as binary. + * Return an octal value as decimal. * - * @param string $x + * Excel Function: + * OCT2DEC(x) + * + * @access public + * @category Engineering Functions + * @param string $x The octal number you want to convert. Number may not contain + * more than 10 octal characters (30 bits). The most significant + * bit of number is the sign bit. The remaining 29 bits are + * magnitude bits. Negative numbers are represented using + * two's-complement notation. + * If number is not a valid octal number, OCT2DEC returns the + * #NUM! error value. * @return string */ public static function OCTTODEC($x) { @@ -1321,7 +1560,28 @@ class PHPExcel_Calculation_Engineering { * * Return an octal value as hex. * - * @param string $x + * Excel Function: + * OCT2HEX(x[,places]) + * + * @access public + * @category Engineering Functions + * @param string $x The octal number you want to convert. Number may not contain + * more than 10 octal characters (30 bits). The most significant + * bit of number is the sign bit. The remaining 29 bits are + * magnitude bits. Negative numbers are represented using + * two's-complement notation. + * If number is negative, OCT2HEX ignores places and returns a + * 10-character hexadecimal number. + * If number is not a valid octal number, OCT2HEX returns the + * #NUM! error value. + * If OCT2HEX requires more than places characters, it returns + * the #NUM! error value. + * @param integer $places The number of characters to use. If places is omitted, OCT2HEX + * uses the minimum number of characters necessary. Places is useful + * for padding the return value with leading 0s (zeros). + * If places is not an integer, it is truncated. + * If places is nonnumeric, OCT2HEX returns the #VALUE! error value. + * If places is negative, OCT2HEX returns the #NUM! error value. * @return string */ public static function OCTTOHEX($x, $places=null) { @@ -1664,6 +1924,7 @@ 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 * @return string */ public static function IMPOWER($complexNumber,$realNumber) {