sheetjs/docbits/52_datatype.md
SheetJS 19620da30b version bump 0.12.1: BIFF5 features
- BIFF5 write number formats and other features
- XLSX/XLSB/BIFF8 Suppress "Number stored as Text" errors
- codename awareness (fixes #992 h/t @samusstrike)
- updated CFB to 1.0.3
- demo refresh
2018-02-14 15:06:35 -05:00

4.0 KiB

Data Types

The raw value is stored in the v value property, interpreted based on the t type property. This separation allows for representation of numbers as well as numeric text. There are 6 valid cell types:

Type Description
b Boolean: value interpreted as JS boolean
e Error: value is a numeric code and w property stores common name **
n Number: value is a JS number **
d Date: value is a JS Date object or string to be parsed as Date **
s Text: value interpreted as JS string and written as text **
z Stub: blank stub cell that is ignored by data processing utilities **
Error values and interpretation (click to show)
Value Error Meaning
0x00 #NULL!
0x07 #DIV/0!
0x0F #VALUE!
0x17 #REF!
0x1D #NAME?
0x24 #NUM!
0x2A #N/A
0x2B #GETTING_DATA

Type n is the Number type. This includes all forms of data that Excel stores as numbers, such as dates/times and Boolean fields. Excel exclusively uses data that can be fit in an IEEE754 floating point number, just like JS Number, so the v field holds the raw number. The w field holds formatted text. Dates are stored as numbers by default and converted with XLSX.SSF.parse_date_code.

Type d is the Date type, generated only when the option cellDates is passed. Since JSON does not have a natural Date type, parsers are generally expected to store ISO 8601 Date strings like you would get from date.toISOString(). On the other hand, writers and exporters should be able to handle date strings and JS Date objects. Note that Excel disregards timezone modifiers and treats all dates in the local timezone. The library does not correct for this error.

Type s is the String type. Values are explicitly stored as text. Excel will interpret these cells as "number stored as text". Generated Excel files automatically suppress that class of error, but other formats may elicit errors.

Type z represents blank stub cells. They are generated in cases where cells have no assigned value but hold comments or other metadata. They are ignored by the core library data processing utility functions. By default these cells are not generated; the parser sheetStubs option must be set to true.

Dates

Excel Date Code details (click to show)

By default, Excel stores dates as numbers with a format code that specifies date processing. For example, the date 19-Feb-17 is stored as the number 42785 with a number format of d-mmm-yy. The SSF module understands number formats and performs the appropriate conversion.

XLSX also supports a special date type d where the data is an ISO 8601 date string. The formatter converts the date back to a number.

The default behavior for all parsers is to generate number cells. Setting cellDates to true will force the generators to store dates.

Time Zones and Dates (click to show)

Excel has no native concept of universal time. All times are specified in the local time zone. Excel limitations prevent specifying true absolute dates.

Following Excel, this library treats all dates as relative to local time zone.

Epochs: 1900 and 1904 (click to show)

Excel supports two epochs (January 1 1900 and January 1 1904), see "1900 vs. 1904 Date System" article. The workbook's epoch can be determined by examining the workbook's wb.Workbook.WBProps.date1904 property:

!!(((wb.Workbook||{}).WBProps||{}).date1904)