FV

What it does

FV(rate, nper, pmt, [pv], [type])

FV(rate,nper,pmt,[pv],[type]) returns the final balance of a constant-rate investment or loan with equal periodic payments. Present value pv and type default to zero. Type zero pays at period end; type one at the beginning.

Use a rate per payment period and a matching number of periods. Cash paid out is negative and cash received positive. For nonzero rate the mathematical balance equation is pv*(1+r)^n+pmt*(1+r*type)*((1+r)^n-1)/r+fv=0.

Try it

=FV(0.25,2,-100,-1000,0) returns about 1787.5. The starting thousand grows to 1562.5. The first hundred earns one period of interest and the second earns none, adding 225.

=FV(0.25,2,-100,-1000,1) returns about 1843.75: moving both payments one period earlier changes their combined accumulation to 281.25. At zero rate, =FV(0,4,-250) returns 1000.

Quirks

A zero payment and an omitted payment position are useful for lump-sum growth; supply pv in that case. For example, FV(0.25,2,,-1000) describes the starting balance alone.

The current wrapper truncates type, choosing ending timing for zero and beginning timing for other truncated values. Microsoft defines only zero and one. Treat the broader code rule as an implementation fact rather than a documented promise.

The newer cited helper distinguishes exactly zero rate from a tiny nonzero rate. A stored growth factor can round to one and cancel the nonzero-rate annuity numerator. FV therefore does not inherit PMT’s cancellation-corrected discount body. The current POWER route also permits some nonpositive-base cases with integer periods, whereas PMT has a separate domain guard.

The recipe below cites a later source revision than the separately pinned interactive calculator. A preview result can still follow an earlier route at the changed boundaries.

How to implement

Let D mean ordinary nearest/even binary64 storage and R mean a 64-bit-significand operation followed by a binary64 store. The current R31 composition is:

1. Validate finite r, n, payment and pv. Read timing and apply the optional defaults.
2. Form base=R(1+r), then obtain g=POWER(base,n) through the public worksheet POWER kernel. Its integer and fractional paths remain separate; this is not an unconditional EXP/LN replacement.
3. If r is exactly zero, set term=n. Otherwise form difference=D(g-1), store end_term=R(difference/r), then store term=R(end_term*timing_factor). The current timing factor is one for ending payments and D(1+r) for beginning payments. Division comes before timing multiplication.
4. Separately store present=R(pv*g) and payments=R(pmt*term).
5. Store combined=R(present+payments) and negate it. Apply the finite-result and worksheet number-publication rules.

For the ending-payment example, base is 1.25, g is 1.5625, difference 0.5625 and term 2.25. The two stored components are minus 1562.5 and minus 225, giving positive 1787.5 after negation. Beginning timing multiplies term by 1.25 to obtain 2.8125.

A boundary reconstruction is r=2^-53,n=1,pmt=-1,pv=0,type=0: the stored base and growth are one, difference is zero and the reconstructed result is zero. At exactly r=0 the linear term is one instead. The cited test source retains this cancellation control; a stable expm1(n*log1p(r))/r implementation would have a different result. Do not smooth away the measured branch merely because the mathematical one-period value is one.

The source retains separate unit controls for the growth, annuity quotient, timing product, two balance products and final addition. Those constrain stages independently of their producers. Complete POWER behaviour, other input routes and environments, and remaining reported FV mismatches still need their own evidence; the stage recipe is not a whole-function equality claim.

Rust code

2 fv_fn "FV" (3, 5) [V "rate", V "nper", V "pmt", V "pv", V "type"] |s, a, sv| {
    let t = timing(s, a, 4)?;
    tv_out(s, tv::fv(num(s, a, 0)?, num(s, a, 1)?, num(s, a, 2)?, opt(s, a, 3, 0.0)?, t))
}

pub fn fv(
    periodic_rate: f64,
    periods: f64,
    payment_value: f64,
    present_value: f64,
    timing: PaymentTiming,
) -> Result<f64, FinancialError> {
    validate_finite(&[periodic_rate, periods, payment_value, present_value])?;
    // R31 n=1 public growth calls expose the base store. Independent POWER
    // leaves confirm the same input stage at the remaining multi-period cases.
    let factor = growth_from_base(excel_x87_add(1.0, periodic_rate), periods)?;
    // R31 paired end/beginning unit calls identify division before timing,
    // with each operation stored from PC64. Small-rate controls keep only
    // exact zero on the linear route, including measured cancellation at 2^-53.
    // Reuse FV's growth stage; PV retains its own composition above.
    let term = if periodic_rate == 0.0 {
        periods
    } else {
        let end_term = excel_x87_div(factor - 1.0, periodic_rate);
        excel_x87_mul(end_term, timing.factor(periodic_rate))
    };
    // R31 public unit calls isolate both products from their growth and annuity
    // helpers. Separate nonzero pairs and addition ties identify the final store.
    let present_component = excel_x87_mul(present_value, factor);
    let payment_component = excel_x87_mul(payment_value, term);
    let result = -excel_x87_add(present_component, payment_component);
    if result.is_finite() {
        Ok(result)
    } else {
        Err(FinancialError::Num)
    }
}

No implementation has been published with a Handbook test suite for this function.

Version differences

The recorded environments below distinguish a reading from a same-input comparison. Counts describe captured inputs in each environment; overlapping captures and comparisons are not totals of unique worksheet calls.

The record contains no same-input comparison between these environments. Reading different inputs on different builds does not establish either a version change or cross-build agreement.

Recorded environments and comparison details.

Alternatives

PV, PMT, NPER and RATE solve other variables of the annuity equation. FVSCHEDULE applies varying rates to a principal without this payment stream; NPV discounts varying equally spaced payments.

Named variants

No named variants are recorded yet.