org.apache.poi.ss.usermodel

## Class CellBase

- java.lang.Object
- - org.apache.poi.ss.usermodel.CellBase

- All Implemented Interfaces:
    Cell
  Direct Known Subclasses:
    HSSFCell, SXSSFCell, XSSFCell

      public abstract class CellBase
      extends java.lang.Object
      implements Cell

  Common implementation-independent logic shared by all implementations of `Cell`.
  Author:
    Vladislav "gallon" Galas gallon at apache dot org

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CellBase()`

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `CellAddress` | `getAddress()` Gets the address of this cell
    `CellType` | `getCellTypeEnum()` Deprecated.
    `protected abstract SpreadsheetVersion` | `getSpreadsheetVersion()` Get the spreadsheet version for the given implementation.
    `protected CellType` | `getValueType()` Get value type of this cell.
    `void` | `removeFormula()` Removes formula, if any.
    `protected abstract void` | `removeFormulaImpl()` Implementation-specific removal of the formula.
    `void` | `setBlank()` Removes formula and value from the cell, and sets its type to `CellType.BLANK`.
    `void` | `setCellFormula(java.lang.String formula)` Sets formula for this cell.
    `protected abstract void` | `setCellFormulaImpl(java.lang.String formula)` Implementation-specific setting the formula.
    `void` | `setCellType(CellType cellType)` Set the cells type (blank, numeric, boolean, error or string).
    `protected abstract void` | `setCellTypeImpl(CellType cellType)` Implementation-specific logic
    `void` | `setCellValue(java.util.Calendar value)` Set a date value for the cell.
    `void` | `setCellValue(java.util.Date value)` Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.
    `void` | `setCellValue(double value)` Set a numeric value for the cell.
    `void` | `setCellValue(java.time.LocalDateTime value)` Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.
    `void` | `setCellValue(RichTextString value)` Set a rich string value for the cell.
    `void` | `setCellValue(java.lang.String value)` Set a string value for the cell.
    `protected abstract void` | `setCellValueImpl(java.util.Calendar value)` Implementation-specific way to set a calendar value.
    `protected abstract void` | `setCellValueImpl(java.util.Date value)` Implementation-specific way to set a date value.
    `protected abstract void` | `setCellValueImpl(double value)` Implementation-specific way to set a numeric value.
    `protected abstract void` | `setCellValueImpl(java.time.LocalDateTime value)` Implementation-specific way to set a date value.
    `protected abstract void` | `setCellValueImpl(RichTextString value)` Implementation-specific way to set a RichTextString value.
    `protected abstract void` | `setCellValueImpl(java.lang.String value)` Implementation-specific way to set a string value.
    `void` | `tryToDeleteArrayFormula(java.lang.String message)` Called when this an array formula in this cell is deleted.

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

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

    - ### Methods inherited from interface org.apache.poi.ss.usermodel.Cell

      `getArrayFormulaRange, getBooleanCellValue, getCachedFormulaResultType, getCachedFormulaResultTypeEnum, getCellComment, getCellFormula, getCellStyle, getCellType, getColumnIndex, getDateCellValue, getErrorCellValue, getHyperlink, getLocalDateTimeCellValue, getNumericCellValue, getRichStringCellValue, getRow, getRowIndex, getSheet, getStringCellValue, isPartOfArrayFormulaGroup, removeCellComment, removeHyperlink, setAsActiveCell, setCellComment, setCellErrorValue, setCellStyle, setCellValue, setCellValue, setHyperlink`

- - ### Constructor Detail

    - #### CellBase

          public CellBase()

  - ### Method Detail

    - #### setCellType

          public final void setCellType(CellType cellType)

      Set the cells type (blank, numeric, boolean, error or string).

      If the cell currently contains a value, the value will be converted to match the new type, if possible. Formatting is generally lost in the process however.

      Conversion rules:

      to NUMERIC: numeric value is left as is. True converts to 1.0, false converts to 0. otherwise, the value is set to 0. Formula is removed.

      If what you want to do is get a String value for your numeric cell, stop! This is not the way to do it. Instead, for fetching the string value of a numeric or boolean or date cell, use `DataFormatter` instead.

      If cell is a member of an array formula group containing more than 1 cell, an `IllegalStateException` is thrown. If the array formula group contains only this cell, it is removed.

      Passing `CellType.FORMULA` is illegal and will result in an `IllegalArgumentException`.

      Specified by:
        `setCellType` in interface `Cell`

    - #### setBlank

          public void setBlank()

      Removes formula and value from the cell, and sets its type to `CellType.BLANK`. Preserves comments and hyperlinks. While `Cell.setCellType(CellType)` exists, is an alias for `setCellType(CellType.BLANK)`.
      Specified by:
        `setBlank` in interface `Cell`

    - #### getAddress

          public CellAddress getAddress()

      Gets the address of this cell
      Specified by:
        `getAddress` in interface `Cell`
      Returns:
        `A1` style address of this cell

    - #### setCellTypeImpl

          protected abstract void setCellTypeImpl(CellType cellType)

      Implementation-specific logic
      Parameters:
        `cellType` - new cell type. Guaranteed non-null, not _NONE.

    - #### tryToDeleteArrayFormula

          public final void tryToDeleteArrayFormula(java.lang.String message)

      Called when this an array formula in this cell is deleted.

      The purpose of this method is to validate the cell state prior to modification.

      Parameters:
        `message` - a customized exception message for the case if deletion of the cell is impossible. If null, a default message will be generated
      Throws:
        `java.lang.IllegalStateException` - if modification is not allowed Note. Exposing this to public is ugly. Needed for methods like Sheet#shiftRows.
      See Also:
        `setCellType(CellType)`, `setCellFormula(String)`, `Row.removeCell(org.apache.poi.ss.usermodel.Cell)`, `Sheet.removeRow(org.apache.poi.ss.usermodel.Row)`, `Sheet.shiftRows(int, int, int)`, `Sheet.addMergedRegion(org.apache.poi.ss.util.CellRangeAddress)`

    - #### setCellFormula

          public final void setCellFormula(java.lang.String formula)
                                    throws FormulaParseException,
                                           java.lang.IllegalStateException

      Sets formula for this cell.

      If `formula` is not null, sets or updates the formula. If `formula` is null, removes the formula. Or use `Cell.removeFormula()` to remove the formula.

      Note, this method only sets the formula string and does not calculate the formula value. To set the precalculated value use `Cell.setCellValue(double)`.

      If the cell was blank, sets value to 0. Otherwise, preserves the value as precalculated.

      Specified by:
        `setCellFormula` in interface `Cell`
      Parameters:
        `formula` - the formula to set, e.g. `"SUM(C4:E4)"`. If the argument is `null` then the current formula is removed.
      Throws:
        `FormulaParseException` - if the formula has incorrect syntax or is otherwise invalid
        `java.lang.IllegalStateException` - if this cell is a part of an array formula group containing other cells
      See Also:
        `Cell.removeFormula()`

    - #### getCellTypeEnum

          @Deprecated
           @Removal(version="4.2")
          public final CellType getCellTypeEnum()

      Deprecated.
      Return the cell type. Tables in an array formula return `CellType.FORMULA` for all cells, even though the formula is only defined in the OOXML file for the top left cell of the array.

      NOTE: POI does not support data table formulas. Cells in a data table appear to POI as plain cells typed from their cached value.

      Specified by:
        `getCellTypeEnum` in interface `Cell`
      Returns:
        the cell type

    - #### setCellFormulaImpl

          protected abstract void setCellFormulaImpl(java.lang.String formula)

      Implementation-specific setting the formula. Formula is not null. Shall not change the value.
      Parameters:
        `formula` -

    - #### getValueType

          protected final CellType getValueType()

      Get value type of this cell. Can return BLANK, NUMERIC, STRING, BOOLEAN or ERROR. For current implementations where type is strongly coupled with formula, is equivalent to `getCellType() == CellType.FORMULA ? getCachedFormulaResultType() : getCellType()`

      This is meant as a temporary helper method until the time when value type is decoupled from the formula.

      Returns:
        value type

    - #### removeFormula

          public final void removeFormula()

      Removes formula, if any. If cell was blank, leaves it as is. If it is a part of an array formula group, blanks the cell. If has a regular formula, removes the formula preserving the "cached" value.
      Specified by:
        `removeFormula` in interface `Cell`

    - #### removeFormulaImpl

          protected abstract void removeFormulaImpl()

      Implementation-specific removal of the formula. The cell is guaranteed to have a regular formula set. Shall preserve the "cached" value.

    - #### setCellValue

          public void setCellValue(double value)

      Set a numeric value for the cell.
      Specified by:
        `setCellValue` in interface `Cell`
      Parameters:
        `value` - the numeric value to set this cell to. For formulas we'll set the precalculated value, for numerics we'll set its value. For other types we will change the cell to a numeric cell and set its value.

    - #### setCellValueImpl

          protected abstract void setCellValueImpl(double value)

      Implementation-specific way to set a numeric value. `value` is guaranteed to be a valid (non-NaN) double. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return `CellType.NUMERIC`.
      Parameters:
        `value` - the new value to set

    - #### setCellValue

          public void setCellValue(java.util.Date value)

      Description copied from interface: `Cell`

      Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.

      Note - There is actually no 'DATE' cell type in Excel. In many cases (when entering date values), Excel automatically adjusts the cell style to some date format, creating the illusion that the cell data type is now something besides `CellType.NUMERIC`. POI does not attempt to replicate this behaviour. To make a numeric cell display as a date, use `Cell.setCellStyle(CellStyle)` etc.

      Specified by:
        `setCellValue` in interface `Cell`
      Parameters:
        `value` - the numeric value to set this cell to. For formulas we'll set the precalculated value, for numerics we'll set its value. For other types we will change the cell to a numerics cell and set its value.

    - #### setCellValue

          public void setCellValue(java.time.LocalDateTime value)

      Description copied from interface: `Cell`

      Converts the supplied date to its equivalent Excel numeric value and sets that into the cell.

      Note - There is actually no 'DATE' cell type in Excel. In many cases (when entering date values), Excel automatically adjusts the cell style to some date format, creating the illusion that the cell data type is now something besides `CellType.NUMERIC`. POI does not attempt to replicate this behaviour. To make a numeric cell display as a date, use `Cell.setCellStyle(CellStyle)` etc.

      Specified by:
        `setCellValue` in interface `Cell`
      Parameters:
        `value` - the numeric value to set this cell to. For formulas we'll set the precalculated value, for numerics we'll set its value. For other types we will change the cell to a numerics cell and set its value.

    - #### setCellValueImpl

          protected abstract void setCellValueImpl(java.util.Date value)

      Implementation-specific way to set a date value. `value` is guaranteed to be non-null. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return `CellType.NUMERIC`.
      Parameters:
        `value` - the new date to set

    - #### setCellValueImpl

          protected abstract void setCellValueImpl(java.time.LocalDateTime value)

      Implementation-specific way to set a date value. `value` is guaranteed to be non-null. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return `CellType.NUMERIC`.
      Parameters:
        `value` - the new date to set

    - #### setCellValue

          public void setCellValue(java.util.Calendar value)

      Set a date value for the cell. Excel treats dates as numeric so you will need to format the cell as a date.

      This will set the cell value based on the Calendar's timezone. As Excel does not support timezones this means that both 20:00+03:00 and 20:00-03:00 will be reported as the same value (20:00) even that there are 6 hours difference between the two times. This difference can be preserved by using `setCellValue(value.getTime())` which will automatically shift the times to the default timezone.

      Specified by:
        `setCellValue` in interface `Cell`
      Parameters:
        `value` - the date value to set this cell to. For formulas we'll set the precalculated value, for numerics we'll set its value. For othertypes we will change the cell to a numeric cell and set its value.

    - #### setCellValueImpl

          protected abstract void setCellValueImpl(java.util.Calendar value)

      Implementation-specific way to set a calendar value. `value` is guaranteed to be non-null. The implementation is expected to adjust the cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() would return `CellType.NUMERIC`.
      Parameters:
        `value` - the new calendar value to set

    - #### setCellValue

          public void setCellValue(java.lang.String value)

      Set a string value for the cell.
      Specified by:
        `setCellValue` in interface `Cell`
      Parameters:
        `value` - value to set the cell to. For formulas we'll set the formula string, for String cells we'll set its value. For other types we will change the cell to a string cell and set its value. If value is null then we will change the cell to a Blank cell.

    - #### setCellValueImpl

          protected abstract void setCellValueImpl(java.lang.String value)

      Implementation-specific way to set a string value. The value is guaranteed to be non-null and to satisfy the length limitation imposed by the spreadsheet version. The implementation is expected to adjust cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() (whichever appropriate) would return `CellType.STRING`.
      Parameters:
        `value` - the new value to set.

    - #### setCellValue

          public void setCellValue(RichTextString value)

      Set a rich string value for the cell.
      Specified by:
        `setCellValue` in interface `Cell`
      Parameters:
        `value` - value to set the cell to. For formulas we'll set the formula string, for String cells we'll set its value. For other types we will change the cell to a string cell and set its value. If value is null then we will change the cell to a Blank cell.

    - #### setCellValueImpl

          protected abstract void setCellValueImpl(RichTextString value)

      Implementation-specific way to set a RichTextString value. The value is guaranteed to be non-null, having non-null value, and to satisfy the length limitation imposed by the spreadsheet version. The implementation is expected to adjust cell type accordingly, so that after this call getCellType() or getCachedFormulaResultType() (whichever appropriate) would return `CellType.STRING`.
      Parameters:
        `value` - the new value to set.

    - #### getSpreadsheetVersion

          protected abstract SpreadsheetVersion getSpreadsheetVersion()

      Get the spreadsheet version for the given implementation.
      Returns:
        the spreadsheet version

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