278 lines
11 KiB
Java
Executable File
278 lines
11 KiB
Java
Executable File
/* ====================================================================
|
|
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(Eval arg, int srcCellRow, short srcCellCol)
|
|
throws EvaluationException {
|
|
Eval 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);
|
|
}
|
|
if (result instanceof ValueEval) {
|
|
return (ValueEval) result;
|
|
}
|
|
throw new RuntimeException("Unexpected eval type (" + result.getClass().getName() + ")");
|
|
}
|
|
|
|
/**
|
|
* 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, short srcCellCol) throws EvaluationException {
|
|
ValueEval result = chooseSingleElementFromAreaInternal(ae, srcCellRow, 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.getValues()[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> ).<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 {
|
|
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 not supported and must be handled by the caller.
|
|
* @param ev must be a <tt>NumberEval</tt>, <tt>StringEval</tt> or <tt>BoolEval</tt>
|
|
* @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 <tt>NumberEval</tt>,
|
|
* <tt>StringEval</tt> or <tt>BoolEval</tt>
|
|
*/
|
|
public static double coerceValueToDouble(ValueEval ev) throws EvaluationException {
|
|
|
|
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/>
|
|
*
|
|
* @param text
|
|
* @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 instanceof NumberEval) {
|
|
NumberEval neval = (NumberEval) ve;
|
|
return neval.getStringValue();
|
|
}
|
|
|
|
if (ve instanceof BlankEval) {
|
|
return "";
|
|
}
|
|
throw new IllegalArgumentException("Unexpected eval class (" + ve.getClass().getName() + ")");
|
|
}
|
|
}
|