Function future_value 

pub fn future_value<T, C>(
    rate: f64,
    periods: u32,
    present_value: T,
    compounding: C,
) -> FinanceResult<f64>
where
    T: Into<f64> + Copy,
    C: Into<Compounding>,

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

See the future_value module page for the formulas.

Related functions:

• To calculate a future value with a fixed rate and return a struct that shows the formula and optionally produces the the period-by-period values use future_value_solution.
• To calculate the future value if the rates vary by period use future_value_schedule or 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.

Errors

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

Examples

Investment that grows quarter by quarter.

use finance_solution::*;

// The investment grows by 3.4% per quarter.
let rate = 0.034;

// The investment will grow for 5 quarters.
let periods = 5;

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

let continuous_compounding = false;

let future_value = future_value(rate, periods, present_value, continuous_compounding).unwrap();
// Confirm that the future value is correct to four decimal places (one
// hundredth of a cent).
assert_rounded_4(295_489.9418, future_value);

Investment that loses money each year.

// The investment loses 5% per year.
let rate = -0.05;

// The investment will shrink for 6 periods.
let periods = 6;

// The initial investment is $10,000.75.
let present_value = -10_000.75;

let continuous_compounding = false;

let future_value = future_value(rate, periods, present_value, continuous_compounding).unwrap();
// Confirm that the future value is correct to the penny.
assert_rounded_2(7351.47, future_value);

Error case: rate less than −100% per period is outside the domain.

let err = future_value(-1.05, 6, 10_000.75, false).unwrap_err();
assert!(matches!(err, FinanceError::InvalidRate { .. }));

Errors

Returns FinanceError::InvalidRate if rate < -1.0, or FinanceError::NonFinite if inputs or the computed result are not finite.

Examples

use finance_solution::{future_value, FinanceError, FinanceResult};

match future_value(0.05, 10, -1_000.0, false) {
    Ok(fv) => assert!(fv > 0.0),
    Err(FinanceError::InvalidRate { rate }) => panic!("unexpected bad rate {rate}"),
    Err(e) => panic!("{e}"),
}

assert!(matches!(
    future_value(-1.5, 10, 1000.0, false),
    Err(FinanceError::InvalidRate { .. })
));

fn project(pv: f64, years: u32) -> FinanceResult<f64> {
    future_value(0.07, years, pv, false)
}
assert!(project(-5_000.0, 5).is_ok());