Update to FV description and associated pages in the Features area.

docs/src/.vitepress/config.mts

@@ -58,6 +58,18 @@ export default defineConfig({
             text: "Error Types",
             link: "/features/error-types",
           },
+          {
+            text: "Value Types",
+            link: "/features/value-types",
+          },
+          {
+            text: "Optional Arguments",
+            link: "/features/optional-arguments",
+          },
+          {
+            text: "Units",
+            link: "/features/units",
+          },		  
           {
             text: "Unsupported Features",
             link: "/features/unsupported-features",

docs/src/features/error-types.md

@@ -7,31 +7,39 @@ lang: en-US
 # Error Types
 
 ::: warning
-**Note:** This page is in construction 🚧
+**Note:** This draft page is under construction 🚧
 :::
 
-When working with formulas, you may encounter these common errors:
+The result of a formula is sometimes an _error_. In some situations those errors are expected and your formulas might be dealing with them.
+The error `#N/A` might signal that there is no data to evaluate the formula yet. Maybe the payrol has not been introduced for that month just yet.
 
----
+Some other errors like `#SPILL!`, `#CIRC!` or `#ERROR!` signal an error in your spreadsheet logic and must be corrected.
 
-### **`#ERROR!`**
+The first kind of errors or 'common errors' are found in other spreadsheet engines like Excel while other errrors like `#ERROR!` or `#N/IMPL` are particular to IronCalc.
 
-**Cause:** General formula issue, like syntax errors or invalid references.  
-**Fix:** Check the formula for mistakes or invalid cell references.
-
----
+## Common Errors
 
 ### **`#VALUE!`**
 
-**Cause:** Mismatched data types (e.g., text used where numbers are expected).  
-**Fix:** Ensure input types are correct; convert text to numbers if needed.
+It might be caused by mismatched data types (e.g., text used where numbers are expected):
 
----
+```
+5+"two"
+```
+
+The engine doesn't know how to add the number `5` to the string `two` resulting in a `#VALUE!`.
+
+It is an actual error in your spreadsheet. It indicates that the formula isn’t working as intended.
 
 ### **`#DIV/0!`**
 
-**Cause:** Division by zero or an empty cell.  
-**Fix:** Ensure the denominator isn’t zero or blank. Use `IF` to handle such cases:
+Division by zero or an empty cell.
+
+```
+=1/0
+```
+
+Usually this is an error. However, in cases where a denominator might be blank (e.g., data not yet filled in), this could be expected. Use `IFERROR` or `IF` to handle it.
 
 ```
 =IF(B1=0, "N/A", A1/B1)
@@ -39,23 +47,42 @@ When working with formulas, you may encounter these common errors:
 
 ### **`#NAME?`**
 
-**Cause:** Unrecognized text in the formula (e.g., misspelled function names or undefined named ranges).  
-**Fix:** Correct spelling or define the missing name.
+Found when a name is not recognized. Maybe a misspeled name for a function. Could be a referenceto defined name that has been deleted.
+
+```
+=UNKOWN_FUNCTION(A1)
+```
+
+This indicates an error in your spreadsheet logic.
 
 ### **`#REF!`**
 
-**Cause:** Invalid cell reference, often from deleting cells used in a formula.  
-**Fix:** Update the formula with correct references.
+Indicates an invalid cell reference, often from deleting cells used in a formula.
+
+They can appear as a result of a computation or in a formula. Examples:
+
+```
+=Sheet34!A1
+```
+
+If `Sheet34` doesn't exist it will return `#REF!`
+
+This is a genuine error. It indicates that part of your formula references a cell or range that is missing.
 
 ### **`#NUM!`**
 
-**Cause:** Invalid numeric operation (e.g., calculating a square root of a negative number).  
-**Fix:** Adjust the formula to ensure valid numeric operations.
+Invalid numeric operation (e.g., calculating a square root of a negative number).  
+Adjust the formula to ensure valid numeric operations.
+
+Sometimes a `#NUM!` might be expected signalling the user that some parameter is out of scope.
 
 ### **`#N/A`**
 
-**Cause:** A value is not available, often in lookup functions like VLOOKUP.  
-**Fix:** Ensure the lookup value exists or use IFNA() to handle missing values:
+A value is not available, often in lookup functions like VLOOKUP.
+
+This is frequnly not an error in your spreadsheetlogic.
+
+You can produce a prettier answer using the [`IFNA`](/functions/information/isna) formula:
 
 ```
 =IFNA(VLOOKUP(A1, B1:C10, 2, FALSE), "Not Found")
@@ -63,17 +90,68 @@ When working with formulas, you may encounter these common errors:
 
 ### **`#NULL!`**
 
-**Cause:** Incorrect range operator in a formula (e.g., missing a colon between cell references).  
-**Fix:** Use correct range operators (e.g., A1:A10).
+Incorrect range operator in a formula (e.g., missing a colon between cell references).
 
+### **`#SPILL!`**
+
+A cell in a formula will overwrite content in other cells.
+This cannot happen riht now in IronCalc as formulas don't spill yet.
 
 ### **`#CIRC!`**
 
-**Cause:** Circular reference.  
-**Fix:** Remove the circular reference.
+Circular reference. This is an error is your spreadsheet and must be fixed.
+Means that during teh course of a computation a circular dependency was found.
+
+A circular dependency is a dependency of a formula on itself.
+
+For instance in the cell `A1` the formula `=A1*2` is a circular dependency.
+
+Other spreadsheet engines use circular dependencies to do "loop computations", run "sensitivity analysis" or "goal seek".
+
+IronCalc doesn't support any of those at the moment.
+
+## IronCalc specific errors
+
+---
+
+### **`#ERROR!`**
+
+General formula issue, like syntax errors or invalid references.
+In general Excel does not let you enter incorrect formulas but IronCalc will.
+
+This will make your workbook imcompatible with Excel
+
+For instace an incomplete formula
+
+```
+=A1+
+```
+
+### **`#N/IMPL!`**
+
+A particular feature is not yet implemented in IronCalc
+
+Look if there is a Github ticket or contact us via email, Discord or bluesky
+
+## Error propagation
+
+Some errors a created by some formulas. For instance the function `SQRT` can create the error `#NUM!` but can't ceate the error `#DIV/0`.
+
+Once an error is created it is normally _propagated_ by all the formulas. So if cell `C3` evaluates to `#ERROR!` then the formula
+`=SQRT(C3)` will return `#ERROR!`.
+
+Not all functions propagate errors in their arguments. For instancethe function `IF(condition, if_true, if_false)` will only propagate an error in the `if_false` argument if the `condition` is `FALSE`. This is called _lazy evaluation_, the function `IF` is _lazy_, it only evaluates the arguments when needed. The opposite of lazy evaulaution is called _eager evaluation_.
+
+Some functions also expect an error as an argument like [`ERROR.TYPE`](/functions/information/error.type) and will not propagate the error.
 
 
-### **`#####`**
+## See also
 
-**Cause:** The column isn’t wide enough to display the value.  
-**Fix:** Resize the column width to fit the content.
+The following functions are convenient when working with errors
+
+- [`ISERR(ref)`](/functions/information/iserr), `TRUE` if `ref` is any error type except the `#N/A` error.
+- [`ISERROR(ref)`](/functions/information/iserror), `TRUE` if `ref` is any error.
+- [`ISNA(ref)`](/functions/information/isna), `TRUE` if ref is `#N/A`.
+- [`ERROR.TYPE`](/functions/information/error.type) returns the numeric code for a given error.
+- [`IFERROR(ref, value)`](/functions/logical/iferror) returns `value` if the content of `ref` is an error.
+- [`IFNA(ref, value)`](/functions/logical/ifna) return `value` if `ref` is #N/A errors only.

docs/src/features/optional-arguments.md

@@ -0,0 +1,49 @@
+---
+layout: doc
+outline: deep
+lang: en-US
+---
+
+# Optional Arguments
+
+::: warning
+**Note:** This draft page is under construction 🚧
+:::
+
+Any IronCalc function may accept zero, one or more arguments, which are values passed to the function when it is called from a spreadsheet formula.
+
+Many function arguments are _required_. For such arguments, always pass a suitable value in the function call.
+
+Some function arguments are _optional_. Optional arguments need not be passed in the function call and, in such cases, the function instead uses a predefined default value.
+
+Consider a notional function called _FN\_NAME_, with the following syntax:
+
+<p style="font-weight:bold;text-align:center;">FN_NAME(<span title="Number" style="color:#1E88E5">arg1</span>, <span title="Number" style="color:#1E88E5">arg2</span>, <span title="Number" style="color:#1E88E5">arg3</span>, <span title="Number" style="color:#1E88E5">arg4</span>=def1, <span title="Number" style="color:#1E88E5">arg5</span>=def2,  <span title="Number" style="color:#1E88E5">arg6</span>=def3) => <span title="Number" style="color:#1E88E5" >fn_name</span></p>
+
+Notes about this syntax:
+
+* _FN_NAME_ is a function that takes six arguments (_arg1_, _arg2_, _arg3_, _arg4_, _arg5_ and _arg6_) and returns a value referred to as _fn_name_.
+* For convenience in this case, all arguments and the returned value are colour-coded to indicate that they are numbers.
+* Arguments _arg1_, _arg2_ and _arg3_ are <u>required</u> arguments and this would normally be stated in the **Argument descriptions** section of the function's description page.
+* Arguments _arg4_, _arg5_ and _arg6_ are <u>optional</u> arguments and again this would normally be stated in the **Argument descriptions** section of the function's description page. In addition, optional arguments are usually indicated by the specification of a default value in the syntax. 
+   * If _arg4_ is omitted, then the value _def1_ is assumed.
+   * If _arg5_ is omitted, then the value _def2_ is assumed. 
+   * If _arg6_ is omitted, then the value _def3_ is assumed.
+
+With this syntax, the following would all be valid calls to the _FN_NAME_ function:
+
+**=FN\_NAME(1,2,3)**. All optional arguments omitted.
+
+**=FN\_NAME(1,2,3,4)**. _arg4_ set to 4; optional arguments _arg5_ and _arg6_ assume default values.
+
+**=FN\_NAME(1,2,3,,5)**.  _arg5_ set to 5; optional arguments _arg4_ and _arg6_ assume  default values.
+
+**=FN\_NAME(1,2,3,,,6)**. _arg6_ set to 6; optional arguments _arg4_ and _arg5_ assume  default values.
+
+**=FN\_NAME(1,2,3,4,5)**. _arg4_ and  _arg5_ set to 4 and 5 respectively; optional argument _arg6_ assumes default value.
+
+**=FN\_NAME(1,2,3,4,,6)**. _arg4_ and _arg6_ set to 4 and 6 respectively; optional argument _arg5_ assumes default value.
+
+**=FN\_NAME(1,2,3,,5,6)**. _arg5_ and _arg6_ set to 5 and 6 respectively; optional argument _arg4_ assumes default value.
+
+**=FN\_NAME(1,2,3,4,5,6)**. Values passed for all optional arguments.

docs/src/features/units.md

@@ -0,0 +1,13 @@
+---
+layout: doc
+outline: deep
+lang: en-US
+---
+
+# Units
+
+::: warning
+**Note:** This draft page is under construction 🚧
+:::
+
+Some IronCalc functions return values that have units like currencies, percentage or dates.

docs/src/features/value-types.md

@@ -0,0 +1,67 @@
+---
+layout: doc
+outline: deep
+lang: en-US
+---
+
+# Value Types
+
+::: warning
+**Note:** This draft page is under construction 🚧
+:::
+
+In IronCalc a value, a result of a calculation can be one of:
+
+## Numbers
+
+Numbers in IronCalc are [IEEE 754 double precission](https://en.wikipedia.org/wiki/Double-precision_floating-point_format).
+
+Numbers are only displayed up to 15 significant figures. That's why '=0.1+0.2' is actually '0.3'
+
+Also numbers are compared up to 15 significant figures. So `=IF(0.1+0.2=0.3, "Valid", "Invalid")` will return `Valid`.
+
+However `=0.3-0.2-0.1` will not result in `0` in IronCalc.
+
+### Casting into numbers
+
+Strings and booleans are sometimes coverted to numbers
+
+`=1+"2"` => 3
+
+Some functions cast in weird ways:
+
+SUM(1, TRUE) => 2
+SUM(1, "1") => 2
+
+But SUM(1, A1) => 1 (where A1 is TRUE or "1")
+
+
+Sometimes the conversion happens like => "123"+1 is actually 124 and the SQRT("4") is 2 or the SQRT(TRUE) is 1.
+
+Some functions, however are more strict BIN2DEC(TRUE) is #VALUE!
+
+### Dates
+
+On spreadsheets a date is just the number of days since January 1, 1900.
+
+
+## Strings
+
+
+### Complex numbers
+
+On IronCal a complex number is just a string like "1+j3".
+
+
+## Booleans
+
+### Casting from numbers
+
+## Errors
+
+
+### Casting from strings
+
+"#N/A" => #N/A
+
+## Arrays

docs/src/functions/financial/fv.md

@@ -3,8 +3,10 @@ layout: doc
 outline: deep
 lang: en-US
 ---
-
 # FV function
+::: warning
+**Note:** This draft page is under construction 🚧
+:::
 ## Overview
 FV (<u>F</u>uture <u>V</u>alue) is a function of the Financial category that can be used to predict the future value of an investment or asset based on its present value.
 
@@ -13,34 +15,38 @@ FV can be used to calculate future value over a specified number of compounding
 If your interest rate varies between periods, use the [FVSCHEDULE](/functions/financial/fvschedule) function instead of FV.
 ## Usage
 ### Syntax
-**FV(rate, nper, pmt, pv, type)**
+**FV(<span title="Number" style="color:#1E88E5">rate</span>, <span title="Number" style="color:#1E88E5">nper</span>, <span title="Number" style="color:#1E88E5">pmt</span>, <span title="Number" style="color:#1E88E5">pv</span>=0, <span title="Boolean" style="color:#43A047">type</span>=FALSE) => <span title="Number" style="color:#1E88E5">fv</span>**
 ### Argument descriptions
-* *rate*. The fixed percentage interest rate or yield per period.
-* *nper*. The number of compounding periods to be taken into account. While this will often be an integer, non-integer values are accepted and processed.
-* *pmt*. The fixed amount paid or deposited each compounding period.
-* *pv* (optional). The present value or starting amount of the asset (default 0).
-* *type* (optional). A logical value indicating whether the payment due dates are at the end (0) of the compounding periods or at the beginning (any non-zero value). The default is 0 when omitted.
+* *rate* ([number](/features/value-types#numbers), required). The fixed percentage interest rate or yield per period.
+* *nper* ([number](/features/value-types#numbers), required). "nper" stands for <u>n</u>umber of <u>per</u>iods, in this case the number of compounding periods to be taken into account. While this will often be an integer, non-integer values are accepted and processed.
+* *pmt* ([number](/features/value-types#numbers), required). "pmt" stands for <u>p</u>ay<u>m</u>en<u>t</u>, in this case the fixed amount paid or deposited each compounding period. 
+* *pv* ([number](/features/value-types#numbers), [optional](/features/optional-arguments.md)). "pv" is the <u>p</u>resent <u>v</u>alue or starting amount of the asset (default 0).
+* *type* ([boolean](/features/value-types/#booleans), [optional](/features/optional-arguments.md)). A logical value indicating whether the payment due dates are at the end (FALSE or 0) of the compounding periods or at the beginning (TRUE or any non-zero value). The default is FALSE when omitted.
 ### Additional guidance
 * Make sure that the *rate* argument specifies the interest rate or yield applicable to the compounding period, based on the value chosen for *nper*.
-* The *pmt* and *pv* arguments should be expressed in the same currency unit. The value returned is expressed in the same currency unit.
+* The *pmt* and *pv* arguments should be expressed in the same currency unit.
 * To ensure a worthwhile result, one of the *pmt* and *pv* arguments should be non-zero.
 * The setting of the *type* argument only affects the calculation for non-zero values of the *pmt* argument.
-<!--@include: ../markdown-snippets/error-type-details.md-->
-
+### Returned value
+FV returns a [number](/features/value-types/#numbers) representing the future value expressed in the same [currency unit](/features/units) that was used for the *pmt* and *pv* arguments.
+### Error conditions
+* In common with many other IronCalc functions, FV propagates errors that are found in any of its arguments.
+* If too few or too many arguments are supplied, FV returns the [`#ERROR!`](/features/error-types.md#error) error.
+* If the value of any of the *rate*, *nper*, *pmt* or *pv* arguments is not (or cannot be converted to) a [number](/features/value-types#value), then FV returns the [`#VALUE!`](/features/error-types.md#value) error.
+* If the value of the *type* argument is not (or cannot be converted to) a [Boolean](/features/value-types#booleans), then FV again returns the [`#VALUE!`](/features/error-types.md#value) error.
+* For some combinations of valid argument values, FV may return a [`#NUM!`](/features/error-types.md#num) error or a [`#DIV/0!`](/features/error-types.md#div-0) error.
+<!--@include: ../markdown-snippets/error-type-details.txt-->
 ## Details
-* If *rate* = 0, FV is given by the equation:
-$$
-FV = -pv - (pmt \times nper)
-$$
+* If $\text{type} \neq 0$, $\text{fv}$ is given by the equation:
+$$ \text{fv} = -\text{pv} \times (1 + \text{rate})^\text{nper} - \dfrac{\text{pmt}\times\big({(1+\text{rate})^\text{nper}-1}\big) \times(1+\text{rate})}{\text{rate}}$$
 
-* If *rate* <> 0 and *type* = 0, FV is given by the equation:
-$$ FV = -pv \times (1 + rate)^{nper} - \dfrac{pmt\times\big({(1+rate)^{nper}-1}\big)}{rate}
-$$
-* If *rate* <> 0 and *type* <> 0, FV is given by the equation:
-$$ FV = -pv \times (1 + rate)^{nper} - \dfrac{pmt\times\big({(1+rate)^{nper}-1}\big) \times(1+rate)}{rate}
-$$
+* If $\text{type} = 0$, $\text{fv}$ is given by the equation:
+$$ \text{fv} = -\text{pv} \times (1 + \text{rate})^{\text{nper}} - \dfrac{\text{pmt}\times\big({(1+\text{rate})^\text{nper}-1}\big)}{\text{rate}}$$
+
+* For any $\text{type}$, in the special case of $\text{rate} = 0$, $\text{fv}$ is given by the equation:
+$$ \text{fv} = -\text{pv} - (\text{pmt} \times \text{nper}) $$
 ## Examples
-[See this example in IronCalc](https://app.ironcalc.com/?example=fv).
+[See some examples in IronCalc](https://app.ironcalc.com/?example=fv).
 
 ## Links
 * For more information about the concept of "future value" in finance, visit Wikipedia's [Future value](https://en.wikipedia.org/wiki/Future_value) page.

docs/src/functions/markdown-snippets/error-type-details.md

@@ -1 +0,0 @@
-* For information about the different types of errors that you may encounter when using IronCalc functions, visit our [Error Types](/features/error-types) page.

docs/src/functions/markdown-snippets/error-type-details.txt

@@ -0,0 +1 @@
+* For more information about the different types of errors that you may encounter when using IronCalc functions, visit our [Error Types](/features/error-types) page.