{
  "category": "Financial functions",
  "display_name": "FV",
  "entry_kind": "built_in_function",
  "eval_api": {
    "method": "POST",
    "url": "https://handbook.dnacalc.com/api/eval"
  },
  "function_id": "FUNC.FV",
  "implementation_state": {
    "answer_bank": {
      "excel_builds": [
        "20131",
        "20228",
        "20430",
        "20527",
        "?"
      ],
      "larger_numeric": 1,
      "last_bit": 1,
      "matched": 2559,
      "other_mismatch": 0,
      "refused": 0,
      "rows": 2561,
      "unread": 0,
      "worst_ulp": 100663296
    },
    "detail": "Of 2,567 recorded answers (2,561 in the answer bank and 6 workbook cells), 2 do not match: 1 differ by more than 16 ULP, 1 differ by at most 16 ULP.",
    "dnacalc_commit": "9e1884369a678158dd82d3d74188daf986995e87",
    "in_catalogue": true,
    "state": "differs",
    "state_label": "Known larger differences",
    "summary": "Known larger differences on 2 of 2,567 recorded answers",
    "workbook_corpus": {
      "cells": 6,
      "matched": 6
    }
  },
  "implementations": [
    {
      "commit": "9e1884369a678158dd82d3d74188daf986995e87",
      "flavour": "excel-compatibility-candidate",
      "language": "Rust",
      "name": "CalcFunc",
      "own_code": [
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/financial.rs#L168-L171",
        "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/ported/financial_time_value_family.rs#L193-L224"
      ],
      "repository": "https://github.com/DnaCalc/DnaCalc",
      "shared_code": [
        "catalogue/financial::tv_out",
        "catalogue/financial::timing",
        "ported/excel_numeric::backend::sqrt",
        "ported/excel_numeric::binary_with",
        "ported/excel_numeric::excel_pow_positive",
        "ported/excel_numeric::excel_pow_chain",
        "ported/excel_numeric::excel_x87_add",
        "ported/excel_numeric::excel_x87_mul",
        "ported/excel_numeric::excel_x87_div",
        "ported/excel_numeric::excel_x87_recip",
        "ported/excel_numeric/x87::mul",
        "ported/excel_numeric/x87::add",
        "ported/excel_numeric/x87::div",
        "ported/excel_numeric/x87::recip",
        "ported/excel_numeric/x87_chains::pow2_positive",
        "ported/excel_numeric/x87_chains::pow2",
        "ported/excel_numeric/x87_chains::exp_ext",
        "ported/excel_numeric/x87_chains::exp_with",
        "ported/excel_numeric/x87_chains::excel_exp",
        "ported/excel_numeric/x87_chains::log_with",
        "ported/excel_numeric/x87_chains::excel_log",
        "ported/financial_time_value_family::PaymentTiming::factor",
        "ported/financial_time_value_family::validate_finite",
        "ported/financial_time_value_family::growth",
        "ported/financial_time_value_family::annuity_term",
        "ported/financial_time_value_family::growth_from_base",
        "ported/financial_time_value_family::balance_equation",
        "ported/financial_time_value_family::values_bracket_root",
        "ported/financial_time_value_family::bisect_rate_bracket",
        "ported/financial_time_value_family::search_rate_bracket_from_zero",
        "ported/financial_time_value_family::rate",
        "ported/financial_time_value_family::polish_root",
        "ported/financial_time_value_family::rate_root",
        "ported/power_fn::exact_integer_magnitude",
        "ported/power_fn::accept_negative_base_odd_root",
        "ported/power_fn::binexp_positive",
        "ported/power_fn::power_kernel"
      ],
      "source": "https://github.com/DnaCalc/DnaCalc/blob/9e1884369a678158dd82d3d74188daf986995e87/crates/calc-func/src/catalogue/financial.rs#L168-L171",
      "state": "differs",
      "suite": null,
      "summary": "Known larger differences on 2 of 2,567 recorded answers"
    }
  ],
  "json_url": "https://handbook.dnacalc.com/api/functions/FUNC.FV.json",
  "name": "FV",
  "notes": [],
  "schema": "efh.function-reference/v1",
  "section_order": [
    "what-it-does",
    "try-it",
    "quirks",
    "how-to-implement",
    "version-differences",
    "alternatives"
  ],
  "sections": {
    "alternatives": "\n[PV](FUNC.PV.md), [PMT](FUNC.PMT.md), [NPER](FUNC.NPER.md) and [RATE](FUNC.RATE.md) solve other variables of the annuity equation. [FVSCHEDULE](FUNC.FVSCHEDULE.md) applies varying rates to a principal without this payment stream; [NPV](FUNC.NPV.md) discounts varying equally spaced payments.\n\n\n",
    "how-to-implement": "\nLet `D` mean ordinary nearest/even binary64 storage and [R](../model/09-staged-arithmetic.md) mean a 64-bit-significand operation followed by a binary64 store. The current R31 composition is:\n\n1. Validate finite r, n, payment and pv. Read timing and apply the optional defaults.\n2. 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.\n3. 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.\n4. Separately store `present=R(pv*g)` and `payments=R(pmt*term)`.\n5. Store `combined=R(present+payments)` and negate it. Apply the finite-result and worksheet number-publication rules.\n\nFor 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.\n\nA 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.\n\nThe 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.\n\n\n",
    "quirks": "\nA 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.\n\nThe 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.\n\nThe 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.\n\nThe 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.\n\n\n",
    "sources": "\n- [Microsoft: FV function](https://support.microsoft.com/en-us/excel/functions/fv-function), opened 6 November 2026; syntax, documented argument rules and errors.\n- [R31 financial composition](https://github.com/DnaCalc/DnaCalc/blob/481f4ab85d3bf5a95b6daf959bb75ccb2f8b40f8/crates/calc-func/src/ported/financial_time_value_family.rs); `fv`, stored growth base, quotient, timing and balance operations.\n- [Retained public stage controls](https://github.com/DnaCalc/DnaCalc/blob/481f4ab85d3bf5a95b6daf959bb75ccb2f8b40f8/crates/calc-func/tests/f3_financial.rs); FV unit controls, exact-zero distinction and base-store ties. These are retained source controls, not fresh Handbook Excel runs.\n- [Current wrapper timing and defaults](https://github.com/DnaCalc/DnaCalc/blob/481f4ab85d3bf5a95b6daf959bb75ccb2f8b40f8/crates/calc-func/src/catalogue/financial.rs).\n- [Remaining numerical failures](https://github.com/DnaCalc/DnaCalc/blob/481f4ab85d3bf5a95b6daf959bb75ccb2f8b40f8/docs/generated/problem-functions.md); counts retain their source scopes and do not certify this guide.\n\n",
    "try-it": "\n`=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.\n\n`=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`.\n\n\n",
    "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.\n\n| Excel 16.0 build | Platform and CPU | Captured inputs |\n|---|---|---:|\n| 20131 | Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics | 789 |\n| 20228 | Windows, 64-bit, CPU not recorded | 512 |\n| 20430 | Windows, 64-bit, CPU not recorded | 1,230 |\n\nThe 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.\n\n[Recorded environments and comparison details](https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.FV.json).",
    "what-it-does": "\n`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.\n\nUse 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`.\n\n\n"
  },
  "signature": {
    "display": "FV(rate, nper, pmt, [pv], [type])",
    "parameters": [
      {
        "description": null,
        "name": "rate",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "nper",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "pmt",
        "optional": false,
        "repeats": false
      },
      {
        "description": null,
        "name": "pv",
        "optional": true,
        "repeats": false
      },
      {
        "description": null,
        "name": "type",
        "optional": true,
        "repeats": false
      }
    ],
    "trailing_repeats": false
  },
  "sources": {
    "metadata": {
      "admission": {
        "label": "implemented",
        "reason": null
      },
      "arity": {
        "max": 5,
        "min": 3
      },
      "category": "Financial functions",
      "classification": {
        "arg_preparation_profile": "RefsVisibleInAdapter",
        "coercion_lift_profile": "Custom",
        "determinism_class": "Deterministic",
        "error_collapse_profile": "None",
        "fec_dependency_profile": "None",
        "host_interaction_class": "None",
        "kernel_signature_class": "Custom",
        "rich_value_usage": "RichBlind",
        "surface_fec_dependency_profile": "RefOnly",
        "thread_safety_class": "SafePure",
        "volatility_class": "NonVolatile"
      },
      "descriptions": {
        "long": null,
        "short": "Future value of an investment with fixed periodic payments and a fixed rate",
        "short_source": "dna-calc-own"
      },
      "docs": {
        "english_description": "Returns the future value of an investment",
        "microsoft_url": "https://support.microsoft.com/en-us/office/fv-function-2eef9f44-a084-4c61-bdd8-4fe4bb1b71b3"
      },
      "entry_kind": "built_in_function",
      "localized_family_names": null,
      "localized_names": [
        {
          "locale": "ar-SA",
          "name": "FV"
        },
        {
          "locale": "bg-BG",
          "name": "FV"
        },
        {
          "locale": "cs-CZ",
          "name": "BUDHODNOTA"
        },
        {
          "locale": "da-DK",
          "name": "FV"
        },
        {
          "locale": "de-DE",
          "name": "ZW"
        },
        {
          "locale": "el-GR",
          "name": "FV"
        },
        {
          "locale": "en-AU",
          "name": "FV"
        },
        {
          "locale": "en-GB",
          "name": "FV"
        },
        {
          "locale": "en-US",
          "name": "FV"
        },
        {
          "locale": "es-ES",
          "name": "VF"
        },
        {
          "locale": "et-EE",
          "name": "FV"
        },
        {
          "locale": "fi-FI",
          "name": "Tuleva_arvo"
        },
        {
          "locale": "fr-FR",
          "name": "FV"
        },
        {
          "locale": "he-IL",
          "name": "FV"
        },
        {
          "locale": "hr-HR",
          "name": "FV"
        },
        {
          "locale": "hu-HU",
          "name": "JBÉ"
        },
        {
          "locale": "id-ID",
          "name": "FV"
        },
        {
          "locale": "it-IT",
          "name": "VAL.FUT"
        },
        {
          "locale": "ja-JP",
          "name": "FV"
        },
        {
          "locale": "ko-KR",
          "name": "FV"
        },
        {
          "locale": "lt-LT",
          "name": "FV"
        },
        {
          "locale": "lv-LV",
          "name": "FV"
        },
        {
          "locale": "nb-NO",
          "name": "SLUTTVERDI"
        },
        {
          "locale": "nl-NL",
          "name": "TW"
        },
        {
          "locale": "pl-PL",
          "name": "FV"
        },
        {
          "locale": "pt-BR",
          "name": "VF"
        },
        {
          "locale": "pt-PT",
          "name": "VF"
        },
        {
          "locale": "ro-RO",
          "name": "FV"
        },
        {
          "locale": "ru-RU",
          "name": "БС"
        },
        {
          "locale": "sk-SK",
          "name": "FV"
        },
        {
          "locale": "sl-SI",
          "name": "FV"
        },
        {
          "locale": "sr-Latn-RS",
          "name": "FV"
        },
        {
          "locale": "sv-SE",
          "name": "SLUTVÄRDE"
        },
        {
          "locale": "th-TH",
          "name": "FV"
        },
        {
          "locale": "tr-TR",
          "name": "GD"
        },
        {
          "locale": "uk-UA",
          "name": "Мв"
        },
        {
          "locale": "vi-VN",
          "name": "FV"
        },
        {
          "locale": "zh-CN",
          "name": "FV"
        },
        {
          "locale": "zh-HK",
          "name": "FV"
        },
        {
          "locale": "zh-TW",
          "name": "FV"
        }
      ],
      "signature": {
        "display": "FV(rate, nper, pmt, [pv], [type])",
        "parameters": [
          {
            "description": null,
            "name": "rate",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "nper",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "pmt",
            "optional": false,
            "repeats": false
          },
          {
            "description": null,
            "name": "pv",
            "optional": true,
            "repeats": false
          },
          {
            "description": null,
            "name": "type",
            "optional": true,
            "repeats": false
          }
        ],
        "trailing_repeats": false
      },
      "surface_name": "FV",
      "version_marker": null,
      "xlcall": {
        "code": "57",
        "symbol": "xlfFv"
      }
    },
    "microsoft": "https://support.microsoft.com/en-us/office/fv-function-2eef9f44-a084-4c61-bdd8-4fe4bb1b71b3"
  },
  "try_it": {
    "formula": "=FV(0.25,2,-100,-1000,0)"
  },
  "url": "https://handbook.dnacalc.com/functions/FV.html",
  "variants": [],
  "versions": [
    {
      "behaviour": "789 captured inputs are indexed for this environment. Capture dates: 2026-07-11 to 2026-07-23. This is a reading count, not a comparison with another build.",
      "excel_build": "16.0 build 20131",
      "platform": "Windows, bitness not recorded, AMD Ryzen 7 4800H with Radeon Graphics",
      "sources": [
        "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.FV.json"
      ]
    },
    {
      "behaviour": "512 captured inputs are indexed for this environment. Capture dates: 2026-08-09 to 2026-08-09. This is a reading count, not a comparison with another build.",
      "excel_build": "16.0 build 20228",
      "platform": "Windows, 64-bit, CPU not recorded",
      "sources": [
        "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.FV.json"
      ]
    },
    {
      "behaviour": "1,230 captured inputs are indexed for this environment. Capture dates: 2026-09-29 to 2026-09-29. This is a reading count, not a comparison with another build.",
      "excel_build": "16.0 build 20430",
      "platform": "Windows, 64-bit, CPU not recorded",
      "sources": [
        "https://github.com/DnaCalc/ExcelFunctionsHandbook/blob/5dc75391aa5125ccc5abdb095da85950980d6fd8/content/evidence/environments/FUNC.FV.json"
      ]
    }
  ]
}