PV

What it does

PV(rate, nper, pmt, [fv], [type])

PV(rate,nper,pmt,[fv],[type]) solves the present value of fixed payments and a final balance. Rate and period count must use the same interval. Type zero pays at the end of each period; type one at its beginning.

Try it

=PV(0,4,-250) returns 1000. Four negative payments are balanced by a positive present value. =PV(0.25,1,0,1250) is about -1000: a future inflow has a negative present outflow under this sign convention.

Quirks

At least a payment or a future value must be supplied. Inflows and outflows have opposite signs. The current PV helper uses a small-rate band abs(rate)<1e-12 for its linear branch; PMT’s separately measured zero-rate rule is exact equality. Do not transfer one function’s branch boundary to another.

How to implement

For a mathematical route put g=(1+r)^n and a=(1+r*type)*(g-1)/r, then return -(fv+pmt*a)/g. At zero rate the expression has the limit -(fv+pmt*n). The current helper implements that limit over its small-rate band, otherwise uses its power/annuity-term body and explicit nonfinite checks. Near zero, a log1p/expm1 formulation is numerically useful but changes intermediate rounding. Its last-bit behaviour is not solved by copying the PMT discount recipe.

Rust code

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

fn growth_allow_nonpositive_base(periodic_rate: f64, periods: f64) -> Result<f64, FinancialError> {
    validate_finite(&[periodic_rate, periods])?;
    let base = 1.0 + periodic_rate;
    growth_from_base(base, periods)
}

fn annuity_term_allow_nonpositive_base(
    periodic_rate: f64,
    periods: f64,
    timing: PaymentTiming,
) -> Result<f64, FinancialError> {
    if periodic_rate.abs() < EPSILON {
        return Ok(periods);
    }
    let factor = growth_allow_nonpositive_base(periodic_rate, periods)?;
    let term = timing.factor(periodic_rate) * (factor - 1.0) / periodic_rate;
    if term.is_finite() {
        Ok(term)
    } else {
        Err(FinancialError::Num)
    }
}

pub fn pv(
    periodic_rate: f64,
    periods: f64,
    payment_value: f64,
    future_value: f64,
    timing: PaymentTiming,
) -> Result<f64, FinancialError> {
    validate_finite(&[periodic_rate, periods, payment_value, future_value])?;
    if periodic_rate.abs() < EPSILON {
        return Ok(-(future_value + payment_value * periods));
    }
    let factor = growth_allow_nonpositive_base(periodic_rate, periods)?;
    let term = annuity_term_allow_nonpositive_base(periodic_rate, periods, timing)?;
    if factor == 0.0 {
        return Err(FinancialError::Div0);
    }
    let result = -(future_value + payment_value * term) / factor;
    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

NPV accepts varying equally spaced amounts; XNPV uses dates; PMT and FV solve other annuity variables.

Named variants

No named variants are recorded yet.