From 17cf519d41e17a43e4883a7f58e4b525bb649683 Mon Sep 17 00:00:00 2001
From: stevethesleeve <57075240+stevethesleeve@users.noreply.github.com>
Date: Sat, 7 Dec 2024 11:25:57 +0000
Subject: [PATCH] Update fv files (#162)

* Files updated for FV function documentation.

* Further FV changes
---
 docs/src/functions/financial/fv.md            |  46 ++++++++++++++++--
 .../markdown-snippets/error-type-details.md   |   1 +
 xlsx/tests/docs/FV.xlsx                       | Bin 9998 -> 10164 bytes
 3 files changed, 43 insertions(+), 4 deletions(-)
 create mode 100644 docs/src/functions/markdown-snippets/error-type-details.md

diff --git a/docs/src/functions/financial/fv.md b/docs/src/functions/financial/fv.md
index 5e56976..8afdaeb 100644
--- a/docs/src/functions/financial/fv.md
+++ b/docs/src/functions/financial/fv.md
@@ -4,8 +4,46 @@ outline: deep
 lang: en-US
 ---
 
-# FV
+# FV function
+## 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.
 
-::: warning
-🚧 This function is implemented but currently lacks detailed documentation. For guidance, you may refer to the equivalent functionality in [Microsoft Excel documentation](https://support.microsoft.com/en-us/office/excel-functions-by-category-5f91f4e9-7b42-46d2-9bd1-63f26a86c0eb).
-:::
\ No newline at end of file
+FV can be used to calculate future value over a specified number of compounding periods. A fixed interest rate or yield is assumed over all periods, and a fixed payment or deposit can be applied at the start or end of every period.
+
+If your interest rate varies between periods, use the [FVSCHEDULE](./FVSCHEDULE) function instead of FV.
+## Usage
+### Syntax
+**FV(rate, nper, pmt, pv, type)**
+### 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.
+### 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.
+* 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-->
+
+## Details
+* If *rate* = 0, FV solves the equation:
+$$
+FV = -pv - (pmt \times nper)
+$$
+
+* If *rate* <> 0 and *type* = 0, FV solves 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 solves the equation:
+$$ FV = -pv \times (1 + rate)^{nper} - \dfrac{pmt\times\big({(1+rate)^{nper}-1}\big) \times(1+rate)}{rate}
+$$
+## Examples
+[See this example 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.
+* See also IronCalc's [NPER](./NPER), [PMT](./PMT), [PV](./PV) and [RATE](./RATE) functions.
+* Visit Microsoft Excel's [FV function](https://support.microsoft.com/en-gb/office/fv-function-2eef9f44-a084-4c61-bdd8-4fe4bb1b71b3) page.
+* Both [Google Sheets](https://support.google.com/docs/answer/3093224) and [LibreOffice Calc](https://wiki.documentfoundation.org/Documentation/Calc_Functions/FV) provide versions of the FV function.
\ No newline at end of file
diff --git a/docs/src/functions/markdown-snippets/error-type-details.md b/docs/src/functions/markdown-snippets/error-type-details.md
new file mode 100644
index 0000000..e4829bc
--- /dev/null
+++ b/docs/src/functions/markdown-snippets/error-type-details.md
@@ -0,0 +1 @@
+* 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/xlsx/tests/docs/FV.xlsx b/xlsx/tests/docs/FV.xlsx
index e4b342f6792012443e0c95b00ed73cee3b50d58c..0f76d4dbbe2bee4962bde577eb82d63dcf91d05d 100644
GIT binary patch
delta 3028
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

delta 2854
zcmZ8jX*3iJ7aqoveM}>}u?|BaTb3-NA={wPv{;g|QxOK4i6k=C5!o8cgbG<QBx_?y
zwq98V*%`?)){yPf`{V07-#zD^^PF>^`{SPHx#!;ZR`Hf)Lo93yp}R#%KmcHoFv)Tn
zhkor~=RvL~NZKiCw#qAMjjFwVb3oULN+f4~gAdh5Q>kM5SXY{$|KS}pdPH?DqN>}X
z-OXgkolwo}CFb_K`i?867AEb%ez}S(dqK(ehZC*wD6qk2_uGY0JrBUw=yXT34{R1T
zvoa+ynqKGLhd&SK^pbS`3`Lbsr9kp<B-_E~9ul(|>dtX`;!OJxd|<t+7HXvKt%npV
z$WlQvyg_c*81Ei{Ww%G|*i@fgCyxVKfNx(sTtEbr^gNDjFPNLnWvmXO{u3x7#(yY)
zaEX&`?)&GGdS|f0NY#0uyT5qYtiCa<4Qg1X6W{D%Lhe{lwb43XHoYQy?E@?B^fnh~
zzLPOUyu?v~fr(CV?+MR*)!RE%oLBw$fqKR8Lz${Cwy(VScva54AhlW$Kb4L3@tmw1
zMT)+?Ij~+fw@BL;pZ6-|dw{AnQ$&20IxisU6_HrM<Q(~&R40+#<|Bo88rq1p^Vbcu
zC+FPrK^(0J6k1=+QCj7@p3FLnL)f3Z<|+ElHAJMif$bhnMmntEZMj^_&xmT2#T$DY
z_1Z7BF!US)HYTeQ<s|=hDR9fOX}0G2;p0ft(&<}<H(Ayxd%XxoC`S3q=5;@=aiwH)
zlL4;asFv{a&%zv>3|v=d8#;m?(Vbj$VhdBDLcXV5DCE;a(XdoEYDY^e?xk+}&g%ow
ztSR5bY7$}2@g#dl!KnD7{8tJU!f0i7?JITvV2t*Nxxa}S_m@BVT^++#<9%B*L;9^p
z$I1)bt5wIEPHAqf->+Hbr(cyYw|<`Btt?18%vmaDYNMvV3A2`YHf({b(v{`rU6%j^
zx>FU+ID6a6lPsiq{SUf+;Xb{0yWNoAKT&B=La!=#7bhIBeXHiH-305kAxuusBtP>C
zLDRPrp>NIcW|1olA7z-U6AYi-7YRv}0ESSFry#rJ@V*!q>dU)=iF}>W%PnTv9vP&h
z{Pp~Xlg&r>Z~Phn;i2NK71H*KS{=m6%Bq~j=o6s+Nzm#;D-FLo+zHg9yzHs2vhoDH
zoSzTHv?4~e)ig_cSoqr9;cr6FbGKg~;Yp(X<?>Tlks^)JUNP7ZrA5yQ>Zx>9T3&T;
z?8p@Z97k^=XO?~;DLab;>pzjBoezR>Y1y74jz*@K+OV3dk+?J8^xLJnaGXWMvi4Q=
z7TuR%8&CiMaCAgy5d~GIvm+VV$1Vzws51compBOXoZ>i#yCcewD7x&jKC*$QhaVnu
z!VYb)*sWHwSEJFxR$eyKrNOMR+(_4iT#s?gG26YjRM#77x$heC5v_t@ba}EO4^EH-
z8?*<UsSPl~K6HvY3BKB1n_)VJFyg-1vAi_%bipz+&WFMNQDn~*Qb4H^ysD15b;)G=
z>y%l3+$|h8v^!&D9PpMkDOoKhFH0V#?I)c=6N>T`YIZK&y@HsJ2LY3{iYLf<)v_7W
zLz58IOdqIUNeHqy60)LfV48#3En9i-tPm4MpTV!)yt`_$YGI{8*?&R+e|LW?e9lls
zcktmb7QyjlC;h?jk=+Z;e3qAy6HWZK>kY}%Yq<31bxnOipVn2oaEdm*Mh;1h!Dl~o
zR$zEfnWjWtYp|e5I+CW&6I+OV?n$S%7xYy!2N{E?L3{%4@_zhjoou<43yDM`W8kj=
z&3oQkC%`qp&1lori(Xrw(<7Di9)ag2@noK5v&FbH{mEF~-&6!GOdx2QZ3QvC*eT+F
zgbTgbCNa`iNnc!h9W@8qcn2%Wb-uCCurTHZS{%$>6Uf|NfG<)+PPbF@*5m|3<%ht$
z7_OAnBWPRvvO+|1c9BD@>cS6L{IgA#!kt0w60EM$`OXBx;y}>!0atDSD{*S+43ntY
z4$mJK{A-02JJj8LWyrq5slrkut{Hm>kdJ^c>TO+l9fY*m>T~6*82dFbMC0W&M$Unl
zyDf}gu60V$$K%`02kbK>^@)ds4aJ)b3x^ue?BEb<+J}oHxUsp-QmgrGS|8BKLT#DS
z85FQIGV`?Aok>M*een8H$wehqq}$it2-=!kQu}g_TpGIuS|pWS4{eJxXYS(Lx-3Cs
zk9#I9K4Usp6pfN{Iivh;E)c6Q&MXK^D5_jqgeOJ4{8a<=!?Ube+o`L6bV~`b8;o^w
zM_!&ey8dJSqi!TgjhJY=Dx2W69Hwky%LFH|lgdf`1NyPu)h*;{ho-00@h7RDZ+Vv1
zjT(c6RVC^(jZ@3ZQ$lbC_9!7<{*3l68cjlL)yuOvS?&&8Ipb2IVA=EjTjrh$j#hC?
zW}ebRm!))2y6PL+eV;$<Gj4DYoFXM&w+@15Q^CcUdZycGGXuX8rrU)w7TtA%-#&i;
zOQ(vX*!oh%+rf{FzT<Uoi`XV#p1RWReYnh$<xLsIh1#b*%<6LhGYEt~=CM6ta*o<y
zD5Y$i$E*I7D@Jq$E6nMnCLMCLW9tNDlum!90x~l-RV`OpaNRi2Bl3-!H<T8D!%g*|
zMW7e68+<|xcTjHKg*Pl+TWL?e5t$rrZM*I<RJ!u|a<Z{Od^{VErI#U$iHhJ75az(M
zpeOW*BZ;mt*DY&g@}~GEKh;rYDSoWU73>Ckb+~72hWI|Stt*x=ADCA6LbZZqDE9Ik
zP=Hi!5o0OF4c#k5E9WH@)Ibb*^ySJp5_l|;D0(vHh23Iil}gWxd~Y+OpB?Bakt!)-
zv2B}X2fiq{T!~Uvr3GVD)l4=1>C91Z>9_9=c79TtxiCCGuTm)MU@kNN+5W`9#+Ta;
z@LAh}-ovNp;RX*Ewf36#`j5#IoM=L$C?Ad}Eze3i9%cDBLC1;lR&sIncDdm0?BT13
z@$t6rL9l;P1~GrFpA`MH<l{LY+4r6!SN1C~@_{#d2kCaikL9==zVDn}d#k&s?N!U~
zXV)Pn&15-*c)GHMntYAp?`~cuS=8geaO>uig0+G5p7=nT_ZCv}97v%I-mNDKAHKSo
z5vwdUH+w2?2;O)<<^08d;Ek5q?BXvKse1edqXN8qo1q|^alohgcl+y86b{=X>m$kv
ztDoRV!=DkDeJ*o<GpQs)r5SMeWG5?%IHYv~wa?8(KXZ`pFX59`G)yqJxRSpX*ED8)
zIt5TVTAfC|QPRT-oyyvq$r4^~MGQ8J;rZg^t--BwfL0;JezJkmfJ#<=llB|U5@BX$
z?FggT_22St8D(uvl^$vWvP~>6NvEA_4Rq$!nyD3{CZ1AsYsc?u#<<J#39hl~cc2eA
zG~;FjQzzvL<EOa=ekMg*n)Dcx4%Gs9COI!~fm13qW5D~%0XInp{yAuvCH(uPJ<Gxx
z8x6O|nzcMv@NHzDe2qnyoqaa!4c(HxH@Vhhr2;uB^LS-ozj}ea4)sDA$!xcThRJ(y
zqxf}zLgQ*20E^rAK{lvi{G4t#0eK#(sX(+8-VIY+s*rbt3ePzwN3Io{sV28b*N4)_
zkIqgQi7L**TXE4rc0cb6e#o|pb~8wyiKSn{G7y?XA(cv!I>7(=H~nQS8J-e8$(#}X
zd+Y!Jfn&e?jZOkP%!omQU=1^1fD)2m;==!369xbP@|Spwv<O`=S>gZp-d~D5fm>Ee
k<X>Trd%YL|0N%gFW3(?uK*{PdhDs3dvXU&?(tnEo0p&PF761SM