From 45ca934a5316deedcebf9a596de9faf2242eacdb Mon Sep 17 00:00:00 2001
From: MarkBaker <mark@lange.demon.co.uk>
Date: Wed, 2 Mar 2022 12:33:20 +0100
Subject: [PATCH] Update Change Log and Documentation

---
 CHANGELOG.md                 | 11 +++++++++--
 docs/topics/reading-files.md | 38 ++++++++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0b625d14..d68fc896 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,15 +10,22 @@ and this project adheres to [Semantic Versioning](https://semver.org).
 ### Added
 
 - Implementation of the ISREF() information function.
-- Allow Boolean Conversion in Csv Reader to be locale-aware when using the String Value Binder.
+- Added support for reading "formatted" numeric values from Csv files; although default behaviour of reading these values as strings is preserved.
 
-  (i.e. `"Vrai"` wil be converted to a boolean `true` if the Locale is set to `fr`.)
+  (i.e a value of "12,345.67" will be read as numeric `1235.67`, not as a string `"12,345.67"`.
+
+  This functionality is locale-aware, using the server's locale settings to identify the thousands and decimal separators.
 
 ### Changed
 
 - Gnumeric Reader now loads number formatting for cells.
 - Gnumeric Reader now correctly identifies selected worksheet.
 - Some Refactoring of the Ods Reader, moving all formula and address translation from Ods to Excel into a separate class to eliminate code duplication and ensure consistency.
+- Make Boolean Conversion in Csv Reader locale-aware when using the String Value Binder.
+
+  This is determined b the Calculation Engine locale setting.
+
+  (i.e. `"Vrai"` wil be converted to a boolean `true` if the Locale is set to `fr`.)
 
 ### Deprecated
 
diff --git a/docs/topics/reading-files.md b/docs/topics/reading-files.md
index 6c30f266..38428166 100644
--- a/docs/topics/reading-files.md
+++ b/docs/topics/reading-files.md
@@ -560,6 +560,44 @@ Xlsx      | NO  | Xls    | NO  | Xml | NO  |
 Ods       | NO  | SYLK   | NO  | Gnumeric     | NO  |
 CSV       | YES | HTML   | NO
 
+
+### Reading formatted Numbers from a CSV File
+
+Unfortunately, numbers in a CSV file may be formatted as strings.
+If that number is a simple integer or float (with a decimal `.` separator) without any thousands separator, then it will be treated as a number.
+However, if the value has a thousands separator (e.g. `12,345`), or a decimal separator that isn't a `.` (e.g. `123,45` for a European locale), then it will be loaded as a string with that formatting.
+If you want the Csv Reader to convert that value to a numeric when it loads the file, the you need to tell it to do so. The `castFormattedNumberToNumeric()` lets you do this.
+
+(Assuming that our server is configured with German locale settings: otherwise it may be necessary to call `setlocale()` before loading the file.)
+```php
+$inputFileType = 'Csv';
+$inputFileName = './sampleData/example1.de.csv';
+
+/** It may be necessary to call setlocale() first if this is not your default locale  */
+// setlocale(LC_ALL, 'de_DE.UTF-8', 'deu_deu');
+
+/**  Create a new Reader of the type defined in $inputFileType  **/
+$reader = \PhpOffice\PhpSpreadsheet\IOFactory::createReader($inputFileType);
+/**  Enable loading numeric values formatted with German , decimal separator and . thousands separator  **/
+$reader->castFormattedNumberToNumeric(true);
+
+/**  Load the file to a Spreadsheet Object  **/
+$spreadsheet = $reader->load($inputFileName);
+```
+This will attempt to load those formatted numeric values as numbers, based on the server's locale settings.
+
+If you want to load those values as numbers, but also to retain the formatting as a number format mask, then you can pass a boolean `true` as a second argument to the `castFormattedNumberToNumeric()` method to tell the Reader to identify the format masking to use for that value. This option does have an arbitrary limit of 6 decimal places.
+
+If your Csv file includes other formats for numbers (currencies, scientific format, etc); then you should probably also use the Advanced Value Binder to handle these cases.  
+
+Applies to:
+
+Reader    | Y/N |Reader  | Y/N |Reader        | Y/N |
+----------|:---:|--------|:---:|--------------|:---:|
+Xlsx      | NO  | Xls    | NO  | Xml | NO  |
+Ods       | NO  | SYLK   | NO  | Gnumeric     | NO  |
+CSV       | YES | HTML   | NO
+
 ### A Brief Word about the Advanced Value Binder
 
 When loading data from a file that contains no formatting information,