From 42ecc270ecfb85ea7c419481cd3622be2e6d1e7e Mon Sep 17 00:00:00 2001
From: Mark Baker <mark@lange.demon.co.uk>
Date: Sat, 13 Feb 2021 15:35:07 +0100
Subject: [PATCH] Extract Permutation functions from the Statistical class into
 a dedicated Permutations class (#1851)

* Extract Permutation functions from the Statistical class into a dedicated Permutations class

Retain the original methods in the Statistical class as stubs for BC, but deprecate them. They will be removed for PHPSpreadsheet v2

Note that unit tests still point to the Statistical class stubs; these should be modified to use the Permutations class directly when the stubs are removed

Also provided a basic implementationof the PERMUTATIONA() Function
---
 CHANGELOG.md                                  |  1 +
 .../Calculation/Calculation.php               |  4 +-
 .../Calculation/Statistical.php               | 16 +----
 .../Calculation/Statistical/Permutations.php  | 69 +++++++++++++++++++
 .../Statistical/PermutationATest.php          | 31 +++++++++
 tests/data/Calculation/Statistical/PERMUT.php |  4 ++
 .../Calculation/Statistical/PERMUTATIONA.php  | 28 ++++++++
 7 files changed, 138 insertions(+), 15 deletions(-)
 create mode 100644 src/PhpSpreadsheet/Calculation/Statistical/Permutations.php
 create mode 100644 tests/PhpSpreadsheetTests/Calculation/Functions/Statistical/PermutationATest.php
 create mode 100644 tests/data/Calculation/Statistical/PERMUTATIONA.php

diff --git a/CHANGELOG.md b/CHANGELOG.md
index eb49b512..ddfd2fc3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 
 - Implemented DataBar for conditional formatting in Xlsx, providing read/write and creation of (type, value, direction, fills, border, axis position, color settings) as DataBar options in Excel. [#1754](https://github.com/PHPOffice/PhpSpreadsheet/pull/1754)
 - Alignment for ODS Writer [#1796](https://github.com/PHPOffice/PhpSpreadsheet/issues/1796)
+- Basic implementation of the PERMUTATIONA() Statistical Function
 
 ### Changed
 
diff --git a/src/PhpSpreadsheet/Calculation/Calculation.php b/src/PhpSpreadsheet/Calculation/Calculation.php
index 537b9372..0ef11aa0 100644
--- a/src/PhpSpreadsheet/Calculation/Calculation.php
+++ b/src/PhpSpreadsheet/Calculation/Calculation.php
@@ -1932,12 +1932,12 @@ class Calculation
         ],
         'PERMUT' => [
             'category' => Category::CATEGORY_STATISTICAL,
-            'functionCall' => [Statistical::class, 'PERMUT'],
+            'functionCall' => [Statistical\Permutations::class, 'PERMUT'],
             'argumentCount' => '2',
         ],
         'PERMUTATIONA' => [
             'category' => Category::CATEGORY_STATISTICAL,
-            'functionCall' => [Functions::class, 'DUMMY'],
+            'functionCall' => [Statistical\Permutations::class, 'PERMUTATIONA'],
             'argumentCount' => '2',
         ],
         'PHONETIC' => [
diff --git a/src/PhpSpreadsheet/Calculation/Statistical.php b/src/PhpSpreadsheet/Calculation/Statistical.php
index 601dafa0..5792b78f 100644
--- a/src/PhpSpreadsheet/Calculation/Statistical.php
+++ b/src/PhpSpreadsheet/Calculation/Statistical.php
@@ -2923,6 +2923,8 @@ class Statistical
      *        combinations, for which the internal order is not significant. Use this function
      *        for lottery-style probability calculations.
      *
+     * @Deprecated 2.0.0 Use the PERMUT() method in the Statistical\Permutations class instead
+     *
      * @param int $numObjs Number of different objects
      * @param int $numInSet Number of objects in each permutation
      *
@@ -2930,19 +2932,7 @@ class Statistical
      */
     public static function PERMUT($numObjs, $numInSet)
     {
-        $numObjs = Functions::flattenSingleValue($numObjs);
-        $numInSet = Functions::flattenSingleValue($numInSet);
-
-        if ((is_numeric($numObjs)) && (is_numeric($numInSet))) {
-            $numInSet = floor($numInSet);
-            if ($numObjs < $numInSet) {
-                return Functions::NAN();
-            }
-
-            return round(MathTrig::FACT($numObjs) / MathTrig::FACT($numObjs - $numInSet));
-        }
-
-        return Functions::VALUE();
+        return Statistical\Permutations::PERMUT($numObjs, $numInSet);
     }
 
     /**
diff --git a/src/PhpSpreadsheet/Calculation/Statistical/Permutations.php b/src/PhpSpreadsheet/Calculation/Statistical/Permutations.php
new file mode 100644
index 00000000..84c10719
--- /dev/null
+++ b/src/PhpSpreadsheet/Calculation/Statistical/Permutations.php
@@ -0,0 +1,69 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheet\Calculation\Statistical;
+
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+use PhpOffice\PhpSpreadsheet\Calculation\MathTrig;
+
+class Permutations
+{
+    /**
+     * PERMUT.
+     *
+     * Returns the number of permutations for a given number of objects that can be
+     *        selected from number objects. A permutation is any set or subset of objects or
+     *        events where internal order is significant. Permutations are different from
+     *        combinations, for which the internal order is not significant. Use this function
+     *        for lottery-style probability calculations.
+     *
+     * @param int $numObjs Number of different objects
+     * @param int $numInSet Number of objects in each permutation
+     *
+     * @return int|string Number of permutations, or a string containing an error
+     */
+    public static function PERMUT($numObjs, $numInSet)
+    {
+        $numObjs = Functions::flattenSingleValue($numObjs);
+        $numInSet = Functions::flattenSingleValue($numInSet);
+
+        if ((is_numeric($numObjs)) && (is_numeric($numInSet))) {
+            $numInSet = floor($numInSet);
+            if ($numObjs < $numInSet) {
+                return Functions::NAN();
+            }
+
+            return round(MathTrig::FACT($numObjs) / MathTrig::FACT($numObjs - $numInSet));
+        }
+
+        return Functions::VALUE();
+    }
+
+    /**
+     * PERMUTATIONA.
+     *
+     * Returns the number of permutations for a given number of objects (with repetitions)
+     *     that can be selected from the total objects.
+     *
+     * @param int $numObjs Number of different objects
+     * @param int $numInSet Number of objects in each permutation
+     *
+     * @return int|string Number of permutations, or a string containing an error
+     */
+    public static function PERMUTATIONA($numObjs, $numInSet)
+    {
+        $numObjs = Functions::flattenSingleValue($numObjs);
+        $numInSet = Functions::flattenSingleValue($numInSet);
+
+        if ((is_numeric($numObjs)) && (is_numeric($numInSet))) {
+            $numObjs = floor($numObjs);
+            $numInSet = floor($numInSet);
+            if ($numObjs < 0 || $numInSet < 0) {
+                return Functions::NAN();
+            }
+
+            return $numObjs ** $numInSet;
+        }
+
+        return Functions::VALUE();
+    }
+}
diff --git a/tests/PhpSpreadsheetTests/Calculation/Functions/Statistical/PermutationATest.php b/tests/PhpSpreadsheetTests/Calculation/Functions/Statistical/PermutationATest.php
new file mode 100644
index 00000000..8a256ae8
--- /dev/null
+++ b/tests/PhpSpreadsheetTests/Calculation/Functions/Statistical/PermutationATest.php
@@ -0,0 +1,31 @@
+<?php
+
+namespace PhpOffice\PhpSpreadsheetTests\Calculation\Functions\Statistical;
+
+use PhpOffice\PhpSpreadsheet\Calculation\Functions;
+use PhpOffice\PhpSpreadsheet\Calculation\Statistical\Permutations;
+use PHPUnit\Framework\TestCase;
+
+class PermutationATest extends TestCase
+{
+    protected function setUp(): void
+    {
+        Functions::setCompatibilityMode(Functions::COMPATIBILITY_EXCEL);
+    }
+
+    /**
+     * @dataProvider providerPERMUT
+     *
+     * @param mixed $expectedResult
+     */
+    public function testPERMUT($expectedResult, ...$args): void
+    {
+        $result = Permutations::PERMUTATIONA(...$args);
+        self::assertEqualsWithDelta($expectedResult, $result, 1E-12);
+    }
+
+    public function providerPERMUT()
+    {
+        return require 'tests/data/Calculation/Statistical/PERMUTATIONA.php';
+    }
+}
diff --git a/tests/data/Calculation/Statistical/PERMUT.php b/tests/data/Calculation/Statistical/PERMUT.php
index 47be16ca..80b3a93d 100644
--- a/tests/data/Calculation/Statistical/PERMUT.php
+++ b/tests/data/Calculation/Statistical/PERMUT.php
@@ -45,6 +45,10 @@ return [
         10068347520,
         49, 6,
     ],
+    [
+        '#NUM!',
+        2, 3,
+    ],
     [
         '#NUM!',
         1, 2,
diff --git a/tests/data/Calculation/Statistical/PERMUTATIONA.php b/tests/data/Calculation/Statistical/PERMUTATIONA.php
new file mode 100644
index 00000000..6bc118b3
--- /dev/null
+++ b/tests/data/Calculation/Statistical/PERMUTATIONA.php
@@ -0,0 +1,28 @@
+<?php
+
+return [
+    [
+        5,
+        5, 1,
+    ],
+    [
+        2,
+        2.2, 1.1,
+    ],
+    [
+        5,
+        5.1, 1.9,
+    ],
+    [
+        1,
+        1, 2,
+    ],
+    [
+        '#NUM!',
+        -1, 2,
+    ],
+    [
+        '#VALUE!',
+        49, 'NaN',
+    ],
+];