# Cell Value Types

Use this article to understand how the `Value` property works in the RadSpreadProcessing document model and which value types a cell can store. It explains the `ICellValue` abstraction, the supported concrete value types, and the most common ways to set, read, and format cell values.

## Working with the Value Property of Cells

Cells are the atomic data units of a worksheet, so the `Value` property is one of the most frequently used cell members. The property is of type `ICellValue`, which is implemented by these five concrete types:

* `EmptyCellValue`
* `BooleanCellValue`
* `NumberCellValue`
* `FormulaCellValue`
* `TextCellValue`

In most scenarios, you start by creating a `CellSelection` that points to a single cell or a cell range. The `Value` property then exposes three common operations:

* `SetValue()`
* `GetValue()`
* `ClearValue()`

`SetValue()` provides multiple overloads, so you can pass a `double`, `string`, `bool`, `DateTime`, or an `ICellValue` instance directly.

## Key ICellValue Members

The `ICellValue` interface exposes several members that are useful when you need to inspect or format a cell value:

* `RawValue`: Stores the entered string value rather than the displayed result. For example, if you enter `=1+2`, the cell value becomes `FormulaCellValue`, the displayed result is `3`, and `RawValue` remains `=1+2`.
* `ValueType` and `ResultValueType`: Return `CellValueType` values that describe the stored value and the calculated result. For example, a formula with `RawValue` equal to `=1+2` has `ValueType` equal to `Formula` and `ResultValueType` equal to `Number`.
* `GetValueAsString()` and `GetResultValueAsString()`: Return formatted string representations of the cell value or its result and require a `CellValueFormat` argument.

## Quick Reference for Supported Value Types

| Value type         | Stores                          | Typical input methods                                                                    |
| ------------------ | ------------------------------- | ---------------------------------------------------------------------------------------- |
| `EmptyCellValue`   | No value                        | `ClearValue()`                                                                           |
| `BooleanCellValue` | `true` or `false`               | `SetValue(bool)`, `CellValueFactory.Create(bool)`                                        |
| `NumberCellValue`  | Numeric values, including dates | `SetValue(double)`, `SetValue(DateTime)`, `SetValue(string)` when parsing succeeds       |
| `FormulaCellValue` | Spreadsheet formulas            | `SetValue(string)` with `=`, `CellValueFactory.Create(...)`, `SetValueAsFormula(string)` |
| `TextCellValue`    | Text strings                    | `SetValue(string)`, text cell format, `SetValueAsText(string)`                           |

## How to Get a Formatted Cell Value

Excel number formats differ from .NET formats. To get the correctly formatted cell value, first read the number format by using `CellSelection.GetFormat().Value`, and then pass the retrieved `CellValueFormat` to `ICellValue.GetResultValueAsString()`.

> caution
>
> The proper way to get a formatted cell value is to read the number format first through `CellSelection.GetFormat().Value` and then pass that `CellValueFormat` to `ICellValue.GetResultValueAsString()`. This approach also calculates formulas contained in the cell. For more information, see [Number Formatting](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/number-formats).

### Example: Get a Formatted Cell Value

```C#
CellSelection cell = worksheet.Cells[rowIndex, columnIndex];
ICellValue cellValue = cell.GetValue().Value;
CellValueFormat cellFormat = cell.GetFormat().Value;
string formattedValue = cellValue.GetResultValueAsString(cellFormat);
```

## Set and Read Cell Values

Example 1 sets the value of cell `A1` to `Total`.

### Example 1: Set a String Value

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();

worksheet.Cells[0, 0].SetValue("Total");
```

Another option is to use the `Create()` method of `CellValueFactory` to produce an `ICellValue` instance and then pass that instance to `SetValue(ICellValue)`. Like `SetValue()`, `Create()` provides overloads for common value types such as `string`, `double`, and `bool`.

Example 2 creates `NumberCellValue` with value `3.14` and assigns it to cell `A1`.

### Example 2: Create NumberCellValue

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();

ICellValue value = CellValueFactory.Create(3.14);
worksheet.Cells[0, 0].SetValue(value);
```

If you retrieve the value of cell `A1`, `GetValue()` returns `NumberCellValue` with `RawValue` equal to `3.14` and both `ValueType` and `ResultValueType` equal to `Number`.

Example 3 retrieves the value created in Example 2.

### Example 3: Retrieve a Cell Value

```C#
RangePropertyValue<ICellValue> rangeValue = worksheet.Cells[0, 0].GetValue();
ICellValue value = rangeValue.Value;
```

## How RangePropertyValue<ICellValue> Works

`GetValue()` does not return `ICellValue` directly. Instead, it returns `RangePropertyValue<ICellValue>`, which is used to determine whether the selected cell range contains a single consistent value.

If you retrieve the value of a range such as `A1:B2` and the cells do not all share the same value, `RangePropertyValue<ICellValue>` reports that the range is not homogeneous.

The class exposes these two key properties:

* `IsIndeterminate`: Indicates whether the `Value` property is consistent across the selected cells. If all cells have the same value, `IsIndeterminate` is `false`. If values differ, it is `true`.
* `Value`: Holds the common `ICellValue` for the range when `IsIndeterminate` is `false`. If the range contains different values, `Value` falls back to the default `EmptyCellValue`.

### Example 4: Use IsIndeterminate and Value

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();

worksheet.Cells[0, 0].SetStyleName("Good");
worksheet.Cells[0, 1].SetStyleName("Bad");

RangePropertyValue<string> cell00Value = worksheet.Cells[0, 0].GetStyleName();
//cell at [0, 0] cell00Value.IsIndeterminate is False, cell00Value.Value is Good

RangePropertyValue<string> cell01Value = worksheet.Cells[0, 1].GetStyleName();
//cell at [0, 0] cell01Value.IsIndeterminate is False, cell01Value.Value is Bad

RangePropertyValue<string> twoCellsValue = worksheet.Cells[0, 0, 0, 1].GetStyleName();
//cells at [0, 0, 0, 1] twoCellsValue.IsIndeterminate is True, twoCellsValue.Value is Normal
```

## Empty Cell Value

`EmptyCellValue` is the default cell value type. When you add an empty worksheet to a workbook, all cells initially contain `EmptyCellValue`. Its `RawValue` is an empty string and its `ValueType` is `Empty`.

If a cell already contains another value, clear it by using `ClearValue()`.

### Example 5: Clear a Value

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].ClearValue();
```

## Boolean Cell Value

`BooleanCellValue` stores a value of type `bool`. Its `RawValue` is either `TRUE` or `FALSE`, and its `ValueType` is `Boolean`. You can assign it directly by using `SetValue(bool)`.

Example 6 sets cells `A1` and `B1` to `true` and `false`.

### Example 6: Set a Boolean Value

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue(true);
worksheet.Cells[0, 1].SetValue(false);
```

You can also create `BooleanCellValue` explicitly by using `CellValueFactory.Create()` and then passing the result to `SetValue()`.

### Example 7: Create BooleanCellValue by Using CellValueFactory

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
ICellValue booleanCellValueTrue = CellValueFactory.Create(true);
ICellValue booleanCellValueFalse = CellValueFactory.Create(false);
worksheet.Cells[0, 0].SetValue(booleanCellValueTrue);
worksheet.Cells[0, 1].SetValue(booleanCellValueFalse);
```

## Number Cell Value

`NumberCellValue` stores a value of type `double`. Its `ValueType` is `Number`, and `RawValue` is the string representation of the internal numeric value.

The displayed cell content can differ from `RawValue` because of the applied number format. For example, `50.00%` and `5.00E-01` can both represent the same internal number `0.5`. Dates also use numeric cell values with a date format applied. For example, `16 September 2020` is stored internally as `44090`.

Use these `SetValue()` overloads to create `NumberCellValue`:

* `SetValue(double)`
* `SetValue(DateTime)`
* `SetValue(string)` when the string can be parsed as a numeric value

If `SetValue(string)` cannot parse the input as another supported type, it falls back to `TextCellValue`.

### Example 8: Set a Number Cell Value

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("1.23");
```

## Date Values

You can use `SetValue(string)` to assign dates.

Example 9 sets the value of cell `A1` to `6 October 1987` in the `en-US` culture. After assignment, the cell contains `NumberCellValue` with `RawValue` equal to `32056`. Because the document model detects a date string, it applies a date format automatically.

### Example 9: Set a Date as NumberCellValue

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("10/06/1987");
```

Contained double value:   32056
Applied format:   m/d/yyyy

If you later access the value from Example 9, you receive its numeric representation, `32056`. To convert that value back to a date, use `FormatHelper.ConvertDoubleToDateTime()` or call `GetValueAsString()` to get the formatted string.

### Example 10: Get a Date Value

```C#
ICellValue cellValue = worksheet.Cells[0, 0].GetValue().Value;
CellValueFormat format = worksheet.Cells[0, 0].GetFormat().Value;

string resultAsString = cellValue.GetValueAsString(format);

double rawValueAsNumber = Convert.ToDouble(cellValue.RawValue);
DateTime? resultAsDateTime = FormatHelper.ConvertDoubleToDateTime(rawValueAsNumber).Value.Date;
```

## Formula Cell Value

`FormulaCellValue` stores a value of type `RadExpression`, which represents an arithmetic expression built from constants, operators, cell references, and functions. Its `CellValueType` is `Formula`, and its `RawValue` must start with `=`.

You can create `FormulaCellValue` in two common ways:

* Pass a string that starts with `=` to `SetValue()`.
* Create an `ICellValue` through `CellValueFactory.Create()` and pass it to `SetValue()`.

Both methods create `FormulaCellValue` only when the current `CellValueFormat` is not `Text`. If the cell format is `Text`, the value becomes `TextCellValue` instead.

### Example 11: Create a Formula That Refers to Another Cell

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("=A2");
```

After this code runs, the value of cell `A1` matches the value of cell `A2`. When `A2` changes, `A1` updates automatically.

An expression can also contain a built-in function. For the full list of available functions, see [Formula Functions](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/formulas/functions). If the current `CellValueFormat` is `Text` (`@`), the method produces `TextCellValue` instead of `FormulaCellValue`.

### Example 12: Use a Built-In Function

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("=SUM(A2, 3)");
```

You can also pass `ICellValue` to `SetValue()` after creating it with `CellValueFactory.Create()`. Unlike the Boolean and Number overloads, formula creation also requires `Worksheet` and `CellIndex` parameters because the expression can reference other cells and worksheets. This overload also takes the current cell format and can return an updated format to apply.

### Example 13: Create FormulaCellValue

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

ICellValue cellValue;
CellValueFormat newFormatValue;
CellValueFactory.Create("=A2 + B2", worksheet, cellIndex, CellValueFormat.GeneralFormat, out cellValue, out newFormatValue);
worksheet.Cells[cellIndex].SetValue(cellValue);
```

`SetValue()` performs internal checks that consider the current cell format and other conditions. If you already know that the incoming text is a formula, use `SetValueAsFormula(string text)` directly to improve performance.

### Example 14: Create FormulaCellValue by Using SetValueAsFormula()

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

worksheet.Cells[cellIndex].SetValueAsFormula("=B1+B2");
```

Depending on your requirements, you can read either the formula definition or the evaluated result value.

### Example 15: Get the Value of a Cell That Contains a Formula

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("=SUM(A2, 3)");
worksheet.Cells[1, 0].SetValue(10);
ICellValue cellValue = worksheet.Cells[0, 0].GetValue().Value;
CellValueFormat format = worksheet.Cells[0, 0].GetFormat().Value;

string valueAsString = cellValue.GetValueAsString(format); // =SUM(A2, 3)
string resultValue = cellValue.GetResultValueAsString(format); // 13
```

## Text Cell Value

`TextCellValue` stores a `string`, and its `ValueType` is `Text`.

You can set `TextCellValue` by using `SetValue(string)`. Before the method creates `TextCellValue`, it first tries to parse the incoming string as other supported value types. For example, if you pass `true`, the cell becomes `BooleanCellValue`.

### Example 16: Set TextCellValue

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetValue("some text");
```

If you want to skip the default parsing and always create `TextCellValue`, set the cell value format to `Text` (`@`) before you assign the value.

### Example 17: Explicitly Apply the Text Value Type

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
worksheet.Cells[0, 0].SetFormat(new CellValueFormat("@"));
worksheet.Cells[0, 0].SetValue("=1+2");
```

You can achieve the same result by using `CellValueFactory.Create()`.

### Example 18: Create TextCellValue

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

ICellValue cellValue;
CellValueFormat newFormatValue;
CellValueFactory.Create("=1 + 2", worksheet, cellIndex, new CellValueFormat("@"), out cellValue, out newFormatValue);
worksheet.Cells[cellIndex].SetValue(cellValue);
```

If you already know that the value must be text, use `SetValueAsText(string text)` directly to avoid the internal parsing checks and improve performance.

### Example 19: Create TextCellValue by Using SetValueAsText()

```C#
Workbook workbook = new Workbook();
Worksheet worksheet = workbook.Worksheets.Add();
CellIndex cellIndex = new CellIndex(0, 0);

worksheet.Cells[cellIndex].SetValueAsText("This is most certainly a text.");
```

## Next Steps

Continue with the article that matches your next task:

1. Read [Accessing Cells of a Worksheet](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/working-with-cells/accessing-cells-of-worksheet) to work with `CellSelection` objects.
2. Read [Number Formatting](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/number-formats) to control how numeric and date values are displayed.
3. Read [Formula Functions](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/formulas/functions) to build more advanced formulas.

## See Also

* [Accessing Cells of a Worksheet](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/working-with-cells/accessing-cells-of-worksheet)