Function periods_solution

pub fn periods_solution<P, F>(
    rate: f64,
    present_value: P,
    future_value: F,
    continuous_compounding: bool,
) -> TvmSolution
where
    P: Into<f64> + Copy,
    F: Into<f64> + Copy,

Calculates the number of periods given a periodic rate along with the present and future values using simple compounding; and builds a struct with the input values, an explanation of the formula, and the option to calculate the period-by-period values.

Note that the calculated number of periods from PeriodsSolution::fractional_periods field will be a floating point number. To get the periods as a whole number (rounded up) use PeriodsSolution::periods.

See the periods module page for the formulas.

Related functions:

• To calculate the periods as a single number with simple compounding use periods.
• To calculate the periods using continuous compounding use periods_continuous or periods_continuous_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.
• present_value - The starting value of the investment. May appear as pv in formulas, or P for principal.
• future_value - The final value of the investment.
• continuous_compounding - True for continuous compounding, false for simple compounding.

Panics

The call will fail if the rate, the present value, or the future value is infinite or not a number (NaN).

The call will also fail in any of the follwing cases because there is no number of periods that would make the calculation work:

• The periodic rate is less than -1.0.
• The present value is zero and the future value is nonzero.
• The present value is nonzero and the future value is zero, unless the rate is exactly -1.0%.
• The present value is negative and the future value is positive or vice versa.
• The present value and future value are both negative, the future value is less than the present value, and the periodic rate is zero or negative.
• The present value and future value are both negative, the future value is greater than the present value, and the periodic rate is zero or positive.
• The present value and future value are both positive, the future value is greater than the present value, and the periodic rate is zero or negative.
• The present value and future value are both positive, the future value is less than the present value, and the periodic rate is zero or positive.

Examples

use finance_solution::*;

// The interest rate is 3.5% per quarter.
let rate = 0.035;

// The starting value is $100,000.00.
let present_value = -100_000.00;

// The ending value is $200,000.00.
let future_value = 200_000.00;

// Use simple compounding.
let continuous_compounding = false;

// Calculate the number of quarters required and build a struct with the
// input values, an explanation of the formula, and an option to calculate
// the quarter-by-quarter values.
let solution = periods_solution(rate, present_value, future_value, continuous_compounding);

let fractional_quarters = solution.fractional_periods();
dbg!(&fractional_quarters);
assert_rounded_2(20.15, fractional_quarters);

// Get the whole number of quarters.
let quarters = solution.periods();
dbg!(&quarters);
assert_eq!(21, quarters);

// Examine the formulas.
let formula = solution.formula();
dbg!(&formula);
assert_eq!("20.15 = log(-200000.0000 / -100000.0000, base 1.035000)", formula);
let symbolic_formula = solution.symbolic_formula();
dbg!(&symbolic_formula);
assert_eq!("n = log(-fv / pv, base (1 + r))", symbolic_formula);

let series = solution.series();
dbg!(&series);

let last_entry = series.last().unwrap();
dbg!(&last_entry);
assert_rounded_4(200_000.0, last_entry.value());

// Create a reduced series with the value at the end of each year.
let filtered_series = series
    .iter()
    .filter(|x| x.period() % 4 == 0 && x.period() != 0)
    .collect::<Vec<_>>();
dbg!(&filtered_series);
assert_eq!(5, filtered_series.len());

Negative interest rate.

// The interest rate is -6% per year and the value falls from $15,000.00 to
// $12,000.00.
let solution = periods_solution(-0.06, -15_000.00, 12_000.00, false);
dbg!(&solution);
assert_rounded_2(3.61, solution.fractional_periods());
assert_eq!(4, solution.periods());

// Print the period-by-period values as a formatted table.
solution.print_series_table();