org.apache.poi.ss.formula

## Class Formula

- java.lang.Object
- - org.apache.poi.ss.formula.Formula

-     public class Formula
      extends java.lang.Object

  Encapsulates an encoded formula token array.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Formula(Formula other)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Formula` | `copy()`
    `static Formula` | `create(Ptg[] ptgs)` Creates a `Formula` object from a supplied `Ptg` array.
    `int` | `getEncodedSize()`
    `int` | `getEncodedTokenSize()` This method is often used when the formula length does not appear immediately before the encoded token data.
    `CellReference` | `getExpReference()` Gets the locator for the corresponding `SharedFormulaRecord`, `ArrayRecord` or `TableRecord` if this formula belongs to such a grouping.
    `Ptg[]` | `getTokens()`
    `static Ptg[]` | `getTokens(Formula formula)` Gets the `Ptg` array from the supplied `Formula`.
    `boolean` | `isSame(Formula other)`
    `static Formula` | `read(int encodedTokenLen, LittleEndianInput in)` Convenience method for `read(int, LittleEndianInput, int)`
    `static Formula` | `read(int encodedTokenLen, LittleEndianInput in, int totalEncodedLen)` When there are no array constants present, `encodedTokenLen`==`totalEncodedLen`
    `void` | `serialize(LittleEndianOutput out)` Writes The formula encoding is includes: ushort tokenDataLen tokenData arrayConstantData (if present)
    `void` | `serializeArrayConstantData(LittleEndianOutput out)`
    `void` | `serializeTokens(LittleEndianOutput out)`

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

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

- - ### Constructor Detail

    - #### Formula

          public Formula(Formula other)

  - ### Method Detail

    - #### read

          public static Formula read(int encodedTokenLen,
                                     LittleEndianInput in)

      Convenience method for `read(int, LittleEndianInput, int)`

    - #### read

          public static Formula read(int encodedTokenLen,
                                     LittleEndianInput in,
                                     int totalEncodedLen)

      When there are no array constants present, `encodedTokenLen`==`totalEncodedLen`
      Parameters:
        `encodedTokenLen` - number of bytes in the stream taken by the plain formula tokens
        `totalEncodedLen` - the total number of bytes in the formula (includes trailing encoding for array constants, but does not include 2 bytes for initial `ushort encodedTokenLen` field.
      Returns:
        A new formula object as read from the stream. Possibly empty, never `null`.

    - #### getTokens

          public Ptg[] getTokens()

    - #### serialize

          public void serialize(LittleEndianOutput out)

      Writes The formula encoding is includes:
      - ushort tokenDataLen
      - tokenData
      - arrayConstantData (if present)

    - #### serializeTokens

          public void serializeTokens(LittleEndianOutput out)

    - #### serializeArrayConstantData

          public void serializeArrayConstantData(LittleEndianOutput out)

    - #### getEncodedSize

          public int getEncodedSize()

      Returns:
        total formula encoding length. The formula encoding includes:
        - ushort tokenDataLen
        - tokenData
        - arrayConstantData (optional)
        Note - this value is different to `tokenDataLength`

    - #### getEncodedTokenSize

          public int getEncodedTokenSize()

      This method is often used when the formula length does not appear immediately before the encoded token data.
      Returns:
        the encoded length of the plain formula tokens. This does not include the leading ushort field, nor any trailing array constant data.

    - #### create

          public static Formula create(Ptg[] ptgs)

      Creates a `Formula` object from a supplied `Ptg` array. Handles `null`s OK.
      Parameters:
        `ptgs` - may be `null`
      Returns:
        Never `null` (Possibly empty if the supplied `ptgs` is `null`)

    - #### getTokens

          public static Ptg[] getTokens(Formula formula)

      Gets the `Ptg` array from the supplied `Formula`. Handles `null`s OK.
      Parameters:
        `formula` - may be `null`
      Returns:
        possibly `null` (if the supplied `formula` is `null`)

    - #### copy

          public Formula copy()

    - #### getExpReference

          public CellReference getExpReference()

      Gets the locator for the corresponding `SharedFormulaRecord`, `ArrayRecord` or `TableRecord` if this formula belongs to such a grouping. The `CellReference` returned by this method will match the top left corner of the range of that grouping. The return value is usually not the same as the location of the cell containing this formula.
      Returns:
        the firstRow & firstColumn of an array formula or shared formula that this formula belongs to. `null` if this formula is not part of an array or shared formula.

    - #### isSame

          public boolean isSame(Formula other)

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