# Number Formatting

Applying different formats to a number changes the appearance of the number. A format does not change the value it is applied to. It only changes the way the value appears in the cell. The following sections explain how to use the predefined number formats.

> note For more information on how to create your own number format or modify one of the predefined types, see the [Format Codes](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/format-codes) article.

## Available Number Formats

The document model exposes the following categories of predefined formats:

* **General format**: The default number format applied to a number. Typically, numbers formatted with this format are displayed exactly as they are typed. If the number has 12 or more digits, the General number format applies scientific notation.

* **Number format**: Used for the general display of numbers. The format specifies the number of decimal places and indicates whether a thousands separator is used. Additionally, the Number format specifies how negative numbers are displayed.

* **Currency format**: Used for general monetary values. Numbers in this format are displayed with the default currency symbol. The format specifies the number of decimal places and indicates whether a thousands separator is used. Additionally, the Currency format specifies how negative numbers are displayed.

* **Accounting format**: Used for monetary values. Unlike the Currency format, it aligns the currency symbols and the values in a column. The format specifies the number of decimal places used.

* **Date format**: Treats a number as date and time serial number and displays it as a date value.

* **Time format**: Treats a number as date and time serial number and displays it as a time value.

* **Percentage format**: Displays the cell value multiplied by 100 and followed by a percent (%) symbol. The format specifies the number of decimal places used.

* **Fraction format**: Displays a cell value as a fraction.

* **Scientific format**: Displays a number in scientific notation. The number is transformed into a real number followed by E+n, where E (which stands for Exponent) multiplies the real number by 10 to the nth power. For example, a 2-decimal scientific format displays 12345678901 as 1.23E+10, which is 1.23 times 10 to the 10th power. The format specifies the number of decimal places used.

* **Text format**: Treats the content of a cell as text and displays the content exactly as it is typed.

* **Special format**: Designed to display numbers as postal codes (ZIP Code), phone numbers, or Social Security numbers.

* **Custom format**: Allows modifying any of the predefined formats. The format also allows creating a new custom number format that is added to the list of number format codes. For more information, see the [Format Codes](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/format-codes) article.

> The Date, Time, and Currency formats are influenced by your OS regional settings. For more information, see [Localization](https://docs.telerik.com/devtools/document-processing/libraries/radspreadprocessing/features/format-codes.html#localization).

## Applying a Number Format

The number format is represented by the `CellValueFormat` class. You can set it to a given `CellSelection` object through its `SetFormat()` method.

> When working with `CellValueFormat`, keep in mind that its constructor accepts a culture-dependent format and converts it to culture-independent format using the current thread format settings (for example, in Bulgarian culture a format passed as 0,00 is converted to 0.00).

The following examples demonstrate how to apply a predefined format to a `CellSelection`:

**Example 1: Apply the General number format**

```C#
CellValueFormat generalFormat = new CellValueFormat("General");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(generalFormat);
```

**Example 1** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a value with the General number format](https://www.telerik.com/document-processing-libraries/documentation/assets/9578e16800f504619cf31c4e36cf2c0a/radspreadprocessing_features_number_formatting_00.jpg)

**Example 2: Apply a Number format**

```C#
CellValueFormat numberFormat = new CellValueFormat("0.00");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(numberFormat);
```

**Example 2** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a numeric value with decimal places in the Number format](https://www.telerik.com/document-processing-libraries/documentation/assets/e45254f1126cca08f642dd75d990a05a/radspreadprocessing_features_number_formatting_01.jpg)

**Example 3: Apply a Currency format**

```C#
CellValueFormat currencyFormat = new CellValueFormat("$#,##0.00");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(currencyFormat);
```

**Example 3** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a currency value with a dollar symbol](https://www.telerik.com/document-processing-libraries/documentation/assets/b9dcb2731c8866981f3ea53d70ebee2c/radspreadprocessing_features_number_formatting_02.jpg)

**Example 4: Apply an Accounting format**

```C#
CellValueFormat accountingFormat = new CellValueFormat("_($* #,##0.00_);_($* (#,##0.00);_($* \" - \"??_);_(@_)");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(accountingFormat);
```

**Example 4** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying an accounting value with an aligned currency symbol](https://www.telerik.com/document-processing-libraries/documentation/assets/c201a14a2184520057e9fe6c7ac94625/radspreadprocessing_features_number_formatting_03.jpg)

**Example 5: Apply a Date format**

```C#
CellValueFormat dateFormat = new CellValueFormat("m/d/yyyy");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789); // OR cellSelectionA1.SetValue(new DateTime(1903, 5, 18, 13, 37, 46));
cellSelectionA1.SetFormat(dateFormat);
```

**Example 5** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a serial value formatted as a date](https://www.telerik.com/document-processing-libraries/documentation/assets/d2ddd2f00b6a8c35af0c0490921e40b3/radspreadprocessing_features_number_formatting_04.jpg)

To show **milliseconds** in **Date Format**, modify the predefined format as follows: *"m/d/yyyy HH:mm:ss.SSS"*. For more information on how to create your own number format or modify one of the predefined types, see the [Format Codes](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/format-codes) article.

**Example 6: Apply a Time format**

```C#
CellValueFormat timeFormat = new CellValueFormat("h:mm:ss AM/PM");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789); // OR cellSelectionA1.SetValue(new DateTime(1903, 5, 18, 13, 37, 46));
cellSelectionA1.SetFormat(timeFormat);
```

**Example 6** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a serial value formatted as a time](https://www.telerik.com/document-processing-libraries/documentation/assets/1c3eb71e6c09161671dcbe9a5f8d49aa/radspreadprocessing_features_number_formatting_05.jpg)

To show **milliseconds** in **Time Format**, modify the predefined format as follows: *"HH:mm:ss.SSS"*. For more information on how to create your own number format or modify one of the predefined types, see the [Format Codes](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/format-codes) article.

**Example 7: Apply a Percentage format**

```C#
CellValueFormat percentageFormat = new CellValueFormat("0.00%");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(percentageFormat);
```

**Example 7** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a percentage value](https://www.telerik.com/document-processing-libraries/documentation/assets/ab98c6b63f7cbefde7f6d4022256addb/radspreadprocessing_features_number_formatting_06.jpg)

**Example 8: Apply a Fraction format**

```C#
CellValueFormat fractionFormat = new CellValueFormat("# ?/?");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(fractionFormat);
```

**Example 8** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a decimal value formatted as a fraction](https://www.telerik.com/document-processing-libraries/documentation/assets/4e454ff29269133794088f16c3dc7591/radspreadprocessing_features_number_formatting_07.jpg)

**Example 9: Apply a Scientific format**

```C#
CellValueFormat scientificFormat = new CellValueFormat("0.00E+00");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(scientificFormat);
```

**Example 9** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a number in scientific notation](https://www.telerik.com/document-processing-libraries/documentation/assets/549c1a305debfdbc60354d471a97a035/radspreadprocessing_features_number_formatting_08.jpg)

**Example 10: Apply a Text format**

```C#
CellValueFormat textFormat = new CellValueFormat("@");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(textFormat);
```

**Example 10** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying content preserved with the Text format](https://www.telerik.com/document-processing-libraries/documentation/assets/8d7dff7a00a14b705f2fb73ed6d56553/radspreadprocessing_features_number_formatting_09.jpg)

**Example 11: Apply a Special format**

```C#
CellValueFormat specialFormat = new CellValueFormat("00000-0000");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(1234.56789);
cellSelectionA1.SetFormat(specialFormat);
```

**Example 11** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a value formatted as a postal code with the Special format](https://www.telerik.com/document-processing-libraries/documentation/assets/13332966a7641913819c91b6ef224f91/radspreadprocessing_features_number_formatting_10.jpg)

**Example 12: Apply a Custom format**

```C#
CellValueFormat specialFormat = new CellValueFormat("[Green]$#,##0_);[Red]$(#,##0);\"zero\";[Blue]\"Text: \" @");

CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];
cellSelectionA1.SetValue(123456789);
cellSelectionA1.SetFormat(specialFormat);

CellSelection cellSelectionB1 = worksheet.Cells[new CellIndex(0, 1)];
cellSelectionB1.SetValueAsText("Progress");
cellSelectionB1.SetFormat(specialFormat);

CellSelection cellSelectionA2 = worksheet.Cells[new CellIndex(1, 0)];
cellSelectionA2.SetValue(0);
cellSelectionA2.SetFormat(specialFormat);

CellSelection cellSelectionB2 = worksheet.Cells[new CellIndex(1, 1)];
cellSelectionB2.SetValue(-1234.56789);
cellSelectionB2.SetFormat(specialFormat);
```

**Example 12** produces the following result:
![Telerik Document Processing RadSpreadProcessing worksheet cell displaying a value with a custom number format](https://www.telerik.com/document-processing-libraries/documentation/assets/60ca2ef7270033f4b5d556688e5c908f/radspreadprocessing_features_number_formatting_11.jpg)

For more information on how to create your own number format or modify one of the predefined types, see the [Format Codes](https://www.telerik.com/document-processing-libraries/documentation/libraries/radspreadprocessing/features/format-codes) article.

## Retrieving a Number Format

You can retrieve the number format of any cell selection through the `GetFormat()` method of the `CellSelection` class. The method returns an object of type `RangePropertyValue<CellValueFormat>`, which exposes two properties:

* `IsIndeterminate`: Determines if the `CellValueFormat` is consistent among all cells in the specified `CellSelection`. If the `CellValueFormat` is one and the same for all cells, `IsIndeterminate` is set to false. If the `CellValueFormat` varies throughout the cells in the `CellSelection`, the `IsIndeterminate` property is set to true and the `Value` property of the `RangePropertyValue<T>` object is set to its default value.

* `Value`: Holds the `CellValueFormat` for the cells. If the `IsIndeterminate` property is set to false, `Value` contains the `CellValueFormat` of the whole `CellSelection` region. If the `IsIndeterminate` property is set to true, the `CellValueFormat` is not the same for all cells in the `CellSelection` and the `Value` property is set to the default `CellValueFormat`.

**Example 13** demonstrates how to get the number format of cell *A1*:

**Example 13: Get the number format from a cell selection**

```C#
CellSelection cellSelectionA1 = worksheet.Cells[new CellIndex(0, 0)];

CellValueFormat cellSelectioA1Format = cellSelectionA1.GetFormat().Value;
```