finance-solution

finance-solution is a financial library for time-value-of-money problems. 💸

People who will find this crate helpful include:

• Students of Finance who want to solve their financial problems using something better than a crude handheld calculator. Using this library also reduces the chance of human error, and provides better output and data displays than Excel.
• New developers who want to learn Rust using Finance as a topic.
• Experienced Rust developers who want to learn more about finance.
• Serious Rust developers who want to build financial software, and prefer to rely on a rigourously tested library instead of reinventing the wheel and spending hundreds of hours to develop and test their own library.

Currently, this library is geared towards the basic financial equations, regarding:

• Simple Time-Value-of-Money formulas -- this includes present_value, future_value, rate, and periods (known as NPER in Excel).
• Cashflow Time-Value-of-Money formulas -- this includes present_value_annuity, future_value_annuity, net_present_value, and payment (known as PMT in Excel).
• Rate conversions -- this includes all conversions between apr, ear, and epr, and also includes conversion for continuous compounding (apr_continuous, ear_continuous).

Examples

A business partner will give you $4,000 in 3 years. Your rate-of-return in the market is 5%. How much is the deal worth to you right now?

uses present_value() to return f64 value

let future_value = 4_000;
let periods = 3;
let rate = 0.05;
let pv = present_value(rate, periods, future_value);
dbg!(pv);

// PRINTS TO TERMINAL:
// pv = 3455.350394125904 

The crate also provides helper functions for rounding, such as round_4 to round to four decimals places. See round for more details.

For the same problem above, you can use the _solution function to see a better output and provide additional functionality.

uses present_value_solution() to return a custom "solution" struct

let future_value = 4_000;
let periods = 3;
let rate = 0.05;
let answer = present_value_solution(rate, periods, future_value);
dbg!(answer);

// PRINTS TO TERMINAL:
// answer = TvmSolution {
//    calculated_field: PresentValue,
//    rate: 0.05,
//    periods: 3,
//    fractional_periods: 3.0,
//    present_value: 3455.350394125904,
//    future_value: 4000.0,
//    formula: "3455.3504 = 4000.0000 / (1.050000 ^ 3)",
//    formula_symbolic: "pv = fv / (1 + r)^n",
//}

If you want to explore what happens in each period of the calculation, you can use the .series() method on any solution output:

uses present_value_solution().series() to return a vec of each period

let future_value = 4_000;
let periods = 3;
let rate = 0.05;
let answer = present_value_solution(rate, periods, future_value);
dbg!(answer.series());

// PRINTS TO TERMINAL:
// answer.series() = TvmSeries(
//     [
//         TvmPeriod {
//             period: 0,
//             rate: 0.0,
//             value: 3455.3503941259037,
//             formula: "3455.3504 = 3628.1179 / 1.050000",
//             formula_symbolic: "value = {next period value} / (1 + r)",
//         },
//         TvmPeriod {
//             period: 1,
//             rate: 0.05,
//             value: 3628.117913832199,
//             formula: "3628.1179 = 3809.5238 / 1.050000",
//             formula_symbolic: "value = {next period value} / (1 + r)",
//         },
//         TvmPeriod {
//             period: 2,
//             rate: 0.05,
//             value: 3809.523809523809,
//             formula: "3809.5238 = 4000.0000 / 1.050000",
//             formula_symbolic: "value = {next period value} / (1 + r)",
//         },
//         TvmPeriod {
//             period: 3,
//             rate: 0.05,
//             value: 4000.0,
//             formula: "4000.0000",
//             formula_symbolic: "value = fv",
//         },
//     ],
// )

To view each period in a table format, use the .print_table() method.

uses present_value_solution().series().print_table() to return a pretty-print table

use num_format::{Locale};

let future_value = 4_000;
let periods = 3;
let rate = 0.05;
let answer = present_value_solution(rate, periods, future_value);
dbg!(answer.series().print_table());
// or use .print_table_locale() to specify your formatting preferences.
dbg!(answer.series().print_table_locale(&Locale::en, 4));

// PRINTS TO TERMINAL:
// period    rate       value
// ------  ------  ----------
//      0  0.0000  3,455.3504
//      1  0.0500  3,628.1179
//      2  0.0500  3,809.5238
//      3  0.0500  4,000.0000

In the table above, you can specify the locale, if you prefer a different format for the money values. For example, your country may prefer 8.532,11 instead of 8,532.11. The pretty-printed tables are easily copy&pasted into a spreadsheet.

The .print_table() function can be especially helpful when analyzing payment and cashflow information.

uses payment_solution().series().print_table() to return a pretty-print table

let present_value = 13_000;
let periods = 5;
let rate = 0.08;
let answer = payment_solution(rate, periods, present_value, 0);
dbg!(answer.series().print_table());

// PRINTS TO TERMINAL:
// period  payments_to_date  payments_remaining    principal  principal_to_date  principal_remaining     interest  interest_to_date  interest_remaining
// ------  ----------------  ------------------  -----------  -----------------  -------------------  -----------  ----------------  ------------------
//      1       -3,255.9339        -13,023.7356  -2,215.9339        -2,215.9339         -10,784.0661  -1,040.0000       -1,040.0000         -2,239.6695
//      2       -6,511.8678         -9,767.8017  -2,393.2086        -4,609.1425          -8,390.8575    -862.7253       -1,902.7253         -1,376.9443
//      3       -9,767.8017         -6,511.8678  -2,584.6653        -7,193.8078          -5,806.1922    -671.2686       -2,573.9939           -705.6757
//      4      -13,023.7356         -3,255.9339  -2,791.4385        -9,985.2464          -3,014.7536    -464.4954       -3,038.4893           -241.1803
//      5      -16,279.6695              0.0000  -3,014.7536       -12,999.0000              -0.0000    -241.1803       -3,279.6695              0.0000

As you can see in the table above, the finance-solution library offers more than "just the answer" to the problem (-3,255.9339) but also provides a detailed visual of what is happening in each period.

Benefits of using finance-solution

This library has undergone hundreds of hours spent designing the library to be ergonomic, rustic, and accurate.

Bonus highlights include:

• finance-solution provides both f64 functions almost all functions can add _solution to the function name to provide a more helpful output, with additional functionality. We highly recommend you use the _solution functions when you can!
• the _solution structs add a trivial amount of time to the code execution, 12-30 nanoseconds... as shown in our benches section.
• all the formulas have been rigorously tested, both in unit tests, integration tests, and "symmetry" tests.
• function parameters follow consistent ordering when possible, for example "rate, periods, ..." so the user can almost guess the ordering of parameters.
• table output of _solution().series().print_table() allows the user to specify locale for specific currency formatting, and the output can easily be copy&pasted into spreadsheets (Excel, Google Sheet, etc).
• Sample word problems are provided in the examples folder of the repo, which allows users to see how finance-solution can be used to solve financial problems.
• Functions have built-in asserts, panics, and even warn! logs to prevent users from making common mistakes, especially with rates.
• Functions are built for ease-of-use, so the user can provide f64 or f32 or u32 or i8... Any numeric format for money is accepted into the function and converted into f64, for user convenience.
• Functional parameters like rate and periods are strictly enforced to f64 for rate and u32 for periods. Periods are not allowed to be negative, and periods larger than 2000 will likely lead to computer-inherent floating point representation errors, so we provide a warn! for situations when we believe the inputs may create inaccuracies in the final output. It is up to the user to enable warn logs.

To-do items for this crate

We have a backlog of items we intend to include in this crate:

• IRR
• MIRR
• WACC
• PV and FV annuity schedules (varying rates and cashflows)
• Payback Period
• Profitability Index
• Return on investment
• Amortization
• PPMT
• IPMT
• Perpetuities
• CUMPRINC
• CUMIPMT
• Bonds
• ROI
• Rule of 72 (and related fns)
• SLN
• XNPV
• XIRR