Skip to content

Commit 5eba6fb

Browse files
sequbasequba
authored
Docs: Describe how HyperFormula determines cell value type (#1554)
Docs: describe how HyperFormula determines the cell value type
1 parent 841e923 commit 5eba6fb

1 file changed

Lines changed: 65 additions & 18 deletions

File tree

‎docs/guide/types-of-values.md‎

Lines changed: 65 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Types of values
22

3-
In HyperFormula, values can be of type Number, Text, Logical, Date, Time, DateTime, Error, Duration, Currency, or Percentage depending on the data.
3+
In HyperFormula, values can be of type Number, Text, Logical, Date, Time, DateTime, Error, Currency, or Percentage depending on the data.
44
Functions may work differently based on the types of arguments.
55

66
| Type of value | Description |
@@ -12,35 +12,62 @@ Functions may work differently based on the types of arguments.
1212
| Time | A time in hh:mm:ss or hh:mm (default format), like 10:40:16. |
1313
| DateTime | Date and Time types combined into one, like 22/06/2022 10:40:16. |
1414
| Error | An error returned as a result of formula calculation, like #REF! |
15-
| Duration | A time-based amount of time |
1615
| Currency | Number representing currency |
1716
| Percentage | Number representing percentage |
1817

19-
## Date and time values
18+
## How cell value types are determined
2019

21-
For better compatibility with other spreadsheet software, HyperFormula stores
22-
date and time values as numbers. This makes it easier to perform mathematical
23-
operations such as calculating the number of days between two dates.
20+
HyperFormula automatically detects the type of cell content when you set a value using methods like `setCellContents`, `buildFromArray`, or `setSheetContent`. The type detection follows this priority order:
2421

25-
- A Date value is represented as the number of full days since
26-
[`nullDate`](../api/interfaces/configparams.md#nulldate).
27-
- A Time value is represented as a fraction of a full day.
28-
- A DateTime value is represented as the number of (possibly fractional) days
29-
since [`nullDate`](../api/interfaces/configparams.md#nulldate).
22+
### For JavaScript values
3023

31-
## Text values
24+
When you pass JavaScript values directly (not as strings):
3225

33-
When working with text values directly inside formulas, you must enclose them in double quotes (`"`). This is different from entering text into cells, where quotes are not required. E.g.:
26+
- `number` → **Number type**
27+
- `boolean` → **Logical type**
28+
- `Date` object → **Date/DateTime type** (converted to internal numeric representation)
29+
- `null` or `undefined` → **Empty cell**
3430

35-
```excel
36-
=IF(B1="Active", "Status OK", "Check Status")
31+
```js
32+
const hf = HyperFormula.buildFromArray([
33+
[42], // Number
34+
[true], // Logical
35+
[new Date()], // Date/DateTime
36+
[null], // Empty
37+
]);
3738
```
3839

39-
### Forcing the text value type
40+
### For string values
41+
42+
When you pass string values, HyperFormula detects the type as follows:
4043

41-
Like most spreadsheet software, HyperFormula automatically detects the type of an input value.
44+
- String is "TRUE" or "FALSE" (case-insensitive) → **Logical type**
45+
- String starting with `=` → **Formula type**
46+
- String ending with `%` → **Percentage type**
47+
- String contains currency symbol → **Currency type**
48+
- String can be parsed as a number → **Number type**
49+
- String matches date/time format → **Date/Time/DateTime type**
50+
- None of the above match → **Text type**
51+
52+
```js
53+
const hf = HyperFormula.buildFromArray([
54+
["TRUE"], // Logical
55+
["true"], // Logical
56+
["=SUM(1,2,3)"], // Formula
57+
["25%"], // Percentage (0.25)
58+
["$100"], // Currency (100)
59+
["123.45"], // Number
60+
["5E+01"], // Number
61+
["22/06/2022 10:40:16"], // DateTime
62+
["22/06/2022"], // Date
63+
["10:40:16"], // Time
64+
["Hello"], // Text
65+
]);
66+
```
4267

43-
But sometimes the value should be treated as text even though it's parsable as a formula, number, date, time, datetime, boolean, currency or percentage.
68+
### Forcing the text value type
69+
70+
Sometimes a value should be treated as text even though it's parsable as a formula, number, date, time, datetime, boolean, currency or percentage.
4471
Typical examples are numeric values with no number semantics, such as ZIP codes, bank sort codes, social security numbers, etc.
4572

4673
To prevent the automatic type conversion, prepend the value value with an apostrophe (`'`).
@@ -60,6 +87,26 @@ hf.setCellContents({ col: 0, row: 4, sheet: 0 }, [["=SUM(B1,B2)"]]);
6087
hf.setCellContents({ col: 0, row: 5, sheet: 0 }, [["'=SUM(B1,B2)"]]);
6188
```
6289

90+
## Date and time values
91+
92+
For better compatibility with other spreadsheet software, HyperFormula stores
93+
date and time values as numbers. This makes it easier to perform mathematical
94+
operations such as calculating the number of days between two dates.
95+
96+
- A Date value is represented as the number of full days since
97+
[`nullDate`](../api/interfaces/configparams.md#nulldate).
98+
- A Time value is represented as a fraction of a full day.
99+
- A DateTime value is represented as the number of (possibly fractional) days
100+
since [`nullDate`](../api/interfaces/configparams.md#nulldate).
101+
102+
## Text values
103+
104+
When working with text values directly inside formulas, you must enclose them in double quotes (`"`). This is different from entering text into cells, where quotes are not required. E.g.:
105+
106+
```excel
107+
=IF(B1="Active", "Status OK", "Check Status")
108+
```
109+
63110
## Getting cell type
64111

65112
Cells have types that can be retrieved by using the `getCellType` method. Cell

0 commit comments

Comments
 (0)