Add PMT function

Author: Blake-Madden

TinyExprChanges.md

@@ -3,11 +3,11 @@ The following are changes from the original TinyExpr C library:
 - Compiles as C++17 code.
 - `te_*` functions are now wrapped in a `te_parser` class.
 - `te_interp()`, `te_compile()`, and `te_eval()` have been replaced with `te_parser::compile()`, `te_parser::evaluate()`, and `te_parser::set_variables_and_functions()`.
-    `set_variables_and_functions()` sets your list of custom functions and variables. `compile()` compiles and optimizes an expression.
-    Finally, `evaluate()` will use the already compiled expression and return its result.
-    `evaluate()` also has an overload that compiles and evaluates an expression in one call.
-- Variable/function types (e.g., `TE_FUNCTION0`) have been removed; types are now deduced by the compiler. The available flags
-  for variables and functions are now just combinations of `TE_DEFAULT`, `TE_PURE`, and `TE_VARIADIC`.
+  `set_variables_and_functions()` sets your list of custom functions and variables. `compile()` compiles and optimizes an expression.
+  Finally, `evaluate()` will use the already compiled expression and return its result.
+  `evaluate()` also has an overload that compiles and evaluates an expression in one call.
+- Variable/function types (e.g., `TE_FUNCTION0`) have been removed; types are now deduced by the compiler.
+  The available flags for variables and functions are now just combinations of `TE_DEFAULT`, `TE_PURE`, and `TE_VARIADIC`.
 - Formula parsing is now case insensitive.
 - Added support for variadic functions (can accept 1-24 arguments); enabled through the `TE_VARIADIC` flag.
   (Refer to the `AVERAGE()` function in `tinyexp.cpp` for an example.)
@@ -34,12 +34,12 @@ The following are changes from the original TinyExpr C library:
   - `and`: returns true (i.e., non-zero) if all conditions are true (accepts 1-24 arguments).
   - `average`: returns the mean for a range of values (accepts 1-24 arguments).
   - `bitand`: bitwise AND.
-  - `bitlrotate`: bitwise left rotate. Versions of this are available for 8-, 16-, 32-, and 64-bit integers (if supported by the platform). (Only available if compiled as C++20.)
+  - `bitlrotate`: bitwise left rotate. Versions of this are available for 8-, 16-, 32-, and 64-bit integers (if supported by the platform).
   - `bitlshift`: left shift.
      Negative shift amount arguments (similar to *Excel*) are supported.
   - `bitnot`: bitwise NOT. Versions of this are available for 8-, 16-, 32-, and 64-bit integers (if supported by the platform).
   - `bitor`: bitwise OR.
-  - `bitrrotate`: bitwise right rotate. Versions of this are available for 8-, 16-, 32-, and 64-bit integers (if supported by the platform). (Only available if compiled as C++20.)
+  - `bitrrotate`: bitwise right rotate. Versions of this are available for 8-, 16-, 32-, and 64-bit integers (if supported by the platform).
   - `bitrshift`: right shift.
      Negative shift amount arguments (similar to *Excel*) are supported.
   - `bitxor`: bitwise XOR.
@@ -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.
+  - `pmt`: returns the periodic payment for an investment or loan based on a constant interest rate, a fixed number of periods, and a present value (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.
@@ -127,8 +128,7 @@ The following are changes from the original TinyExpr C library:
 - All data fields are now initialized.
 - Added [Doxygen](https://github.com/doxygen/doxygen) comments.
 - Removed `te_print()` debug function.
-- Added `list_available_functions_and_variables()` function to display all available built-in and custom
-  functions and variables.
+- Added `list_available_functions_and_variables()` function to display all available built-in and custom functions and variables.
 - Added `get_expression()` function to get the last formula used.
 - Added `[[nodiscard]]` attributes to improve compile-time warnings.
 - Added `constexpr` and `noexcept` for C++ optimization.

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. |
+| PMT(Rate, Periods, PresentValue, [FutureValue], [Type]) | Returns the periodic payment for an investment or loan based on a constant interest rate, a fixed number of periods, and a present value.<br>\linebreak Note that *FutureValue* and *Type* are optional and default to 0.<br>\linebreak Also, *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. |
 | 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 Note that *FutureValue* and *Type* are optional and default to 0.<br>\linebreak Also, *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}

tests/tetests.cpp

@@ -4287,6 +4287,105 @@ TEST_CASE("PV", "[finance]")
             WITHIN_TYPE_CAST(0.0001)));
     }
 
+TEST_CASE("PMT", "[finance]")
+    {
+    te_parser tep;
+
+    // Excel: =PMT(0.05/12, 60, 10000)
+    // Monthly payment on a $10,000 loan at 5% for 5 years
+    // Excel result ~ -188.71
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05/12, 60, 10000)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-188.71),
+            WITHIN_TYPE_CAST(0.00002)));
+
+    // Excel: =PMT(0.05/12, 60, 10000, 0, 1)
+    // Payments at beginning of period -> slightly smaller payment
+    // Excel result ~ -187.93
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05/12, 60, 10000, 0, 1)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-187.93),
+            WITHIN_TYPE_CAST(0.00001)));
+
+    // Excel: =PMT(0, 60, 12000)
+    // Zero interest: straight-line repayment
+    // Excel result = -200
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0, 60, 12000)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-200)));
+
+    // Excel: =PMT(0.1, 1, 100)
+    // One-period loan at 10%
+    // Excel result = -110
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.1, 1, 100)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-110),
+            WITHIN_TYPE_CAST(0.00001)));
+
+    // Excel: =PMT(0.05/12, 60, 10000, 1000)
+    // Loan with balloon payment
+    // Excel result ~ -203.42
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05/12, 60, 10000, 1000)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-203.42),
+            WITHIN_TYPE_CAST(0.00002)));
+
+    // Excel data:
+    // Annual interest rate: 8%
+    // Number of months: 10
+    // Loan amount: $10,000
+
+    // Excel: =PMT(A2/12, A3, A4)
+    // Monthly payment
+    // Excel result: ($1,037.03)
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.08/12, 10, 10000)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-1037.03),
+            WITHIN_TYPE_CAST(0.00002)));
+
+    // Excel: =PMT(A2/12, A3, A4, , 1)
+    // Payments at beginning of period
+    // Excel result: ($1,030.16)
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.08/12, 10, 10000, 0, 1)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-1030.16),
+            WITHIN_TYPE_CAST(0.00002)));
+
+    // Excel data:
+    // Annual interest rate: 6%
+    // Term: 18 years
+    // Target future value: $50,000
+
+    // Excel: =PMT(A9/12, A10*12, 0, A11)
+    // Monthly savings required
+    // Excel result ~ ($129.08)
+    CHECK_THAT(
+        WITHIN_TYPE_CAST(tep.evaluate("PMT(0.06/12, 18*12, 0, 50000)")),
+        Catch::Matchers::WithinRel(
+            WITHIN_TYPE_CAST(-129.08),
+            WITHIN_TYPE_CAST(0.00005)));
+
+    // Excel: rate <= -1 -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(-1, 10, 1000)"))));
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(-1.5, 10, 1000)"))));
+
+    // Excel: nper <= 0 -> #NUM!
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05, 0, 1000)"))));
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05, -10, 1000)"))));
+
+    // Non-finite args -> NaN
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(NaN, 10, 1000)"))));
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05, NaN, 1000)"))));
+    CHECK(std::isnan(WITHIN_TYPE_CAST(tep.evaluate("PMT(0.05, 10, NaN)"))));
+    }
+
 TEST_CASE("Nominal", "[finance]")
     {
     te_parser tep;

tinyexpr.cpp

@@ -255,6 +255,51 @@ namespace te_builtins
                decimalPosition;
         }
 
+    [[nodiscard]]
+    static te_type te_pmt(te_type rate, te_type nper, te_type pv, te_type fv, te_type type)
+        {
+        if (!std::isfinite(rate) || !std::isfinite(nper) || !std::isfinite(pv))
+            {
+            return te_parser::te_nan;
+            }
+
+        if (!std::isfinite(fv))
+            {
+            fv = 0;
+            }
+        if (!std::isfinite(type))
+            {
+            type = 0;
+            }
+
+        if (nper <= 0)
+            {
+            return te_parser::te_nan;
+            }
+
+        if (rate <= -1.0)
+            {
+            return te_parser::te_nan;
+            }
+
+        // coerce type to 0 or 1
+        type = (type != 0) ? 1 : 0;
+
+        // zero-interest
+        if (rate == 0.0)
+            {
+            return -(pv + fv) / nper;
+            }
+
+        const te_type powVal = std::pow(1 + rate, nper);
+        if (!std::isfinite(powVal) || powVal == 0.0)
+            {
+            return te_parser::te_nan;
+            }
+
+        return -((pv * powVal) + fv) * rate / ((1 + (rate * type)) * (powVal - 1));
+        }
+
     [[nodiscard]]
     static te_type te_pv(te_type rate, te_type nper, te_type pmt, te_type futureValue, te_type type)
         {
@@ -298,7 +343,8 @@ namespace te_builtins
             return te_parser::te_nan;
             }
 
-        return -(futureValue + pmt * (1 + rate * type) * (powVal - 1) / rate) / powVal;
+        const te_type annuity = (pmt * (1 + (rate * type)) * (powVal - 1)) / rate;
+        return -(futureValue + annuity) / powVal;
         }
 
     [[nodiscard]]
@@ -1545,6 +1591,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 },
+    { "pmt", static_cast<te_fun5>(te_builtins::te_pmt),
+      static_cast<te_variable_flags>(TE_PURE | TE_VARIADIC) },
     { "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 },