Module future_value

Future value calculations. Given an initial investment amount, a number of periods such as periods, and fixed or varying interest rates, what is the value of the investment at the end?

For most common usages, we recommend the future_value_solution function, which provides a better debugging experience and additional features.

For more complex scenarios, which involve varying rates in each period, we recommend the future_value_schedule_solution function.

To simply return an f64 value of the future value answer, use the future_value function.

Example

let (rate, periods, present_value, continuous_compounding) = (0.034, 10, 1_000, false);
let fv = finance_solution::future_value_solution(rate, periods, present_value, continuous_compounding);
dbg!(fv);

Outputs to terminal:

{
    calculated_field: FutureValue,
    continuous_compounding: false,
    rate: 0.034,
    periods: 10,
    fractional_periods: 10.0,
    present_value: 1000.0,
    future_value: 1397.0288910795477,
    formula: "1397.0289 = 1000.0000 * (1.034000 ^ 10)",
    symbolic_formula: "fv = pv * (1 + r)^n",
}

Formulas

Simple Compounding

With simple compound interest, the future value is calculated with:

Or with some more commonly-used variable names:

n is often used for the number of periods, though it may be t for time if each period is assumed to be one year as in continuous compounding. r is the periodic rate, though this may appear as i for interest.

Throughout this crate we use pv for present value and fv for future value. You may see these values called P for principal in some references.

Within the TvmSolution struct we record the formula used for the particular calculation using both concrete values and symbols. For example with $1,000 growing at 3.5% per period for 12 periods using simple compounding the struct contains these fields:

formula: "1511.0687 = 1000.0000 * (1.035000 ^ 12)",
symbolic_formula: "fv = pv * (1 + r)^n",

Continuous Compounding

With continuous compounding the formula is:

or:

With continuous compounding the period is assumed to be years and t (time) is often used as the variable name. Within this crate we stick with n for the number of periods so that it’s easier to compare formulas when they’re printed as simple text as part of the TvmSolution struct. For example with $1,000 growing at 3.5% per period for 12 periods using continuous compounding the struct contains these fields:

formula: "1521.9616 = 1000.0000 * 2.718282^(0.035000 * 12)",
symbolic_formula: "fv = pv * e^(rt)",

This is the same as the example in the previous section except that it uses continuous compounding.

Functions

future_value

Returns the value of an investment after it has grown or shrunk over time, using a fixed rate.

future_value_schedule

Calculates a future value based on rates that change for each period.

future_value_schedule_solution

Calculates a future value based on rates that change for each period, returning a struct with all of the inputs and results.

future_value_solution

Calculates the value of an investment after it has grown or shrunk over time and returns a struct with the inputs and the calculated value. This is used for keeping track of a collection of financial scenarios so that they can be examined later.