Add PV (present value) function

Author: Blake-Madden

TinyExprChanges.md

@@ -71,6 +71,7 @@ The following are changes from the original TinyExpr C library:
   - `not`: returns logical negation of value.
   - `permut`: alias for `npr()`, like the *Excel* function.
   - `power`: alias for `pow()`, like the *Excel* function.
+  - `pv`: returns the present value of an investment, like the *Excel* function.
   - `rand`: returns random number between `0` and `1`.
      Note that this implementation uses the Mersenne Twister (`mt19937`) to generate random numbers.
   - `round`: returns a number, rounded to a given decimal point.

docs/manual/functions.qmd

@@ -127,6 +127,7 @@ Any subsequent arguments that evaluate to NaN will be ignored.
 | DB(Cost, Salvage, Lifetime, Period, Month) | Returns the depreciation of an asset for a specified period using the fixed-declining balance method. |
 | EFFECT(NominalRate, Periods) | Returns the effective annual interest rate, provided the nominal annual interest rate and the number of compounding periods per year.<br>\linebreak NaN will be returned if *Periods* is < 1 or if *NominalRate* <= 0.  |
 | NOMINAL(EffectiveRate, Periods) | Returns the nominal annual interest rate, provided the effective rate and the number of compounding periods per year.<br>\linebreak NaN will be returned if *Periods* is < 1 or if *EffectiveRate* <= 0. |
+| PV(Rate, Periods, Payment, [FutureValue], [Type]) | Returns the present value of an investment based on a constant interest rate, a fixed number of periods, and periodic payments.<br>\linebreak *FutureValue* and *Type* are optional and default to 0.<br>\linebreak *Type* specifies when payments are due: 0 = end of period, 1 = beginning of period.<br>\linebreak NaN will be returned if *Periods* <= 0 or if any required argument is not finite. |
 
 Table: Financial Functions\index{functions!financial}
 :::

docs/manual/unknown-symbol-resolution.qmd

@@ -73,7 +73,7 @@ tep.set_unknown_symbol_resolver(ResolveResolutionSymbols);
 
 /* Will resolve to 288, and "RESOLUTION" will be added as a
    variable to the parser with a value of 96.
-   Also, beccause TinyExpr++ is case insensitive,
+   Also, because TinyExpr++ is case insensitive,
    "resolution" will also be seen as 96 once "RESOLUTION" was resolved.*/
 tep.evaluate("RESOLUTION * 3");
 ```

tests/tetests.cpp

@@ -24,7 +24,7 @@
 
 /*
  * TINYEXPR++ - Tiny recursive descent parser and evaluation engine in C++
- * Copyright (c) 2020-2023 Blake Madden
+ * Copyright (c) 2020-2026 Blake Madden
  *
  * C++ version of the TinyExpr library.
  *
@@ -4193,6 +4193,84 @@ TEST_CASE("NaN Comparison", "[nan]")
     }
 
 // Financial functions
+// --------------------------------------------------
+// PV
+// --------------------------------------------------
+TEST_CASE("PV", "[finance]")
+    {
+    te_parser tep;
+
+    // Excel: =PV(0.05/12, 60, -200)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05/12, 60, -200)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(10598.14), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.05/12, 60, -200, 0, 1)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05/12, 60, -200, 0, 1)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(10642.30), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.1, 1, -100)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.1, 1, -100)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(90.91), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0, 60, -200)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0, 60, -200)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(12000)));
+
+    // Excel: =PV(0, 10, 0, 1000)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0, 10, 0, 1000)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(-1000)));
+
+    // Excel: =PV(0.05, 10, -100)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 10, -100)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(772.17), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.05, 10, -100, 0)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 10, -100, 0)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(772.17), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.05, 10, -100, 0, 0)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 10, -100, 0, 0)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(772.17), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.05, 10, -100, 0, 2)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 10, -100, 0, 2)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(810.78), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.05, 10, -100, 0, -1)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 10, -100, 0, -1)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(810.78), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(-0.5, 5, -100)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(-0.5, 5, -100)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(6200), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(-1, 10, -100) -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PV(-1, 10, -100)"))));
+
+    // Excel: =PV(0.05, 0, -100) -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 0, -100)"))));
+
+    // Excel: =PV(0.05, -10, -100) -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, -10, -100)"))));
+
+    // Excel: =PV(NaN, 10, -100) -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PV(NaN, 10, -100)"))));
+
+    // Excel: =PV(0.05, NaN, -100) -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, NaN, -100)"))));
+
+    // Excel: =PV(0.05, 10, NaN) -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PV(0.05, 10, NaN)"))));
+
+    // Excel: =PV(0.08/12, 360, -1000)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.08/12, 360, -1000)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(136283.35), WITHIN_TYPE_CAST(0.0001)));
+
+    // Excel: =PV(0.03, 1, 0, 1000)
+    CHECK_THAT(WITHIN_TYPE_CAST(tep.evaluate("PV(0.03, 1, 0, 1000)")),
+               Catch::Matchers::WithinRel(WITHIN_TYPE_CAST(-970.87), WITHIN_TYPE_CAST(0.0001)));
+    }
+
 TEST_CASE("Nominal", "[finance]")
     {
     te_parser tep;

tinyexpr.cpp

@@ -26,7 +26,7 @@
 /*
  * TINYEXPR++ - Tiny recursive descent parser and evaluation engine in C++
  *
- * Copyright (c) 2020-2025 Blake Madden
+ * Copyright (c) 2020-2026 Blake Madden
  *
  * C++ version of the TinyExpr library.
  *
@@ -255,6 +255,52 @@ namespace te_builtins
                decimalPosition;
         }
 
+    [[nodiscard]]
+    static te_type te_pv(te_type rate, te_type nper, te_type pmt, te_type fv, te_type type)
+        {
+        if (!std::isfinite(rate) || !std::isfinite(nper) || !std::isfinite(pmt))
+            {
+            return te_parser::te_nan;
+            }
+
+        // optional args default like Excel
+        if (!std::isfinite(fv))
+            {
+            fv = 0;
+            }
+        if (!std::isfinite(type))
+            {
+            type = 0;
+            }
+
+        if (nper <= 0)
+            {
+            return te_parser::te_nan;
+            }
+
+        // Excel: rate <= -1 -> #NUM!
+        if (rate <= -1.0)
+            {
+            return te_parser::te_nan;
+            }
+
+        // coerce type to 0 or 1
+        type = (type != 0) ? 1 : 0;
+
+        if (rate == 0.0)
+            {
+            return -(fv + pmt * nper);
+            }
+
+        const te_type powVal = std::pow(1 + rate, nper);
+        if (!std::isfinite(powVal) || powVal == 0.0)
+            {
+            return te_parser::te_nan;
+            }
+
+        return -(fv + pmt * (1 + rate * type) * (powVal - 1) / rate) / powVal;
+        }
+
     [[nodiscard]]
     static te_type te_nominal(te_type effectiveRate, te_type periods)
         {
@@ -1499,6 +1545,8 @@ const std::set<te_variable> te_parser::m_functions = { // NOLINT
     { "pi", static_cast<te_fun0>(te_builtins::te_pi), TE_PURE },
     { "pow", static_cast<te_fun2>(te_builtins::te_pow), TE_PURE },
     { "power", /* Excel alias*/ static_cast<te_fun2>(te_builtins::te_pow), TE_PURE },
+    { "pv", static_cast<te_fun5>(te_builtins::te_pv),
+      static_cast<te_variable_flags>(TE_PURE | TE_VARIADIC) },
     { "rand", static_cast<te_fun0>(te_builtins::te_random), TE_PURE },
     { "round", static_cast<te_fun2>(te_builtins::te_round),
       static_cast<te_variable_flags>(TE_PURE | TE_VARIADIC) },

tinyexpr.h

@@ -26,7 +26,7 @@
 /*
  * TINYEXPR++ - Tiny recursive descent parser and evaluation engine in C++
  *
- * Copyright (c) 2020-2025 Blake Madden
+ * Copyright (c) 2020-2026 Blake Madden
  *
  * C++ version of the TinyExpr library.
  *