[Summary view]

Differences Between: [Versions 400 and 401]

   1  <?php
   2  
   3  namespace PhpOffice\PhpSpreadsheet\Calculation\MathTrig;
   4  
   5  use PhpOffice\PhpSpreadsheet\Calculation\ArrayEnabled;
   6  use PhpOffice\PhpSpreadsheet\Calculation\Exception;
   7  use PhpOffice\PhpSpreadsheet\Calculation\Information\ExcelError;
   8  
   9  class Round
  10  {
  11      use ArrayEnabled;
  12  
  13      /**
  14       * ROUND.
  15       *
  16       * Returns the result of builtin function round after validating args.
  17       *
  18       * @param mixed $number Should be numeric, or can be an array of numbers
  19       * @param mixed $precision Should be int, or can be an array of numbers
  20       *
  21       * @return array|float|string Rounded number
  22       *         If an array of numbers is passed as the argument, then the returned result will also be an array
  23       *            with the same dimensions
  24       */
  25      public static function round($number, $precision)
  26      {
  27          if (is_array($number) || is_array($precision)) {
  28              return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $precision);
  29          }
  30  
  31          try {
  32              $number = Helpers::validateNumericNullBool($number);
  33              $precision = Helpers::validateNumericNullBool($precision);
  34          } catch (Exception $e) {
  35              return $e->getMessage();
  36          }
  37  
  38          return round($number, (int) $precision);
  39      }
  40  
  41      /**
  42       * ROUNDUP.
  43       *
  44       * Rounds a number up to a specified number of decimal places
  45       *
  46       * @param array|float $number Number to round, or can be an array of numbers
  47       * @param array|int $digits Number of digits to which you want to round $number, or can be an array of numbers
  48       *
  49       * @return array|float|string Rounded Number, or a string containing an error
  50       *         If an array of numbers is passed as the argument, then the returned result will also be an array
  51       *            with the same dimensions
  52       */
  53      public static function up($number, $digits)
  54      {
  55          if (is_array($number) || is_array($digits)) {
  56              return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $digits);
  57          }
  58  
  59          try {
  60              $number = Helpers::validateNumericNullBool($number);
  61              $digits = (int) Helpers::validateNumericNullSubstitution($digits, null);
  62          } catch (Exception $e) {
  63              return $e->getMessage();
  64          }
  65  
  66          if ($number == 0.0) {
  67              return 0.0;
  68          }
  69  
  70          if ($number < 0.0) {
  71              return round($number - 0.5 * 0.1 ** $digits, $digits, PHP_ROUND_HALF_DOWN);
  72          }
  73  
  74          return round($number + 0.5 * 0.1 ** $digits, $digits, PHP_ROUND_HALF_DOWN);
  75      }
  76  
  77      /**
  78       * ROUNDDOWN.
  79       *
  80       * Rounds a number down to a specified number of decimal places
  81       *
  82       * @param array|float $number Number to round, or can be an array of numbers
  83       * @param array|int $digits Number of digits to which you want to round $number, or can be an array of numbers
  84       *
  85       * @return array|float|string Rounded Number, or a string containing an error
  86       *         If an array of numbers is passed as the argument, then the returned result will also be an array
  87       *            with the same dimensions
  88       */
  89      public static function down($number, $digits)
  90      {
  91          if (is_array($number) || is_array($digits)) {
  92              return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $digits);
  93          }
  94  
  95          try {
  96              $number = Helpers::validateNumericNullBool($number);
  97              $digits = (int) Helpers::validateNumericNullSubstitution($digits, null);
  98          } catch (Exception $e) {
  99              return $e->getMessage();
 100          }
 101  
 102          if ($number == 0.0) {
 103              return 0.0;
 104          }
 105  
 106          if ($number < 0.0) {
 107              return round($number + 0.5 * 0.1 ** $digits, $digits, PHP_ROUND_HALF_UP);
 108          }
 109  
 110          return round($number - 0.5 * 0.1 ** $digits, $digits, PHP_ROUND_HALF_UP);
 111      }
 112  
 113      /**
 114       * MROUND.
 115       *
 116       * Rounds a number to the nearest multiple of a specified value
 117       *
 118       * @param mixed $number Expect float. Number to round, or can be an array of numbers
 119       * @param mixed $multiple Expect int. Multiple to which you want to round, or can be an array of numbers.
 120       *
 121       * @return array|float|string Rounded Number, or a string containing an error
 122       *         If an array of numbers is passed as the argument, then the returned result will also be an array
 123       *            with the same dimensions
 124       */
 125      public static function multiple($number, $multiple)
 126      {
 127          if (is_array($number) || is_array($multiple)) {
 128              return self::evaluateArrayArguments([self::class, __FUNCTION__], $number, $multiple);
 129          }
 130  
 131          try {
 132              $number = Helpers::validateNumericNullSubstitution($number, 0);
 133              $multiple = Helpers::validateNumericNullSubstitution($multiple, null);
 134          } catch (Exception $e) {
 135              return $e->getMessage();
 136          }
 137  
 138          if ($number == 0 || $multiple == 0) {
 139              return 0;
 140          }
 141          if ((Helpers::returnSign($number)) == (Helpers::returnSign($multiple))) {
 142              $multiplier = 1 / $multiple;
 143  
 144              return round($number * $multiplier) / $multiplier;
 145          }
 146  
 147          return ExcelError::NAN();
 148      }
 149  
 150      /**
 151       * EVEN.
 152       *
 153       * Returns number rounded up to the nearest even integer.
 154       * You can use this function for processing items that come in twos. For example,
 155       *        a packing crate accepts rows of one or two items. The crate is full when
 156       *        the number of items, rounded up to the nearest two, matches the crate's
 157       *        capacity.
 158       *
 159       * Excel Function:
 160       *        EVEN(number)
 161       *
 162       * @param array|float $number Number to round, or can be an array of numbers
 163       *
 164       * @return array|float|string Rounded Number, or a string containing an error
 165       *         If an array of numbers is passed as the argument, then the returned result will also be an array
 166       *            with the same dimensions
 167       */
 168      public static function even($number)
 169      {
 170          if (is_array($number)) {
 171              return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $number);
 172          }
 173  
 174          try {
 175              $number = Helpers::validateNumericNullBool($number);
 176          } catch (Exception $e) {
 177              return $e->getMessage();
 178          }
 179  
 180          return Helpers::getEven($number);
 181      }
 182  
 183      /**
 184       * ODD.
 185       *
 186       * Returns number rounded up to the nearest odd integer.
 187       *
 188       * @param array|float $number Number to round, or can be an array of numbers
 189       *
 190       * @return array|float|string Rounded Number, or a string containing an error
 191       *         If an array of numbers is passed as the argument, then the returned result will also be an array
 192       *            with the same dimensions
 193       */
 194      public static function odd($number)
 195      {
 196          if (is_array($number)) {
 197              return self::evaluateSingleArgumentArray([self::class, __FUNCTION__], $number);
 198          }
 199  
 200          try {
 201              $number = Helpers::validateNumericNullBool($number);
 202          } catch (Exception $e) {
 203              return $e->getMessage();
 204          }
 205  
 206          $significance = Helpers::returnSign($number);
 207          if ($significance == 0) {
 208              return 1;
 209          }
 210  
 211          $result = ceil($number / $significance) * $significance;
 212          if ($result == Helpers::getEven($result)) {
 213              $result += $significance;
 214          }
 215  
 216          return $result;
 217      }
 218  }