Function future_value_solution

pub fn future_value_solution<T>(
    rate: f64,
    periods: u32,
    present_value: T,
    continuous_compounding: bool,
) -> TvmSolution
where
    T: Into<f64> + Copy,

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.

See the future_value module page for the formulas.

Related functions:

• For simply calculating a single future value using a fixed rate use [future_value].
• To calculate the future value if the rates vary by period use future_value_schedule.
• To calculate the future value with varying rates and return a struct that can produce the period-by-period values use future_value_schedule_solution.

Arguments

• rate - The rate at which the investment grows or shrinks per period, expressed as a floating point number. For instance 0.05 would mean 5% growth. Often appears as r or i in formulas.
• periods - The number of periods such as quarters or periods. Often appears as n or t.
• present_value - The starting value of the investment. May appear as pv in formulas, or C for cash flow or P for principal.
• continuous_compounding - True for continuous compounding, false for simple compounding.

Panics

The call will fail if rate is less than -1.0 as this would mean the investment is losing more than its full value every period.

Examples

Calculate a future value and examine the period-by-period values.

use finance_solution::*;
// The rate is 1.2% per month.
let rate = 0.012;

// The investment will grow for 8 months.
let periods = 8;

// The initial investment is $200,000.
let present_value = -200_000;

let continuous_compounding = false;

let solution = future_value_solution(rate, periods, present_value, continuous_compounding);
dbg!(&solution);

let future_value = solution.future_value();
assert_rounded_4(future_value, 220_026.0467);

// Examine the formulas.
let formula = solution.formula();
dbg!(&formula);
assert_eq!(formula, "220026.0467 = 200000.0000 * (1.012000 ^ 8)");
let symbolic_formula = solution.symbolic_formula();
dbg!(&symbolic_formula);
assert_eq!(symbolic_formula, "fv = -pv * (1 + r)^n");

// Calculate the value at the end of each period.
let series = solution.series();
dbg!(&series);

Create a collection of future value calculations ranging over several interest rates.

// The initial investment is $100,000.
let present_value = -100_000;

// The investment will grow for 12 periods.
let periods = 12;

let continuous_compounding = false;

// We'll keep a collection of the calculated future values along with their inputs.
let mut scenarios = vec![];

for i in 2..=15 {
    // The rate is between 2% and 15% per year.
    let rate = f64::from(i) / 100.0;
    // Calculate the future value for this periodic rate and add the details to the collection.
    scenarios.push(future_value_solution(rate, periods, present_value, continuous_compounding));
}
dbg!(&scenarios);
assert_eq!(14, scenarios.len());

// Keep only the scenarios where the future value was between $200,000 and $400,000.
scenarios.retain(|x| x.future_value() >= 200_000.00 && x.future_value() <= 400_000.00);
dbg!(&scenarios);
assert_eq!(7, scenarios.len());

// Check the formulas for the first of the remainingc scenarios.
let formula = scenarios[0].formula();
dbg!(&formula);
assert_eq!("201219.6472 = 100000.0000 * (1.060000 ^ 12)", formula);
let symbolic_formula = scenarios[0].symbolic_formula();
dbg!(&symbolic_formula);
assert_eq!("fv = -pv * (1 + r)^n", symbolic_formula);