diff --git a/docs/src/.vitepress/config.mts b/docs/src/.vitepress/config.mts index c6d7d94..4f42410 100644 --- a/docs/src/.vitepress/config.mts +++ b/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", diff --git a/docs/src/features/error-types.md b/docs/src/features/error-types.md index c392e7b..7f361a4 100644 --- a/docs/src/features/error-types.md +++ b/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. diff --git a/docs/src/features/optional-arguments.md b/docs/src/features/optional-arguments.md new file mode 100644 index 0000000..8940765 --- /dev/null +++ b/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: + +

FN_NAME(arg1, arg2, arg3, arg4=def1, arg5=def2, arg6=def3) => fn_name

+ +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 required arguments and this would normally be stated in the **Argument descriptions** section of the function's description page. +* Arguments _arg4_, _arg5_ and _arg6_ are optional 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. diff --git a/docs/src/features/units.md b/docs/src/features/units.md new file mode 100644 index 0000000..2a6c246 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/src/features/value-types.md b/docs/src/features/value-types.md new file mode 100644 index 0000000..0bd2efd --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/src/functions/financial/fv.md b/docs/src/functions/financial/fv.md index a71ff3b..36d6303 100644 --- a/docs/src/functions/financial/fv.md +++ b/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 (Future Value) 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(rate, nper, pmt, pv=0, type=FALSE) => fv** ### 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 number of periods, 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 payment, 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 present value 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. - - +### 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. + ## 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. diff --git a/docs/src/functions/markdown-snippets/error-type-details.md b/docs/src/functions/markdown-snippets/error-type-details.md deleted file mode 100644 index e4829bc..0000000 --- a/docs/src/functions/markdown-snippets/error-type-details.md +++ /dev/null @@ -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. \ No newline at end of file diff --git a/docs/src/functions/markdown-snippets/error-type-details.txt b/docs/src/functions/markdown-snippets/error-type-details.txt new file mode 100644 index 0000000..a5674b3 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/xlsx/tests/docs/FV.xlsx b/xlsx/tests/docs/FV.xlsx index 0f76d4d..28575ad 100644 Binary files a/xlsx/tests/docs/FV.xlsx and b/xlsx/tests/docs/FV.xlsx differ