From bc7f63906d49f25bf9e93fe52b9ad4b3d6ff893f Mon Sep 17 00:00:00 2001
From: Yegor Kozlov <yegor@apache.org>
Date: Sat, 21 Jan 2012 11:50:49 +0000
Subject: [PATCH] Added implementation for SUMIFS(), see Bugzilla 52462

git-svn-id: https://svn.apache.org/repos/asf/poi/trunk@1234305 13f79535-47bb-0310-9956-ffa450edef68
---
 src/documentation/content/xdocs/status.xml    |   1 +
 .../poi/ss/formula/atp/AnalysisToolPak.java   |   7 +-
 .../poi/ss/formula/functions/Sumifs.java      | 147 ++++++++++
 .../poi/ss/formula/functions/TestSumifs.java  | 268 ++++++++++++++++++
 test-data/spreadsheet/sumifs.xls              | Bin 0 -> 36352 bytes
 5 files changed, 422 insertions(+), 1 deletion(-)
 create mode 100644 src/java/org/apache/poi/ss/formula/functions/Sumifs.java
 create mode 100644 src/testcases/org/apache/poi/ss/formula/functions/TestSumifs.java
 create mode 100644 test-data/spreadsheet/sumifs.xls

diff --git a/src/documentation/content/xdocs/status.xml b/src/documentation/content/xdocs/status.xml
index 3a1e1999f..7a021f334 100644
--- a/src/documentation/content/xdocs/status.xml
+++ b/src/documentation/content/xdocs/status.xml
@@ -34,6 +34,7 @@
 
     <changes>
         <release version="3.8-beta6" date="2012-??-??">
+           <action dev="poi-developers" type="add">52462 - Added implementation for SUMIFS()</action>
            <action dev="poi-developers" type="add">POIXMLPropertiesTextExtractor support for extracting custom OOXML properties as text</action>
            <action dev="poi-developers" type="fix">52449 - Support writing XWPF documents with glossaries (Glossaries are not yet supported, but can now be written out again without changes)</action>
            <action dev="poi-developers" type="fix">52446 - Handle files which have been truncated by a few bytes in NPropertyTable</action>
diff --git a/src/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java b/src/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java
index cc98aae2a..ce93467ad 100644
--- a/src/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java
+++ b/src/java/org/apache/poi/ss/formula/atp/AnalysisToolPak.java
@@ -15,6 +15,7 @@ import java.util.Map;
 
 import org.apache.poi.ss.formula.eval.ValueEval;
 import org.apache.poi.ss.formula.functions.FreeRefFunction;
+import org.apache.poi.ss.formula.functions.Sumifs;
 import org.apache.poi.ss.formula.udf.UDFFinder;
 import org.apache.poi.ss.formula.OperationEvaluationContext;
 import org.apache.poi.ss.formula.eval.NotImplementedException;
@@ -48,6 +49,10 @@ public final class AnalysisToolPak implements UDFFinder {
     }
 
     public FreeRefFunction findFunction(String name) {
+        // functions that are available in Excel 2007+ have a prefix _xlfn.
+        // if you save such a .xlsx workbook as .xls
+        if(name.startsWith("_xlfn.")) name = name.substring(6);
+
         return _functionsByName.get(name.toUpperCase());
     }
 
@@ -150,7 +155,7 @@ public final class AnalysisToolPak implements UDFFinder {
         r(m, "RTD", null);
         r(m, "SERIESSUM", null);
         r(m, "SQRTPI", null);
-        r(m, "SUMIFS", null);
+        r(m, "SUMIFS", Sumifs.instance);
         r(m, "TBILLEQ", null);
         r(m, "TBILLPRICE", null);
         r(m, "TBILLYIELD", null);
diff --git a/src/java/org/apache/poi/ss/formula/functions/Sumifs.java b/src/java/org/apache/poi/ss/formula/functions/Sumifs.java
new file mode 100644
index 000000000..63d35439a
--- /dev/null
+++ b/src/java/org/apache/poi/ss/formula/functions/Sumifs.java
@@ -0,0 +1,147 @@
+/*
+ *  ====================================================================
+ *    Licensed to the Apache Software Foundation (ASF) under one or more
+ *    contributor license agreements.  See the NOTICE file distributed with
+ *    this work for additional information regarding copyright ownership.
+ *    The ASF licenses this file to You under the Apache License, Version 2.0
+ *    (the "License"); you may not use this file except in compliance with
+ *    the License.  You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ * ====================================================================
+ */
+
+package org.apache.poi.ss.formula.functions;
+
+import org.apache.poi.ss.formula.OperationEvaluationContext;
+import org.apache.poi.ss.formula.eval.*;
+import org.apache.poi.ss.formula.functions.CountUtils.I_MatchPredicate;
+
+/**
+ * Implementation for the Excel function SUMIFS<p>
+ *
+ * Syntax : <br/>
+ *  SUMIFS ( <b>sum_range</b>, <b>criteria_range1</b>, <b>criteria1</>,
+ *  [<b>criteria_range2</b>,  <b>criteria2</b>], ...) <br/>
+ *    <ul>
+ *      <li><b>sum_range</b> Required. One or more cells to sum, including numbers or names, ranges,
+ *      or cell references that contain numbers. Blank and text values are ignored.</li>
+ *      <li><b>criteria1_range</b> Required. The first range in which
+ *      to evaluate the associated criteria.</li>
+ *      <li><b>criteria1</b> Required. The criteria in the form of a number, expression,
+ *        cell reference, or text that define which cells in the criteria_range1
+ *        argument will be added</li>
+ *      <li><b> criteria_range2, criteria2, ...</b>    Optional. Additional ranges and their associated criteria.
+ *      Up to 127 range/criteria pairs are allowed.
+ *    </ul>
+ * </p>
+ *
+ * @author Yegor Kozlov
+ */
+public final class Sumifs implements FreeRefFunction {
+    public static final FreeRefFunction instance = new Sumifs();
+
+	public ValueEval evaluate(ValueEval[] args, OperationEvaluationContext ec) {
+        if(args.length < 3 || args.length % 2 == 0) {
+            return ErrorEval.VALUE_INVALID;
+        }
+
+		try {
+            AreaEval sumRange = convertRangeArg(args[0]);
+
+            // collect pairs of ranges and criteria
+            AreaEval[] ae = new AreaEval[(args.length - 1)/2];
+            I_MatchPredicate[] mp = new I_MatchPredicate[ae.length];
+            for(int i = 1, k=0; i < args.length; i += 2, k++){
+                ae[k] = convertRangeArg(args[i]);
+                mp[k] = Countif.createCriteriaPredicate(args[i+1], ec.getRowIndex(), ec.getColumnIndex());
+            }
+
+            validateCriteriaRanges(ae, sumRange);
+
+            double result = sumMatchingCells(ae, mp, sumRange);
+            return new NumberEval(result);
+		} catch (EvaluationException e) {
+			return e.getErrorEval();
+		}
+	}
+
+    /**
+     * Verify that each <code>criteriaRanges</code> argument contains the same number of rows and columns
+     * as the <code>sumRange</code> argument
+     *
+     * @throws EvaluationException if
+     */
+    private void validateCriteriaRanges(AreaEval[] criteriaRanges, AreaEval sumRange) throws EvaluationException {
+        for(AreaEval r : criteriaRanges){
+            if(r.getHeight() != sumRange.getHeight() ||
+               r.getWidth() != sumRange.getWidth() ) {
+                throw EvaluationException.invalidValue();
+            }
+        }
+    }
+
+    /**
+     *
+     * @param ranges  criteria ranges, each range must be of the same dimensions as <code>aeSum</code>
+     * @param predicates  array of predicates, a predicate for each value in <code>ranges</code>
+     * @param aeSum  the range to sum
+     *
+     * @return the computed value
+     */
+    private static double sumMatchingCells(AreaEval[] ranges, I_MatchPredicate[] predicates, AreaEval aeSum) {
+        int height = aeSum.getHeight();
+        int width = aeSum.getWidth();
+
+        double result = 0.0;
+        for (int r = 0; r < height; r++) {
+            for (int c = 0; c < width; c++) {
+
+                boolean matches = true;
+                for(int i = 0; i < ranges.length; i++){
+                    AreaEval aeRange = ranges[i];
+                    I_MatchPredicate mp = predicates[i];
+
+                    if (!mp.matches(aeRange.getRelativeValue(r, c))) {
+                        matches = false;
+                        break;
+                    }
+
+                }
+
+                if(matches) { // sum only if all of the corresponding criteria specified are true for that cell.
+                    result += accumulate(aeSum, r, c);
+                }
+            }
+        }
+        return result;
+    }
+
+	private static double accumulate(AreaEval aeSum, int relRowIndex,
+			int relColIndex) {
+
+		ValueEval addend = aeSum.getRelativeValue(relRowIndex, relColIndex);
+		if (addend instanceof NumberEval) {
+			return ((NumberEval)addend).getNumberValue();
+		}
+		// everything else (including string and boolean values) counts as zero
+		return 0.0;
+	}
+
+	private static AreaEval convertRangeArg(ValueEval eval) throws EvaluationException {
+		if (eval instanceof AreaEval) {
+			return (AreaEval) eval;
+		}
+		if (eval instanceof RefEval) {
+			return ((RefEval)eval).offset(0, 0, 0, 0);
+		}
+		throw new EvaluationException(ErrorEval.VALUE_INVALID);
+	}
+
+}
diff --git a/src/testcases/org/apache/poi/ss/formula/functions/TestSumifs.java b/src/testcases/org/apache/poi/ss/formula/functions/TestSumifs.java
new file mode 100644
index 000000000..7ecc330f5
--- /dev/null
+++ b/src/testcases/org/apache/poi/ss/formula/functions/TestSumifs.java
@@ -0,0 +1,268 @@
+/*
+ *  ====================================================================
+ *    Licensed to the Apache Software Foundation (ASF) under one or more
+ *    contributor license agreements.  See the NOTICE file distributed with
+ *    this work for additional information regarding copyright ownership.
+ *    The ASF licenses this file to You under the Apache License, Version 2.0
+ *    (the "License"); you may not use this file except in compliance with
+ *    the License.  You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ * ====================================================================
+ */
+
+package org.apache.poi.ss.formula.functions;
+
+import junit.framework.AssertionFailedError;
+import junit.framework.TestCase;
+import org.apache.poi.hssf.HSSFTestDataSamples;
+import org.apache.poi.hssf.usermodel.*;
+import org.apache.poi.ss.formula.OperationEvaluationContext;
+import org.apache.poi.ss.formula.eval.*;
+import org.apache.poi.ss.usermodel.CellValue;
+
+/**
+ * Test cases for SUMIFS()
+ *
+ * @author Yegor Kozlov
+ */
+public final class TestSumifs extends TestCase {
+
+    private static final OperationEvaluationContext EC = new OperationEvaluationContext(null, null, 0, 1, 0, null);
+
+	private static ValueEval invokeSumifs(ValueEval[] args, OperationEvaluationContext ec) {
+		return new Sumifs().evaluate(args, EC);
+	}
+	private static void confirmDouble(double expected, ValueEval actualEval) {
+		if(!(actualEval instanceof NumericValueEval)) {
+			throw new AssertionFailedError("Expected numeric result");
+		}
+		NumericValueEval nve = (NumericValueEval)actualEval;
+		assertEquals(expected, nve.getNumberValue(), 0);
+	}
+
+    private static void confirm(double expectedResult, ValueEval[] args) {
+        confirmDouble(expectedResult, invokeSumifs(args, EC));
+    }
+
+    /**
+     *  Example 1 from
+     *  http://office.microsoft.com/en-us/excel-help/sumifs-function-HA010047504.aspx
+     */
+	public void testExample1() {
+        // mimic test sample from http://office.microsoft.com/en-us/excel-help/sumifs-function-HA010047504.aspx
+        ValueEval[] a2a9 = new ValueEval[] {
+                new NumberEval(5),
+                new NumberEval(4),
+                new NumberEval(15),
+                new NumberEval(3),
+                new NumberEval(22),
+                new NumberEval(12),
+                new NumberEval(10),
+                new NumberEval(33)
+        };
+
+        ValueEval[] b2b9 = new ValueEval[] {
+                new StringEval("Apples"),
+                new StringEval("Apples"),
+                new StringEval("Artichokes"),
+                new StringEval("Artichokes"),
+                new StringEval("Bananas"),
+                new StringEval("Bananas"),
+                new StringEval("Carrots"),
+                new StringEval("Carrots"),
+        };
+
+        ValueEval[] c2c9 = new ValueEval[] {
+                new NumberEval(1),
+                new NumberEval(2),
+                new NumberEval(1),
+                new NumberEval(2),
+                new NumberEval(1),
+                new NumberEval(2),
+                new NumberEval(1),
+                new NumberEval(2)
+        };
+
+        ValueEval[] args;
+        // "=SUMIFS(A2:A9, B2:B9, "=A*", C2:C9, 1)"
+        args = new ValueEval[]{
+                EvalFactory.createAreaEval("A2:A9", a2a9),
+                EvalFactory.createAreaEval("B2:B9", b2b9),
+                new StringEval("A*"),
+                EvalFactory.createAreaEval("C2:C9", c2c9),
+                new NumberEval(1),
+        };
+        confirm(20.0, args);
+
+        // "=SUMIFS(A2:A9, B2:B9, "<>Bananas", C2:C9, 1)"
+        args = new ValueEval[]{
+                EvalFactory.createAreaEval("A2:A9", a2a9),
+                EvalFactory.createAreaEval("B2:B9", b2b9),
+                new StringEval("<>Bananas"),
+                EvalFactory.createAreaEval("C2:C9", c2c9),
+                new NumberEval(1),
+        };
+        confirm(30.0, args);
+
+        // a test case that returns ErrorEval.VALUE_INVALID :
+        // the dimensions of the first and second criteria ranges are different
+        // "=SUMIFS(A2:A9, B2:B8, "<>Bananas", C2:C9, 1)"
+        args = new ValueEval[]{
+                EvalFactory.createAreaEval("A2:A9", a2a9),
+                EvalFactory.createAreaEval("B2:B8", new ValueEval[] {
+                        new StringEval("Apples"),
+                        new StringEval("Apples"),
+                        new StringEval("Artichokes"),
+                        new StringEval("Artichokes"),
+                        new StringEval("Bananas"),
+                        new StringEval("Bananas"),
+                        new StringEval("Carrots"),
+                }),
+                new StringEval("<>Bananas"),
+                EvalFactory.createAreaEval("C2:C9", c2c9),
+                new NumberEval(1),
+        };
+        assertEquals(ErrorEval.VALUE_INVALID, invokeSumifs(args, EC));
+
+	}
+
+    /**
+     *  Example 2 from
+     *  http://office.microsoft.com/en-us/excel-help/sumifs-function-HA010047504.aspx
+     */
+    public void testExample2() {
+        ValueEval[] b2e2 = new ValueEval[] {
+                new NumberEval(100),
+                new NumberEval(390),
+                new NumberEval(8321),
+                new NumberEval(500)
+        };
+        // 1%	0.5%	3%	4%
+        ValueEval[] b3e3 = new ValueEval[] {
+                new NumberEval(0.01),
+                new NumberEval(0.005),
+                new NumberEval(0.03),
+                new NumberEval(0.04)
+        };
+
+        // 1%	1.3%	2.1%	2%
+        ValueEval[] b4e4 = new ValueEval[] {
+                new NumberEval(0.01),
+                new NumberEval(0.013),
+                new NumberEval(0.021),
+                new NumberEval(0.02)
+        };
+
+        // 0.5%	3%	1%	4%
+        ValueEval[] b5e5 = new ValueEval[] {
+                new NumberEval(0.005),
+                new NumberEval(0.03),
+                new NumberEval(0.01),
+                new NumberEval(0.04)
+        };
+
+        ValueEval[] args;
+
+        // "=SUMIFS(B2:E2, B3:E3, ">3%", B4:E4, ">=2%")"
+        args = new ValueEval[]{
+                EvalFactory.createAreaEval("B2:E2", b2e2),
+                EvalFactory.createAreaEval("B3:E3", b3e3),
+                new StringEval(">0.03"), // 3% in the MSFT example
+                EvalFactory.createAreaEval("B4:E4", b4e4),
+                new StringEval(">=0.02"),   // 2% in the MSFT example
+        };
+        confirm(500.0, args);
+    }
+
+    /**
+     *  Example 3 from
+     *  http://office.microsoft.com/en-us/excel-help/sumifs-function-HA010047504.aspx
+     */
+    public void testExample3() {
+        //3.3	0.8	5.5	5.5
+        ValueEval[] b2e2 = new ValueEval[] {
+                new NumberEval(3.3),
+                new NumberEval(0.8),
+                new NumberEval(5.5),
+                new NumberEval(5.5)
+        };
+        // 55	39	39	57.5
+        ValueEval[] b3e3 = new ValueEval[] {
+                new NumberEval(55),
+                new NumberEval(39),
+                new NumberEval(39),
+                new NumberEval(57.5)
+        };
+
+        // 6.5	19.5	6	6.5
+        ValueEval[] b4e4 = new ValueEval[] {
+                new NumberEval(6.5),
+                new NumberEval(19.5),
+                new NumberEval(6),
+                new NumberEval(6.5)
+        };
+
+        ValueEval[] args;
+
+        // "=SUMIFS(B2:E2, B3:E3, ">=40", B4:E4, "<10")"
+        args = new ValueEval[]{
+                EvalFactory.createAreaEval("B2:E2", b2e2),
+                EvalFactory.createAreaEval("B3:E3", b3e3),
+                new StringEval(">=40"),
+                EvalFactory.createAreaEval("B4:E4", b4e4),
+                new StringEval("<10"),
+        };
+        confirm(8.8, args);
+    }
+
+    /**
+     *  Example 5 from
+     *  http://office.microsoft.com/en-us/excel-help/sumifs-function-HA010047504.aspx
+     *
+     *  Criteria entered as reference and by using wildcard characters
+     */
+    public void testFromFile() {
+
+        HSSFWorkbook wb = HSSFTestDataSamples.openSampleWorkbook("sumifs.xls");
+        HSSFFormulaEvaluator fe = new HSSFFormulaEvaluator(wb);
+
+        HSSFSheet example1 = wb.getSheet("Example 1");
+        HSSFCell ex1cell1 = example1.getRow(10).getCell(2);
+        fe.evaluate(ex1cell1);
+        assertEquals(20.0, ex1cell1.getNumericCellValue());
+        HSSFCell ex1cell2 = example1.getRow(11).getCell(2);
+        fe.evaluate(ex1cell2);
+        assertEquals(30.0, ex1cell2.getNumericCellValue());
+
+        HSSFSheet example2 = wb.getSheet("Example 2");
+        HSSFCell ex2cell1 = example2.getRow(6).getCell(2);
+        fe.evaluate(ex2cell1);
+        assertEquals(500.0, ex2cell1.getNumericCellValue());
+        HSSFCell ex2cell2 = example2.getRow(7).getCell(2);
+        fe.evaluate(ex2cell2);
+        assertEquals(8711.0, ex2cell2.getNumericCellValue());
+
+        HSSFSheet example3 = wb.getSheet("Example 3");
+        HSSFCell ex3cell = example3.getRow(5).getCell(2);
+        fe.evaluate(ex3cell);
+        assertEquals(8,8, ex3cell.getNumericCellValue());
+
+        HSSFSheet example4 = wb.getSheet("Example 4");
+        HSSFCell ex4cell = example4.getRow(8).getCell(2);
+        fe.evaluate(ex4cell);
+        assertEquals(3.5, ex4cell.getNumericCellValue());
+
+        HSSFSheet example5 = wb.getSheet("Example 5");
+        HSSFCell ex5cell = example5.getRow(8).getCell(2);
+        fe.evaluate(ex5cell);
+        assertEquals(625000., ex5cell.getNumericCellValue());
+
+    }
+}
diff --git a/test-data/spreadsheet/sumifs.xls b/test-data/spreadsheet/sumifs.xls
new file mode 100644
index 0000000000000000000000000000000000000000..c2d386155c71068621e34359551b0c965eeac328
GIT binary patch
literal 36352
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

literal 0
HcmV?d00001