io.starter.OpenXLS

Class FormulaHandle

java.lang.Object

io.starter.OpenXLS.FormulaHandle

public class FormulaHandle
extends Object

Formula Handle allows for manipulation of Formulas within a WorkBook.

See Also:

WorkBookHandle, WorkSheetHandle, CellHandle

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	FormulaHandle(Formula f, WorkBook book) Create a new FormulaHandle from an Excel Formula

Method Summary

Modifier and Type	Method and Description
boolean	addCellToRange(String formulaLoc, CellHandle handle) Changes a range in a formula to expand until it includes the cell address from CellHandle.
Object	calculate() Calculate the value of the formula and return it as an object Calling calculate will ignore the WorkBook formula calculation flags and forces calculation of the entire formula stack
boolean	changeFormulaLocation(String formulaLoc, String newaddr) Takes a string as a current formula location, and changes that pointer in the formula to the new string that is sent.
boolean	evaluatesToString() If the Formula evaluates to a String, there will be a Stringrec attached to the Formula which contains the latest value.
boolean	getCalcAlways() return the "Calculate Always" setting for this formula used for formulas that always need calculating such as TODAY
String	getCellAddress() Returns the cell Address of the formula
CellRange[]	getCellRanges() Initialize CellRanges referenced by this formula
double	getDoubleVal() If the Formula evaluates to a double, return the value as an double.
float	getFloatVal() If the Formula evaluates to a float, return the value as an float.
Formula	getFormulaRec() returns the low-level formula rec for this Formulahandle
String	getFormulaString() Returns the Human-Readable Formula String
int	getIntVal() If the Formula evaluates to an int, return the value as an int.
String	getOOXML() generate the OOXML necessary to describe this formula OOXML element
String[]	getRanges() get CellRange strings referenced by this formula
String	getStringVal() If the Formula evaluates to a String, return the value as a String.
static String[][]	getSupportedFunctions()
Object	getVal() Return the value of the Formula
boolean	isArrayFormula()
boolean	isErrorValue() Utility method to determine if the calculation works out to an error value.
boolean	isSharedFormula() return truth of "this formula is shared"
static void	moveCellRefs(FormulaHandle fmh, int[] offsets) Copy the formula references with offsets
void	setCalcAlways(boolean fAlwaysCalc) set the "Calculate Always setting for this formula used for formulas that always need calculating such as TODAY
void	setFormula(String formulaString) Sets the formula to a string passed in excel formula format.
boolean	setLocationLocked(String loc, boolean l) Sets the location lock on the Cell Reference at the specified location Used to prevent updating of the Cell Reference when Cells are moved.
boolean	setLocationPolicy(String loc, int l) Sets the location lock on the Cell Reference at the specified location Used to prevent updating of the Cell Reference when Cells are moved.
String	toString()

Methods inherited from class java.lang.Object

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

Constructor Detail

FormulaHandle

protected FormulaHandle(Formula f,
                        WorkBook book)

Create a new FormulaHandle from an Excel Formula

Parameters:

Formula - - the formula to create a handle for.

Method Detail

getSupportedFunctions

public static String[][] getSupportedFunctions()

setLocationLocked

public boolean setLocationLocked(String loc,
                                 boolean l)

Sets the location lock on the Cell Reference at the specified location Used to prevent updating of the Cell Reference when Cells are moved.

Parameters:

location - of the Cell Reference to be locked/unlocked

lock - status setting

Returns:

boolean whether the Cell Reference was found and modified

setLocationPolicy

public boolean setLocationPolicy(String loc,
                                 int l)

Sets the location lock on the Cell Reference at the specified location Used to prevent updating of the Cell Reference when Cells are moved.

Parameters:

location - of the Cell Reference to be locked/unlocked

lock - status setting

Returns:

boolean whether the Cell Reference was found and modified

getCellAddress

public String getCellAddress()

Returns the cell Address of the formula

getFormulaString

public String getFormulaString()

Returns the Human-Readable Formula String

Returns:

String the Formula in Human-readable format

getStringVal

public String getStringVal()
                    throws FunctionNotSupportedException

If the Formula evaluates to a String, return the value as a String.

Returns:

String - value of the Formula if stored as a String.

Throws:

FunctionNotSupportedException

getVal

public Object getVal()
              throws FunctionNotSupportedException

Return the value of the Formula

Returns:

Object - value of the Formula

Throws:

FunctionNotSupportedException

calculate

public Object calculate()
                 throws FunctionNotSupportedException

Calculate the value of the formula and return it as an object Calling calculate will ignore the WorkBook formula calculation flags and forces calculation of the entire formula stack

Throws:

FunctionNotSupportedException

setFormula

public void setFormula(String formulaString)
                throws FunctionNotSupportedException

Sets the formula to a string passed in excel formula format.

Parameters:

formulaString - - String formatted as an excel formula, like Sum(A3+4)

Throws:

FunctionNotSupportedException

evaluatesToString

public boolean evaluatesToString()

If the Formula evaluates to a String, there will be a Stringrec attached to the Formula which contains the latest value.

Returns:

boolean whether this Formula evaluates to a String

getFloatVal

public float getFloatVal()
                  throws FunctionNotSupportedException

If the Formula evaluates to a float, return the value as an float. If the workbook level flag CALCULATE_EXPLICIT is set then the cached value of the formula (if available) will be returned, otherwise the latest calculated value will be returned

Returns:

float - value of the Formula if available as a float. If the value cannot be returned as a float NaN will be returned.

Throws:

FunctionNotSupportedException

getDoubleVal

public double getDoubleVal()
                    throws FunctionNotSupportedException

If the Formula evaluates to a double, return the value as an double. If the workbook level flag CALCULATE_EXPLICIT is set then the cached value of the formula (if available) will be returned, otherwise the latest calculated value will be returned

Returns:

double - value of the Formula if available as a double. If the value cannot be returned as a double NaN will be returned.

Throws:

FunctionNotSupportedException

getIntVal

public int getIntVal()
              throws FunctionNotSupportedException

If the Formula evaluates to an int, return the value as an int. If the workbook level flag CALCULATE_EXPLICIT is set then the cached value of the formula (if available) will be returned, otherwise the latest calculated value will be returned

Returns:

int - value of the Formula if available as a int. If the value returned can not be represented by an int or is a float/double with a non-zero mantissa a runtime NumberFormatException will be thrown

Throws:

FunctionNotSupportedException

getRanges

public String[] getRanges()
                   throws FormulaNotFoundException

get CellRange strings referenced by this formula

Returns:

Throws:

FormulaNotFoundException

getCellRanges

public CellRange[] getCellRanges()
                          throws FormulaNotFoundException

Initialize CellRanges referenced by this formula

Returns:

Throws:

FormulaNotFoundException

changeFormulaLocation

public boolean changeFormulaLocation(String formulaLoc,
                                     String newaddr)
                              throws FormulaNotFoundException

Takes a string as a current formula location, and changes that pointer in the formula to the new string that is sent. This can take single cells"A5" and cell ranges,"A3:d4" Returns true if the cell range specified in formulaLoc exists & can be changed else false. This also cannot change a cell pointer to a cell range or vice versa.

Parameters:

String - - range of Cells within Formula to modify

String - - new range of Cells within Formula

Throws:

FormulaNotFoundException

addCellToRange

public boolean addCellToRange(String formulaLoc,
                              CellHandle handle)
                       throws FormulaNotFoundException

Changes a range in a formula to expand until it includes the cell address from CellHandle. Example: CellHandle cell = new Cellhandle("D4") Formula = SUM(A1:B2) addCellToRange("A1:B2",cell); would change the formula to look like"SUM(A1:D4)" Returns false if formula does not contain the formulaLoc range.

Parameters:

String - - the Cell Range as a String to add the Cell to

CellHandle - - the CellHandle to add to the range

Throws:

FormulaNotFoundException

moveCellRefs

public static void moveCellRefs(FormulaHandle fmh,
                                int[] offsets)
                         throws FormulaNotFoundException

Copy the formula references with offsets

Parameters:

int[row,col] - offsets to move the references

Throws:

FormulaNotFoundException

toString

public String toString()

Overrides:

toString in class Object

isSharedFormula

public boolean isSharedFormula()

return truth of "this formula is shared"

Returns:

boolean

isArrayFormula

public boolean isArrayFormula()

getFormulaRec

public Formula getFormulaRec()

returns the low-level formula rec for this Formulahandle

Returns:

isErrorValue

public boolean isErrorValue()

Utility method to determine if the calculation works out to an error value. The excel values that will cause this to be true are #VALUE!, #N/A, #REF!, #DIV/0!, #NUM!, #NAME?, #NULL!

Returns:

getCalcAlways

public boolean getCalcAlways()

return the "Calculate Always" setting for this formula used for formulas that always need calculating such as TODAY

Returns:

setCalcAlways

public void setCalcAlways(boolean fAlwaysCalc)

set the "Calculate Always setting for this formula used for formulas that always need calculating such as TODAY

Parameters:

fAlwaysCalc -

getOOXML

public String getOOXML()

generate the OOXML necessary to describe this formula OOXML element

Returns: