Module future_value_annuity 

Future value annuity calculations. Given a series of constant cashflows, a number of periods such as years, and a fixed interest rate, what is the value of the series at the final payment?

Timing uses crate::PaymentTiming (or Excel-style bool via From):

• PaymentTiming::EndOfPeriod / false — ordinary annuity (Excel type=0)
• PaymentTiming::BeginningOfPeriod / true — annuity due (Excel type=1)

Prefer the enum in new code; bool remains for spreadsheet parity.

For teaching / debugging, use future_value_annuity_solution, which carries formulas and related PV/FV fields.

Examples

Ordinary annuity (end of period) with bool:

use finance_solution::future_value_annuity_solution;
let (rate, periods, annuity, due) = (0.034, 10, 500, false);
let fv_ann = future_value_annuity_solution(rate, periods, annuity, due).unwrap();
assert!(fv_ann.future_value().abs() > 5_000.0);

Same scenario with the enum (preferred):

use finance_solution::{future_value_annuity, PaymentTiming};
let ordinary = future_value_annuity(0.034, 10, 500, PaymentTiming::EndOfPeriod).unwrap();
let due = future_value_annuity(0.034, 10, 500, PaymentTiming::BeginningOfPeriod).unwrap();
// Annuity due compounds one extra period → larger magnitude than ordinary
assert!(due.abs() > ordinary.abs());

Zero-rate special case (both timings reduce to -payment * periods):

use finance_solution::{future_value_annuity, PaymentTiming};
let z = future_value_annuity(0.0, 12, 100, PaymentTiming::EndOfPeriod).unwrap();
assert!((z - (-1_200.0)).abs() < 1e-12);

Functions

future_value_annuity

Returns the future value of annuity (a series of constant cashflows) at a constant rate. Returns f64.

future_value_annuity_solution

Returns the future value of annuity (a series of constant cashflows) at a constant rate. Returns custom solution struct with additional information and functionality.