Formula (OpenXLS Java Spreadsheet SDK 11.0.4 API)

java.lang.Object
- io.starter.formats.XLS.XLSRecord
- - io.starter.formats.XLS.XLSCellRecord
  - - io.starter.formats.XLS.Formula

All Implemented Interfaces:: BlockByteConsumer, BiffRec, CellAddressible, CellRec, ColumnRange, XLSConstants, Serializable

public final class Formula
extends XLSCellRecord

FORMULA (0x406) describes a cell that contains a formula.

 offset  name        size    contents
 0       rw          2       Row
 2       col         2       Column  
 4       ixfe        2       Index to the XF record
 6       num         8       Current value of the formula
 14      grbit       2       Option Flags
 16      chn         4       (Reserved, must be zero) A field that specifies an application-specific cache of information. This cache exists for performance reasons only, and can be rebuilt based on information stored elsewhere in the file without affecting calculation results.
 20      cce         2       Parsed Expression length
 22      rgce        cce     Parsed Expression

The grbit field contains the following flags:

 byte   bits   mask   name           asserted if
 0      0      0x01   fAlwaysCalc    the result must not be cached    
        1      0x02   fCalcOnLoad    the cached value is incorrect
        2      0x04   (Reserved)
        3      0x08   fShrFmla       this is a reference to a shared formula
        7-4    0xF0   (Unused)
 1      7-0    0xFF   (Unused)

In most cases, formulas should have fAlwaysCalc asserted to ensure that correct values are displayed upon opening of the file in Excel.

See Also:: Serialized Form

Nested Class Summary
- Nested classes/interfaces inherited from interface io.starter.formats.XLS.CellAddressible
  CellAddressible.ColumnMajorComparator, CellAddressible.RangeBoundary, CellAddressible.Reference, CellAddressible.RowMajorComparator
- Nested classes/interfaces inherited from interface io.starter.formats.XLS.ColumnRange
  ColumnRange.Comparator

Field Summary

Fields
Modifier and Type Field and Description

Shrfmla shared
The target ShrFmla record, if this is a shared formula reference.
- Fields inherited from class io.starter.formats.XLS.XLSRecord
  col, continues, DEBUGLEVEL, hyperlink, idx, isBlank, isBoolean, isContinueMerged, isString, lastidx, myxf, offset, rw, streamer, wkbook, worksheet
- Fields inherited from interface io.starter.formats.XLS.XLSConstants
  AI, ALLOWDUPES, ALRUNS, AREA, AREAFORMAT, ARRAY, ATTACHEDLABEL, AUTOFILTER, AXCENT, AXESUSED, AXIS, AXISLINEFORMAT, AXISPARENT, BACKUP, BAR, BEGIN, BLANK, BOF, BOOKBOOL, BOOLERR, BOPPOP, BOPPOPCUSTOM, BOTTOM_MARGIN, BOTTOMMARGIN, BOUNDSHEET, CALC_MODE_PROP, CALCCOUNT, CALCMODE, CALCULATE_ALWAYS, CALCULATE_AUTO, CALCULATE_EXPLICIT, CATLAB, CATSERRANGE, CF, CF12, CHART, CHART3DBARSHAPE, CHARTFORMAT, CHARTFORMATLINK, CHARTFRTINFO, CHARTLINE, CODENAME, COLINFO, CONDFMT, CONDFMT12, CONTINUE, COUNTRY, CRN, CRTLAYOUT12, CRTLAYOUT12A, DAT, DATAFORMAT, DATALABEXT, DATALABEXTCONTENTS, DATE1904, DBCELL, DCON, DCONBIN, DCONNAME, DCONREF, DEBUG_HIGH, DEBUG_LOW, DEBUG_MEDIUM, DEFAULTENCODING, DEFAULTROWHEIGHT, DEFAULTTEXT, DEFCOLWIDTH, DELTA, DIMENSIONS, DROPBAR, DSF, DV, DVAL, END, ENDBLOCK, ENDEXTSST, ENDOBJECT, EOF, EXCEL2K, EXTERNCOUNT, EXTERNNAME, EXTERNSHEET, EXTSST, FBI, FEATHEADR, FILE_LOCK, FILEPASS, FONT, FONTBASIS, FONTX, FOOTERREC, FORMAT, FORMULA, FRAME, FRTFONTLIST, FRTWRAPPER, GARBAGE, GELFRAME, GUTS, HCENTER, HEADERREC, HLINK, HORIZONTAL_PAGE_BREAKS, IFMT, INDEX, INTERFACE_HDR, ITERATION, LABEL, LABELSST, LEFT_MARGIN, LEFTMARGIN, LEGEND, LEGENDXN, LINE, LINEFORMAT, MARKERFORMAT, MAXCOLS, MAXCOLS_BIFF8, MAXRECLEN, MAXROWS, MAXROWS_BIFF8, MERGEDCELLS, MSODRAWING, MSODRAWINGGROUP, MSODRAWINGSELECTION, MULBLANK, MULRK, NAME, NOTE, NUMBER, OBJ, OBJECTLINK, OBJPROTECT, OBPROJ, PALETTE, PANE, PASSWORD, PHONETIC, PICF, PIE, PIEFORMAT, PIVOTCHARTBITS, PIVOTCHARTLINK, PLOTAREA, PLOTGROWTH, PLS, PLV, POS, PRECISION, PRINT_GRIDLINES, PRINT_ROW_HEADERS, PRINTGRID, PRINTROWCOL, PROT4REV, PROTECT, QSISXTAG, RADAR, RADARAREA, RANGEPROTECTION, REFMODE, REFTRACK_PROP, RIGHT_MARGIN, RIGHTMARGIN, RK, ROW, RRD_HEAD, RRD_INFO, RSTRING, RTENTEXU, RTMERGECELLS, SBASEREF, SCATTER, SCENPROTECT, SCL, SELECTION, SERAUXERRBAR, SERAUXTREND, SERFMT, SERIES, SERIESLIST, SERIESTEXT, SERPARENT, SERTOCRT, SETUP, SHAREDUPES, SHEETLAYOUT, SHEETPROTECTION, SHRFMLA, SHTPROPS, SIIINDEX, SST, STARTBLOCK, STARTOBJECT, STRING_ENCODING_AUTO, STRING_ENCODING_COMPRESSED, STRING_ENCODING_UNICODE, STRINGREC, STYLE, SUPBOOK, SURFACE, SXADDL, SXBOOL, SXDB, SXDBB, SXDBEX, SXDI, SXEX, SXFDB, SXFDBTYPE, SXFORMAT, SXIVD, SXLI, SXNUM, SXPI, SXSTREAMID, SXSTRING, SXVD, SXVDEX, SXVI, SXVIEW, SXVIEWEX9, SXVIEWLINK, SXVS, TABID, TABLE, TABLESTYLES, TEXTDISP, THREED, TICK, TOP_MARGIN, TOPMARGIN, TXO, TYPE_BLANK, TYPE_BOOLEAN, TYPE_DOUBLE, TYPE_FORMULA, TYPE_FP, TYPE_INT, TYPE_STRING, UNICODEENCODING, UNITS, USERBVIEW, USERSVIEWBEGIN, USERSVIEWEND, USETEMPFILE_PROP, USR_EXCL, VALIDATEWORKBOOK, VALUERANGE, VB_MODULE, VCENTER, VERTICAL_PAGE_BREAKS, WINDOW_PROTECT, WINDOW1, WINDOW2, WK_CHART, WK_FILE, WK_GLOBALS, WK_MACROSHEET, WK_WORKSHEET, WSBOOL, XCT, XF, XLS_MAX_COLS, YMULT

Fields
Modifier and Type	Field and Description
`Shrfmla`	`shared` The target ShrFmla record, if this is a shared formula reference.

Constructor Summary

Constructors
Constructor and Description

Formula()
Default constructor

Constructors
Constructor and Description
`Formula()` Default constructor

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addInternalRecord(BiffRec b)` store formula-associated records: one or more of: ShrFmla StringRec Array
`Object`	`calculate()` Calculate the formula if necessary.
`Object`	`calculateFormula()` Calculates the formula honoring calculation mode.
`protected void`	`calculateIndirectFunction()` If the method contains an indirect function then register those ptgs into the reference tracker.
`void`	`clearCachedValue()` Set the cached value of this formula, in cases where the formula is null, set the cache to null, as welll as updating the attached string to null in order to force recalc
`Object`	`clone()` clone a record
`void`	`close()` clear out object references in prep for closing workbook
`void`	`convertSharedFormula()` Converts a shared formula reference into a normal formula.
`void`	`destroy()` Performs cleanup needed before removing the formula cell from the work sheet.
`protected void`	`finalize()`
`Array`	`getArray()` fetches the internal Array record linked to this formula, if any, or null if not an array formula
`String`	`getArrayRefs()`
`StringRec`	`getAttatchedString()` Get the String that is attached to this formula (it has a result of a string..);
`boolean`	`getBooleanVal()` Get the value of the record as a Boolean.
`boolean`	`getCalcAlways()` return the "Calculate Always" setting for this formula used for formulas that always need calculating such as TODAY
`Ptg[]`	`getCellRangePtgs()` Returns an array of ptgs that represent any BiffRec ranges in the formula.
`double`	`getDblVal()` Get the value of the record as a Double.
`Stack`	`getExpression()` get the expression stack
`float`	`getFloatVal()` Get the value of the record as a Float.
`String`	`getFormulaString()` Returns the Human-Readable String Representation of this Formula.
`List`	`getInternalRecords()`
`int`	`getIntVal()` Get the value of the formula as an integer.
`List`	`getPtgsByLocation(String loc)` Returns the ptg that matches the string location sent to it.
`String`	`getStringVal()` return the String representation of the current Formula value
`String`	`getTypeName()`
`boolean`	`hasAttachedString()`
`static void`	`incrementSharedFormula(Stack origStack, int rowInc, int colInc, int[] range)` increment each PtgRef in expression stack via row or column based on rowInc or colInc values Used in OOXML parsing
`void`	`init()` Parses the record bytes.
`boolean`	`isArrayFormula()` return truth of "this is an array formula" i.e.
`static boolean`	`isErrorValue(String s)` returns true if the value s is one of the Excel defined Error Strings
`boolean`	`isSharedFormula()` Returns whether this is a reference to a shared formula.
`void`	`preStream()` Updates the record data if necessary to prepare for streaming.
`protected void`	`registerIndirectFunction()` Adds an indirect function to the list of functions to be evaluated post load
`void`	`removeInternalRecord(BiffRec b)`
`void`	`replacePtg(Ptg thisptg, Ptg ptgErr)` Replaces a ptg in the active expression.
`void`	`setArrayRefs(String s)` OOXML-specific: set the range the Array references
`void`	`setCachedValue(Object newValue)` Set the cached value of this formula, in cases where the formula is null, set the cache to null, as well as updating the attached string to null in order to force recalc
`void`	`setCalcAlways(boolean fAlwaysCalc)` set the "Calculate Always setting for this formula used for formulas that always need calculating such as TODAY
`protected void`	`setContainsIndirectFunction(boolean containsIndirectFunction)` Set if the formula contains Indirect()
`void`	`setExpression(Stack exp)` for creating a formula on the fly.
`void`	`setIsExternalRef(boolean isExternalRef)` set if this formula refers to External References (references defined in other workbooks)
`boolean`	`setLocationPolicy(String loc, int l)` locks the Ptg at the specified location
`void`	`setStringVal(String v)`
`String`	`toString()`
`void`	`updateRecord()` Called to indicate that the parsed expression has changed.

Methods inherited from class io.starter.formats.XLS.XLSCellRecord
getColFirst, getColLast, isSingleCol

Methods inherited from class io.starter.formats.XLS.XLSRecord
addContinue, copyFormat, getByteAt, getByteReader, getBytes, getBytesAt, getCellAddress, getCellAddressWithSheet, getCellType, getColNumber, getColorTable, getContinueVect, getData, getDataType, getDefaultVal, getEncryptedByteReader, getFirstBlock, getFont, getFormatPattern, getFormulaRec, getHyperlink, getInternalVal, getIntLocation, getIxfe, getLastBlock, getLength, getMergeRange, getOffset, getOpcode, getPrototype, getRealRecordIndex, getRecDesc, getRecordIndex, getRow, getRowNumber, getSheet, getStreamer, getStringVal, getWorkBook, getXfRec, hasContinues, initRowCol, isFormula, isNumber, isReadOnly, isValueForCell, mergeContinues, postStream, remove, removeContinues, resetCacheBytes, setBooleanVal, setByteReader, setCol, setData, setDebugLevel, setDoubleVal, setEncryptedByteReader, setFirstBlock, setFloatVal, setHyperlink, setIndex, setIntVal, setIsValueForCell, setIxfe, setLastBlock, setLength, setMergeRange, setOffset, setOpcode, setRow, setRowCol, setRowNumber, setSheet, setStreamer, setValueForCell, setWorkBook, setXFRecord, setXFRecord, shouldEncrypt, toHexDump

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface io.starter.formats.XLS.BiffRec
addContinue, copyFormat, getByteAt, getByteReader, getBytes, getBytesAt, getCellAddress, getColNumber, getContinueVect, getData, getDataType, getDefaultVal, getEncryptedByteReader, getFont, getFormatPattern, getFormulaRec, getHyperlink, getInternalVal, getIxfe, getLength, getMergeRange, getOffset, getOpcode, getRecordIndex, getRow, getRowNumber, getSheet, getStreamer, getStringVal, getWorkBook, getXfRec, hasContinues, isReadOnly, isValueForCell, postStream, remove, removeContinues, setBooleanVal, setByteReader, setCol, setData, setDebugLevel, setDoubleVal, setEncryptedByteReader, setHyperlink, setIndex, setIntVal, setIsValueForCell, setIxfe, setLength, setMergeRange, setOffset, setOpcode, setRow, setRowCol, setRowNumber, setSheet, setStreamer, setWorkBook, setXFRecord, setXFRecord, toHexDump

Methods inherited from interface io.starter.formats.XLS.CellAddressible
getRowNumber

- Field Detail
  - shared
```
public Shrfmla shared
```
    The target ShrFmla record, if this is a shared formula reference.
- Constructor Detail
  - Formula
```
public Formula()
```
    Default constructor
- Method Detail
  - init
```
public void init()
```
    Parses the record bytes. This method only needs to be called when the record is being constructed from bytes. Calling it on a programmatically created formula is unnecessary and will probably throw an exception.
    
    Specified by:
    
    init in interface BiffRec
    
    Overrides:
    
    init in class XLSRecord
  - setExpression
```
public void setExpression(Stack exp)
```
    for creating a formula on the fly. This is used currently by FormulaParser to create a formula. The location and XF fields are filled in by boundsheet.add();
  - getExpression
```
public Stack getExpression()
```
    get the expression stack
    
    Returns:
  - addInternalRecord
```
public void addInternalRecord(BiffRec b)
```
    store formula-associated records: one or more of: ShrFmla StringRec Array
    
    Parameters:
    
    b -
  - removeInternalRecord
```
public void removeInternalRecord(BiffRec b)
```
  - getInternalRecords
```
public List getInternalRecords()
```
  - hasAttachedString
```
public boolean hasAttachedString()
```
  - getAttatchedString
```
public StringRec getAttatchedString()
```
    Get the String that is attached to this formula (it has a result of a string..);
  - 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 -
  - setIsExternalRef
```
public void setIsExternalRef(boolean isExternalRef)
```
    set if this formula refers to External References (references defined in other workbooks)
    
    Parameters:
    
    isExternalRef -
  - getTypeName
```
public String getTypeName()
```
  - registerIndirectFunction
```
protected void registerIndirectFunction()
```
    Adds an indirect function to the list of functions to be evaluated post load
  - calculateIndirectFunction
```
protected void calculateIndirectFunction()
```
    If the method contains an indirect function then register those ptgs into the reference tracker. In order to do this it is necessary to calculate the formula to retrieve the Ptg's
  - convertSharedFormula
```
public void convertSharedFormula()
```
    Converts a shared formula reference into a normal formula.
    
    Throws:
    
    IllegalStateException - if this is not a shared formula member
  - getFormulaString
```
public String getFormulaString()
```
    Returns the Human-Readable String Representation of this Formula.
  - getPtgsByLocation
```
public List getPtgsByLocation(String loc)
                       throws FormulaNotFoundException
```
    Returns the ptg that matches the string location sent to it. this can either be in the format "C5" or a range, such as "C4:D9"
    
    Throws:
    
    FormulaNotFoundException
  - getCellRangePtgs
```
public Ptg[] getCellRangePtgs()
                       throws FormulaNotFoundException
```
    Returns an array of ptgs that represent any BiffRec ranges in the formula. Ranges can either be in the format "C5" or "Sheet1!C4:D9"
    
    Throws:
    
    FormulaNotFoundException
  - setLocationPolicy
```
public boolean setLocationPolicy(String loc,
                                 int l)
```
    locks the Ptg at the specified location
  - updateRecord
```
public void updateRecord()
```
    Called to indicate that the parsed expression has changed. Does nothing if the expression doesn't exist yet.
  - preStream
```
public void preStream()
```
    Updates the record data if necessary to prepare for streaming.
    
    Specified by:
    
    preStream in interface BiffRec
    
    Overrides:
    
    preStream in class XLSRecord
  - clone
```
public Object clone()
```
    Description copied from class: XLSRecord
    
    clone a record
    
    Overrides:
    
    clone in class XLSRecord
  - getIntVal
```
public int getIntVal()
              throws RuntimeException
```
    Get the value of the formula as an integer. If the formula exceeds integer boundaries, or is a float with a non-zero mantissa throw an exception
    
    Specified by:
    
    getIntVal in interface BiffRec
    
    Overrides:
    
    getIntVal in class XLSRecord
    
    Throws:
    
    RuntimeException
    
    See Also:
    
    XLSRecord.getIntVal()
  - getFloatVal
```
public float getFloatVal()
```
    Description copied from class: XLSRecord
    
    Get the value of the record as a Float. Value must be parseable as an Float or it will throw a NumberFormatException.
    
    Specified by:
    
    getFloatVal in interface BiffRec
    
    Overrides:
    
    getFloatVal in class XLSRecord
  - getBooleanVal
```
public boolean getBooleanVal()
```
    Description copied from class: XLSRecord
    
    Get the value of the record as a Boolean. Value must be parseable as a Boolean.
    
    Specified by:
    
    getBooleanVal in interface BiffRec
    
    Overrides:
    
    getBooleanVal in class XLSRecord
  - getDblVal
```
public double getDblVal()
```
    Description copied from class: XLSRecord
    
    Get the value of the record as a Double. Value must be parseable as an Double or it will throw a NumberFormatException.
    
    Specified by:
    
    getDblVal in interface BiffRec
    
    Overrides:
    
    getDblVal in class XLSRecord
  - getStringVal
```
public String getStringVal()
```
    return the String representation of the current Formula value
    
    Specified by:
    
    getStringVal in interface BiffRec
    
    Overrides:
    
    getStringVal in class XLSRecord
  - calculateFormula
```
public Object calculateFormula()
                        throws FunctionNotSupportedException
```
    Calculates the formula honoring calculation mode.
    
    Throws:
    
    CalculationException
    
    FunctionNotSupportedException
  - calculate
```
public Object calculate()
```
    Calculate the formula if necessary. This accessor resets the recurse count on the formula. Excel standard is to allow 100 recursions before throwing a circular reference.
    
    Throws:
    
    CalculationException
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class XLSRecord
  - isSharedFormula
```
public boolean isSharedFormula()
```
    Returns whether this is a reference to a shared formula.
  - setStringVal
```
public void setStringVal(String v)
```
    Specified by:
    
    setStringVal in interface BiffRec
    
    Overrides:
    
    setStringVal in class XLSRecord
  - isArrayFormula
```
public boolean isArrayFormula()
```
    return truth of "this is an array formula" i.e. contains an Array sub-record
    
    Returns:
  - getArray
```
public Array getArray()
```
    fetches the internal Array record linked to this formula, if any, or null if not an array formula
    
    Returns:
    
    array record
    
    See Also:
    
    isArrayFormula
  - setArrayRefs
```
public void setArrayRefs(String s)
```
    OOXML-specific: set the range the Array references
    
    Parameters:
    
    s -
  - setCachedValue
```
public void setCachedValue(Object newValue)
```
    Set the cached value of this formula, in cases where the formula is null, set the cache to null, as well as updating the attached string to null in order to force recalc
    
    See Also:
    
    io.starter.formats.XLS.XLSRecord#setCachedValue(java.lang.Object)
  - clearCachedValue
```
public void clearCachedValue()
```
    Set the cached value of this formula, in cases where the formula is null, set the cache to null, as welll as updating the attached string to null in order to force recalc
    
    See Also:
    
    io.starter.formats.XLS.XLSRecord#setCachedValue(java.lang.Object)
  - getArrayRefs
```
public String getArrayRefs()
```
  - incrementSharedFormula
```
public static void incrementSharedFormula(Stack origStack,
                                          int rowInc,
                                          int colInc,
                                          int[] range)
```
    increment each PtgRef in expression stack via row or column based on rowInc or colInc values Used in OOXML parsing
  - setContainsIndirectFunction
```
protected void setContainsIndirectFunction(boolean containsIndirectFunction)
```
    Set if the formula contains Indirect()
    
    Parameters:
    
    containsIndirectFunction - The containsIndirectFunction to set.
  - destroy
```
public void destroy()
```
    Performs cleanup needed before removing the formula cell from the work sheet. The formula will not behave correctly once this is called.
  - isErrorValue
```
public static boolean isErrorValue(String s)
```
    returns true if the value s is one of the Excel defined Error Strings
    
    Parameters:
    
    s -
    
    Returns:
  - close
```
public void close()
```
    Description copied from class: XLSRecord
    
    clear out object references in prep for closing workbook
    
    Overrides:
    
    close in class XLSRecord
  - finalize
```
protected void finalize()
```
    Overrides:
    
    finalize in class Object
  - replacePtg
```
public void replacePtg(Ptg thisptg,
                       Ptg ptgErr)
```
    Replaces a ptg in the active expression. Useful for replacing a ptgRef with a ptgError after a bad movement.
    
    Parameters:
    
    thisptg -
    
    ptgErr -

Class Formula

Nested Class Summary

Nested classes/interfaces inherited from interface io.starter.formats.XLS.CellAddressible

Nested classes/interfaces inherited from interface io.starter.formats.XLS.ColumnRange

Field Summary

Fields inherited from class io.starter.formats.XLS.XLSRecord

Fields inherited from interface io.starter.formats.XLS.XLSConstants

Constructor Summary

Method Summary

Methods inherited from class io.starter.formats.XLS.XLSCellRecord

Methods inherited from class io.starter.formats.XLS.XLSRecord

Methods inherited from class java.lang.Object

Methods inherited from interface io.starter.formats.XLS.BiffRec

Methods inherited from interface io.starter.formats.XLS.CellAddressible

Field Detail

shared

Constructor Detail

Formula

Method Detail

init

setExpression

getExpression

addInternalRecord

removeInternalRecord

getInternalRecords

hasAttachedString

getAttatchedString

getCalcAlways

setCalcAlways

setIsExternalRef

getTypeName

registerIndirectFunction

calculateIndirectFunction

convertSharedFormula

getFormulaString

getPtgsByLocation

getCellRangePtgs

setLocationPolicy

updateRecord

preStream

clone

getIntVal

getFloatVal

getBooleanVal

getDblVal

getStringVal

calculateFormula

calculate

toString

isSharedFormula

setStringVal

isArrayFormula

getArray

setArrayRefs

setCachedValue

clearCachedValue

getArrayRefs

incrementSharedFormula

setContainsIndirectFunction

destroy

isErrorValue

close

finalize

replacePtg