org.apache.poi.ss.formula.eval

## Class OperandResolver

- java.lang.Object
- - org.apache.poi.ss.formula.eval.OperandResolver

-     public final class OperandResolver
      extends java.lang.Object

  Provides functionality for evaluating arguments to functions and operators.
  Author:
    Josh Micich, Brendan Nolan

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static ValueEval` | `chooseSingleElementFromArea(AreaEval ae, int srcCellRow, int srcCellCol)` Implements (some perhaps not well known) Excel functionality to select a single cell from an area depending on the coordinates of the calling cell.
    `static java.lang.Boolean` | `coerceValueToBoolean(ValueEval ve, boolean stringsAreBlanks)`
    `static double` | `coerceValueToDouble(ValueEval ev)` Applies some conversion rules if the supplied value is not already a number.
    `static int` | `coerceValueToInt(ValueEval ev)` Applies some conversion rules if the supplied value is not already an integer. Value is first coerced to a `double` ( See `coerceValueToDouble()` ).
    `static java.lang.String` | `coerceValueToString(ValueEval ve)`
    `static ValueEval` | `getElementFromArray(AreaEval ae, EvaluationCell cell)` Retrieves a single value from an area evaluation utilizing the 2D indices of the cell within its own area reference to index the value in the area evaluation.
    `static ValueEval` | `getSingleValue(ValueEval arg, int srcCellRow, int srcCellCol)` Retrieves a single value from a variety of different argument types according to standard Excel rules.
    `static java.lang.Double` | `parseDateTime(java.lang.String pText)`
    `static java.lang.Double` | `parseDouble(java.lang.String pText)` Converts a string to a double using standard rules that Excel would use. Tolerates leading and trailing spaces,

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getSingleValue

          public static ValueEval getSingleValue(ValueEval arg,
                                                 int srcCellRow,
                                                 int srcCellCol)
                                          throws EvaluationException

      Retrieves a single value from a variety of different argument types according to standard Excel rules. Does not perform any type conversion.
      Parameters:
        `arg` - the evaluated argument as passed to the function or operator.
        `srcCellRow` - used when arg is a single column AreaRef
        `srcCellCol` - used when arg is a single row AreaRef
      Returns:
        a `NumberEval`, `StringEval`, `BoolEval` or `BlankEval`. Never `null` or `ErrorEval`.
      Throws:
        `EvaluationException` - if srcCellRow or srcCellCol do not properly index into an AreaEval. If the actual value retrieved is an ErrorEval, a corresponding EvaluationException is thrown.

    - #### getElementFromArray

          public static ValueEval getElementFromArray(AreaEval ae,
                                                      EvaluationCell cell)

      Retrieves a single value from an area evaluation utilizing the 2D indices of the cell within its own area reference to index the value in the area evaluation.
      Parameters:
        `ae` - area reference after evaluation
        `cell` - the source cell of the formula that contains its 2D indices
      Returns:
        a `NumberEval`, `StringEval`, `BoolEval` or `BlankEval`. or `ErrorEval`Never `null`.``

    - #### chooseSingleElementFromArea

          public static ValueEval chooseSingleElementFromArea(AreaEval ae,
                                                              int srcCellRow,
                                                              int srcCellCol)
                                                       throws EvaluationException

      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.

      | A | B | C | D
      --- | --- | --- | --- | ---
      1 | 15 | 20 | 25 |
      2 |  |  |  | 200
      3 |  |  |  | 300
      3 |  |  |  | 400

      If the formula "=1000+A1:B1+D2:D3" is put into the 9 cells from A2 to C4, the spreadsheet will look like this:

      | A | B | C | D
      --- | --- | --- | --- | ---
      1 | 15 | 20 | 25 |
      2 | 1215 | 1220 | #VALUE! | 200
      3 | 1315 | 1320 | #VALUE! | 300
      4 | #VALUE! | #VALUE! | #VALUE! | 400

      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.

      The same concept is extended to references across sheets, such that even multi-row, multi-column areas can be useful.

      Of course with carefully (or carelessly) chosen parameters, cyclic references can occur and hence this method can throw a 'circular reference' EvaluationException. Note that this method does not attempt to detect cycles. Every cell in the specified Area `ae` has already been evaluated prior to this method call. Any cell (or cells) part of `ae` that would incur a cyclic reference error if selected by this method, will already have the value ErrorEval.CIRCULAR_REF_ERROR upon entry to this method. It is assumed logic exists elsewhere to produce this behaviour.

      Returns:
        whatever the selected cell's evaluated value is. Never `null`. Never `ErrorEval`.
      Throws:
        `EvaluationException` - if there is a problem with indexing into the area, or if the evaluated cell has an error.

    - #### coerceValueToInt

          public static int coerceValueToInt(ValueEval ev)
                                      throws EvaluationException

      Applies some conversion rules if the supplied value is not already an integer.
      Value is first coerced to a `double` ( See `coerceValueToDouble()` ). Note - `BlankEval` is converted to `0`.

      Excel typically converts doubles to integers by truncating toward negative infinity.
      The equivalent java code is:
      `return (int)Math.floor(d);`
      not:
      `return (int)d; // wrong - rounds toward zero`

      Throws:
        `EvaluationException`

    - #### coerceValueToDouble

          public static double coerceValueToDouble(ValueEval ev)
                                            throws EvaluationException

      Applies some conversion rules if the supplied value is not already a number. Note - `BlankEval` is converted to `NumberEval.ZERO`.
      Parameters:
        `ev` - must be a `NumberEval`, `StringEval`, `BoolEval` or `BlankEval`
      Returns:
        actual, parsed or interpreted double value (respectively).
      Throws:
        `EvaluationException` - if a StringEval is supplied and cannot be parsed as a double (See `parseDouble()` for allowable formats).
        `java.lang.RuntimeException` - if the supplied parameter is not `NumberEval`, `StringEval`, `BoolEval` or `BlankEval`

    - #### parseDouble

          public static java.lang.Double parseDouble(java.lang.String pText)

      Converts a string to a double using standard rules that Excel would use.
      Tolerates leading and trailing spaces,

      Doesn't support currency prefixes, commas, percentage signs or arithmetic operations strings. Some examples:
      " 123 " -> 123.0
      ".123" -> 0.123
      "1E4" -> 1000
      "-123" -> -123.0
      These not supported yet:
      " $ 1,000.00 " -> 1000.0
      "$1.25E4" -> 12500.0
      "5**2" -> 500
      "250%" -> 2.5

      Returns:
        `null` if the specified text cannot be parsed as a number

    - #### parseDateTime

          public static java.lang.Double parseDateTime(java.lang.String pText)

    - #### coerceValueToString

          public static java.lang.String coerceValueToString(ValueEval ve)

      Parameters:
        `ve` - must be a `NumberEval`, `StringEval`, `BoolEval`, or `BlankEval`
      Returns:
        the converted string value. never `null`

    - #### coerceValueToBoolean

          public static java.lang.Boolean coerceValueToBoolean(ValueEval ve,
                                                               boolean stringsAreBlanks)
                                                        throws EvaluationException

      Returns:
        `null` to represent blank values
      Throws:
        `EvaluationException` - if ve is an ErrorEval, or if a string value cannot be converted

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.