Add section 'Forcing the string value type' to the 'Types of values' …

…guide
handsontable · Nov 9, 2023 · d9b754e · d9b754e
1 parent 510302d
commit d9b754e
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 8 deletions.
diff --git a/docs/guide/advanced-usage.md b/docs/guide/advanced-usage.md
@@ -122,9 +122,9 @@ console.log(winningTeam)
 ## Demo
 
 <iframe
-     src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
-     style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
-     title="handsontable/hyperformula-demos: advanced-usage"
-     allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
-     sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
-   ></iframe>
+  src="https://codesandbox.io/embed/github/handsontable/hyperformula-demos/tree/2.6.x/advanced-usage?autoresize=1&fontsize=11&hidenavigation=1&theme=light&view=preview"
+  style="width:100%; height:500px; border:0; border-radius: 4px; overflow:hidden;"
+  title="handsontable/hyperformula-demos: advanced-usage"
+  allow="accelerometer; ambient-light-sensor; camera; encrypted-media; geolocation; gyroscope; hid; microphone; midi; payment; usb; vr; xr-spatial-tracking"
+  sandbox="allow-autoplay allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts">
+</iframe>
diff --git a/docs/guide/types-of-values.md b/docs/guide/types-of-values.md
@@ -6,7 +6,7 @@ which it's referring. Functions may work differently based on the types of
 values.
 
 | Type of value              | Description                                                                                                                                                                                                      |
-| :------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+|:---------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | Number                     | A numeric value such as 0, 2, -40, 0.1, and also scientific notation e.g. 5.6E+01; with a period as a default decimal separator.                                                                                 |
 | Text (string)              | A text value, like "ABC", "apollo".                                                                                                                                                                              |
 | Logical (Distinct Boolean) | A logical value might be one of two values: TRUE or FALSE. Please note that even if there is type coercion this will be recognized as TRUE/FALSE when comparing to numbers. It will not be recognized as 1 or 0. |
@@ -30,6 +30,28 @@ operations such as calculating the number of days between two dates.
 - A DateTime value is represented as the number of (possibly fractional) days
   since [`nullDate`](../api/interfaces/configparams.md#nulldate).
 
+## Forcing the string value type
+
+Similarly to other popular spreadsheet software, HyperFormula automatically detects the type of an input value.
+On some occasions, the value should be treated as a string even though it's parsable as a number/date/formula/etc.
+The typical examples are numeric values with no number semantics, such as zip codes, bank sort codes, social security numbers, etc.
+To prevent the automatic type conversion, you can prepend the string value with an apostrophe character (`'`). 
+
+```js
+const hf = HyperFormula.buildFromArray([
+    ["11201"], // a number: 11201
+    ["'11201"], // a string: "11201"
+    ["22/06/2022"], // a date: June 22nd 2022
+    ["'22/06/2022"], // a string: "22/06/2022"
+]);
+
+// a formula: SUM(B1,B2)
+hf.setCellContents({ col: 0, row: 4, sheet: 0 }, [["=SUM(B1,B2)"]]);
+
+// a string: "=SUM(B1,B2)"
+hf.setCellContents({ col: 0, row: 5, sheet: 0 }, [["'=SUM(B1,B2)"]]);
+```
+
 ## Getting cell type
 
 Cells have types that can be retrieved by using the `getCellType` method. Cell

diff --git a/test/interpreter/function-left.spec.ts b/test/interpreter/function-left.spec.ts
@@ -1,4 +1,4 @@
-import {CellType, CellValueType, ErrorType, HyperFormula} from '../../src'
+import {ErrorType, HyperFormula} from '../../src'
 import {ErrorMessage} from '../../src/error-message'
 import {adr, detailedError} from '../testUtils'