123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323 |
- /* ====================================================================
- 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.hssf.record.formula.eval;
-
- /**
- * Provides functionality for evaluating arguments to functions and operators.
- *
- * @author Josh Micich
- */
- public final class OperandResolver {
-
- private OperandResolver() {
- // no instances of this class
- }
-
- /**
- * Retrieves a single value from a variety of different argument types according to standard
- * Excel rules. Does not perform any type conversion.
- * @param arg the evaluated argument as passed to the function or operator.
- * @param srcCellRow used when arg is a single column AreaRef
- * @param srcCellCol used when arg is a single row AreaRef
- * @return a <tt>NumberEval</tt>, <tt>StringEval</tt>, <tt>BoolEval</tt> or <tt>BlankEval</tt>.
- * Never <code>null</code> or <tt>ErrorEval</tt>.
- * @throws EvaluationException(#VALUE!) if srcCellRow or srcCellCol do not properly index into
- * an AreaEval. If the actual value retrieved is an ErrorEval, a corresponding
- * EvaluationException is thrown.
- */
- public static ValueEval getSingleValue(ValueEval arg, int srcCellRow, int srcCellCol)
- throws EvaluationException {
- ValueEval result;
- if (arg instanceof RefEval) {
- result = ((RefEval) arg).getInnerValueEval();
- } else if (arg instanceof AreaEval) {
- result = chooseSingleElementFromArea((AreaEval) arg, srcCellRow, srcCellCol);
- } else {
- result = arg;
- }
- if (result instanceof ErrorEval) {
- throw new EvaluationException((ErrorEval) result);
- }
- return result;
- }
-
- /**
- * Implements (some perhaps not well known) Excel functionality to select a single cell from an
- * area depending on the coordinates of the calling cell. Here is an example demonstrating
- * both selection from a single row area and a single column area in the same formula.
- *
- * <table border="1" cellpadding="1" cellspacing="1" summary="sample spreadsheet">
- * <tr><th> </th><th> A </th><th> B </th><th> C </th><th> D </th></tr>
- * <tr><th>1</th><td>15</td><td>20</td><td>25</td><td> </td></tr>
- * <tr><th>2</th><td> </td><td> </td><td> </td><td>200</td></tr>
- * <tr><th>3</th><td> </td><td> </td><td> </td><td>300</td></tr>
- * <tr><th>3</th><td> </td><td> </td><td> </td><td>400</td></tr>
- * </table>
- *
- * If the formula "=1000+A1:B1+D2:D3" is put into the 9 cells from A2 to C4, the spreadsheet
- * will look like this:
- *
- * <table border="1" cellpadding="1" cellspacing="1" summary="sample spreadsheet">
- * <tr><th> </th><th> A </th><th> B </th><th> C </th><th> D </th></tr>
- * <tr><th>1</th><td>15</td><td>20</td><td>25</td><td> </td></tr>
- * <tr><th>2</th><td>1215</td><td>1220</td><td>#VALUE!</td><td>200</td></tr>
- * <tr><th>3</th><td>1315</td><td>1320</td><td>#VALUE!</td><td>300</td></tr>
- * <tr><th>4</th><td>#VALUE!</td><td>#VALUE!</td><td>#VALUE!</td><td>400</td></tr>
- * </table>
- *
- * Note that the row area (A1:B1) does not include column C and the column area (D2:D3) does
- * not include row 4, so the values in C1(=25) and D4(=400) are not accessible to the formula
- * as written, but in the 4 cells A2:B3, the row and column selection works ok.<p/>
- *
- * The same concept is extended to references across sheets, such that even multi-row,
- * multi-column areas can be useful.<p/>
- *
- * Of course with carefully (or carelessly) chosen parameters, cyclic references can occur and
- * hence this method <b>can</b> throw a 'circular reference' EvaluationException. Note that
- * this method does not attempt to detect cycles. Every cell in the specified Area <tt>ae</tt>
- * has already been evaluated prior to this method call. Any cell (or cell<b>s</b>) part of
- * <tt>ae</tt> that would incur a cyclic reference error if selected by this method, will
- * already have the value <t>ErrorEval.CIRCULAR_REF_ERROR</tt> upon entry to this method. It
- * is assumed logic exists elsewhere to produce this behaviour.
- *
- * @return whatever the selected cell's evaluated value is. Never <code>null</code>. Never
- * <tt>ErrorEval</tt>.
- * @throws EvaluationException if there is a problem with indexing into the area, or if the
- * evaluated cell has an error.
- */
- public static ValueEval chooseSingleElementFromArea(AreaEval ae,
- int srcCellRow, int srcCellCol) throws EvaluationException {
- ValueEval result = chooseSingleElementFromAreaInternal(ae, srcCellRow, (short) srcCellCol);
- if(result == null) {
- // This seems to be required because AreaEval.values() array may contain nulls.
- // perhaps that should not be allowed.
- result = BlankEval.INSTANCE;
- }
- if (result instanceof ErrorEval) {
- throw new EvaluationException((ErrorEval) result);
-
- }
- return result;
- }
-
- /**
- * @return possibly <tt>ErrorEval</tt>, and <code>null</code>
- */
- private static ValueEval chooseSingleElementFromAreaInternal(AreaEval ae,
- int srcCellRow, short srcCellCol) throws EvaluationException {
-
- if(false) {
- // this is too simplistic
- if(ae.containsRow(srcCellRow) && ae.containsColumn(srcCellCol)) {
- throw new EvaluationException(ErrorEval.CIRCULAR_REF_ERROR);
- }
- /*
- Circular references are not dealt with directly here, but it is worth noting some issues.
-
- ANY one of the return statements in this method could return a cell that is identical
- to the one immediately being evaluated. The evaluating cell is identified by srcCellRow,
- srcCellRow AND sheet. The sheet is not available in any nearby calling method, so that's
- one reason why circular references are not easy to detect here. (The sheet of the returned
- cell can be obtained from ae if it is an Area3DEval.)
-
- Another reason there's little value in attempting to detect circular references here is
- that only direct circular references could be detected. If the cycle involved two or more
- cells this method could not detect it.
-
- Logic to detect evaluation cycles of all kinds has been coded in EvaluationCycleDetector
- (and HSSFFormulaEvaluator).
- */
- }
-
- if (ae.isColumn()) {
- if(ae.isRow()) {
- return ae.getRelativeValue(0, 0);
- }
- if(!ae.containsRow(srcCellRow)) {
- throw EvaluationException.invalidValue();
- }
- return ae.getValueAt(srcCellRow, ae.getFirstColumn());
- }
- if(!ae.isRow()) {
- // multi-column, multi-row area
- if(ae.containsRow(srcCellRow) && ae.containsColumn(srcCellCol)) {
- return ae.getValueAt(ae.getFirstRow(), ae.getFirstColumn());
- }
- throw EvaluationException.invalidValue();
- }
- if(!ae.containsColumn(srcCellCol)) {
- throw EvaluationException.invalidValue();
- }
- return ae.getValueAt(ae.getFirstRow(), srcCellCol);
- }
-
- /**
- * Applies some conversion rules if the supplied value is not already an integer.<br/>
- * Value is first coerced to a <tt>double</tt> ( See <tt>coerceValueToDouble()</tt> ).
- * Note - <tt>BlankEval</tt> is converted to <code>0</code>.<p/>
- *
- * Excel typically converts doubles to integers by truncating toward negative infinity.<br/>
- * The equivalent java code is:<br/>
- * <code>return (int)Math.floor(d);</code><br/>
- * <b>not</b>:<br/>
- * <code>return (int)d; // wrong - rounds toward zero</code>
- *
- */
- public static int coerceValueToInt(ValueEval ev) throws EvaluationException {
- if (ev == BlankEval.INSTANCE) {
- return 0;
- }
- double d = coerceValueToDouble(ev);
- // Note - the standard java type conversion from double to int truncates toward zero.
- // but Math.floor() truncates toward negative infinity
- return (int)Math.floor(d);
- }
-
- /**
- * Applies some conversion rules if the supplied value is not already a number.
- * Note - <tt>BlankEval</tt> is converted to {@link NumberEval#ZERO}.
- * @param ev must be a {@link NumberEval}, {@link StringEval}, {@link BoolEval} or
- * {@link BlankEval}
- * @return actual, parsed or interpreted double value (respectively).
- * @throws EvaluationException(#VALUE!) only if a StringEval is supplied and cannot be parsed
- * as a double (See <tt>parseDouble()</tt> for allowable formats).
- * @throws RuntimeException if the supplied parameter is not {@link NumberEval},
- * {@link StringEval}, {@link BoolEval} or {@link BlankEval}
- */
- public static double coerceValueToDouble(ValueEval ev) throws EvaluationException {
-
- if (ev == BlankEval.INSTANCE) {
- return 0.0;
- }
- if (ev instanceof NumericValueEval) {
- // this also handles booleans
- return ((NumericValueEval)ev).getNumberValue();
- }
- if (ev instanceof StringEval) {
- Double dd = parseDouble(((StringEval) ev).getStringValue());
- if (dd == null) {
- throw EvaluationException.invalidValue();
- }
- return dd.doubleValue();
- }
- throw new RuntimeException("Unexpected arg eval type (" + ev.getClass().getName() + ")");
- }
-
- /**
- * Converts a string to a double using standard rules that Excel would use.<br/>
- * Tolerates currency prefixes, commas, leading and trailing spaces.<p/>
- *
- * Some examples:<br/>
- * " 123 " -> 123.0<br/>
- * ".123" -> 0.123<br/>
- * These not supported yet:<br/>
- * " $ 1,000.00 " -> 1000.0<br/>
- * "$1.25E4" -> 12500.0<br/>
- * "5**2" -> 500<br/>
- * "250%" -> 2.5<br/>
- *
- * @return <code>null</code> if the specified text cannot be parsed as a number
- */
- public static Double parseDouble(String pText) {
- String text = pText.trim();
- if(text.length() < 1) {
- return null;
- }
- boolean isPositive = true;
- if(text.charAt(0) == '-') {
- isPositive = false;
- text= text.substring(1).trim();
- }
-
- if(!Character.isDigit(text.charAt(0))) {
- // avoid using NumberFormatException to tell when string is not a number
- return null;
- }
- // TODO - support notation like '1E3' (==1000)
-
- double val;
- try {
- val = Double.parseDouble(text);
- } catch (NumberFormatException e) {
- return null;
- }
- return new Double(isPositive ? +val : -val);
- }
-
- /**
- * @param ve must be a <tt>NumberEval</tt>, <tt>StringEval</tt>, <tt>BoolEval</tt>, or <tt>BlankEval</tt>
- * @return the converted string value. never <code>null</code>
- */
- public static String coerceValueToString(ValueEval ve) {
- if (ve instanceof StringValueEval) {
- StringValueEval sve = (StringValueEval) ve;
- return sve.getStringValue();
- }
- if (ve == BlankEval.INSTANCE) {
- return "";
- }
- throw new IllegalArgumentException("Unexpected eval class (" + ve.getClass().getName() + ")");
- }
-
- /**
- * @return <code>null</code> to represent blank values
- * @throws EvaluationException if ve is an ErrorEval, or if a string value cannot be converted
- */
- public static Boolean coerceValueToBoolean(ValueEval ve, boolean stringsAreBlanks) throws EvaluationException {
-
- if (ve == null || ve == BlankEval.INSTANCE) {
- // TODO - remove 've == null' condition once AreaEval is fixed
- return null;
- }
- if (ve instanceof BoolEval) {
- return Boolean.valueOf(((BoolEval) ve).getBooleanValue());
- }
-
- if (ve == BlankEval.INSTANCE) {
- return null;
- }
-
- if (ve instanceof StringEval) {
- if (stringsAreBlanks) {
- return null;
- }
- String str = ((StringEval) ve).getStringValue();
- if (str.equalsIgnoreCase("true")) {
- return Boolean.TRUE;
- }
- if (str.equalsIgnoreCase("false")) {
- return Boolean.FALSE;
- }
- // else - string cannot be converted to boolean
- throw new EvaluationException(ErrorEval.VALUE_INVALID);
- }
-
- if (ve instanceof NumericValueEval) {
- NumericValueEval ne = (NumericValueEval) ve;
- double d = ne.getNumberValue();
- if (Double.isNaN(d)) {
- throw new EvaluationException(ErrorEval.VALUE_INVALID);
- }
- return Boolean.valueOf(d != 0);
- }
- if (ve instanceof ErrorEval) {
- throw new EvaluationException((ErrorEval) ve);
- }
- throw new RuntimeException("Unexpected eval (" + ve.getClass().getName() + ")");
- }
- }
|