org.apache.poi.ss.formula.ptg

## Class Ptg

- java.lang.Object
- - org.apache.poi.ss.formula.ptg.Ptg

- All Implemented Interfaces:
    Duplicatable
  Direct Known Subclasses:
    ArrayPtg, ControlPtg, OperandPtg, OperationPtg, ScalarConstantPtg, UnknownPtg

      public abstract class Ptg
      extends java.lang.Object
      implements Duplicatable

  `Ptg` represents a syntactic token in a formula. 'PTG' is an acronym for 'parse thing'. Originally, the name referred to the single byte identifier at the start of the token, but in POI, `Ptg` encapsulates the whole formula token (initial byte + value data).

  `Ptg`s are logically arranged in a tree representing the structure of the parsed formula. However, in BIFF files `Ptg`s are written/read in Reverse-Polish Notation order. The RPN ordering also simplifies formula evaluation logic, so POI mostly accesses `Ptg`s in the same way.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static byte` | `CLASS_ARRAY`
    `static byte` | `CLASS_REF`
    `static byte` | `CLASS_VALUE`
    `static Ptg[]` | `EMPTY_PTG_ARRAY`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `Ptg()`
    `protected` | `Ptg(Ptg other)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Ptg` | `copy()`
    `static Ptg` | `createPtg(LittleEndianInput in)`
    `static boolean` | `doesFormulaReferToDeletedCell(Ptg[] ptgs)`
    `abstract byte` | `getDefaultOperandClass()`
    `static int` | `getEncodedSize(Ptg[] ptgs)` This method will return the same result as `getEncodedSizeWithoutArrayData(Ptg[])` if there are no array tokens present.
    `static int` | `getEncodedSizeWithoutArrayData(Ptg[] ptgs)` Used to calculate value that should be encoded at the start of the encoded Ptg token array;
    `byte` | `getPtgClass()`
    `char` | `getRVAType()` Debug / diagnostic method to get this token's 'operand class' type.
    `abstract int` | `getSize()`
    `abstract boolean` | `isBaseToken()`
    `static Ptg[]` | `readTokens(int size, LittleEndianInput in)` Reads `size` bytes of the input stream, to create an array of `Ptg`s.
    `static int` | `serializePtgs(Ptg[] ptgs, byte[] array, int offset)` Writes the ptgs to the data buffer, starting at the specified offset.
    `void` | `setClass(byte thePtgClass)`
    `abstract java.lang.String` | `toFormulaString()` return a string representation of this token alone
    `java.lang.String` | `toString()` Overridden toString method to ensure object hash is not printed.
    `abstract void` | `write(LittleEndianOutput out)`

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

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

- - ### Field Detail

    - #### EMPTY_PTG_ARRAY

          public static final Ptg[] EMPTY_PTG_ARRAY

    - #### CLASS_REF

          public static final byte CLASS_REF

      See Also:
        Constant Field Values

    - #### CLASS_VALUE

          public static final byte CLASS_VALUE

      See Also:
        Constant Field Values

    - #### CLASS_ARRAY

          public static final byte CLASS_ARRAY

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Ptg

          protected Ptg()

    - #### Ptg

          protected Ptg(Ptg other)

  - ### Method Detail

    - #### readTokens

          public static Ptg[] readTokens(int size,
                                         LittleEndianInput in)

      Reads `size` bytes of the input stream, to create an array of `Ptg`s. Extra data (beyond `size`) may be read if and `ArrayPtg`s are present.

    - #### createPtg

          public static Ptg createPtg(LittleEndianInput in)

    - #### getEncodedSize

          public static int getEncodedSize(Ptg[] ptgs)

      This method will return the same result as `getEncodedSizeWithoutArrayData(Ptg[])` if there are no array tokens present.
      Returns:
        the full size taken to encode the specified `Ptg`s

    - #### getEncodedSizeWithoutArrayData

          public static int getEncodedSizeWithoutArrayData(Ptg[] ptgs)

      Used to calculate value that should be encoded at the start of the encoded Ptg token array;
      Returns:
        the size of the encoded Ptg tokens not including any trailing array data.

    - #### serializePtgs

          public static int serializePtgs(Ptg[] ptgs,
                                          byte[] array,
                                          int offset)

      Writes the ptgs to the data buffer, starting at the specified offset.
      The 2 byte encode length field is not written by this method.
      Returns:
        number of bytes written

    - #### getSize

          public abstract int getSize()

      Returns:
        the encoded length of this Ptg, including the initial Ptg type identifier byte.

    - #### write

          public abstract void write(LittleEndianOutput out)

    - #### toFormulaString

          public abstract java.lang.String toFormulaString()

      return a string representation of this token alone

    - #### toString

          public java.lang.String toString()

      Overridden toString method to ensure object hash is not printed. This helps get rid of gratuitous diffs when comparing two dumps Subclasses may output more relevant information by overriding this method
      Overrides:
        `toString` in class `java.lang.Object`

    - #### setClass

          public final void setClass(byte thePtgClass)

    - #### getPtgClass

          public final byte getPtgClass()

      Returns:
        the 'operand class' (REF/VALUE/ARRAY) for this Ptg

    - #### getRVAType

          public final char getRVAType()

      Debug / diagnostic method to get this token's 'operand class' type.
      Returns:
        'R' for 'reference', 'V' for 'value', 'A' for 'array' and '.' for base tokens

    - #### getDefaultOperandClass

          public abstract byte getDefaultOperandClass()

    - #### isBaseToken

          public abstract boolean isBaseToken()

      Returns:
        `false` if this token is classified as 'reference', 'value', or 'array'

    - #### doesFormulaReferToDeletedCell

          public static boolean doesFormulaReferToDeletedCell(Ptg[] ptgs)

    - #### copy

          public abstract Ptg copy()

      Specified by:
        `copy` in interface `Duplicatable`
      Returns:
        a deep copy of the implementing class / instance

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