# [−][src]Crate finance_solution

`finance_solution` is a collection of financial functions related to time-value-of-money. In addition to being rigourously tested with symmetry tests as well as excel-matching tests, the library provides `solution` structs to give the user more detailed information about each transaction, which has record-keeping benefits for financial software and learning benefits for students of finance.

## Example

```use finance_solution::*;
let (rate, periods, present_value, is_continuous) = (0.034,10,1000, false);
let fv = future_value_solution(rate, periods, present_value, is_continuous);
dbg!(fv);```

which prints to the terminal:

``````fv = TvmSolution {
calculated_field: FutureValue,
continuous_compounding: false,
rate: 0.034,
periods: 10,
fractional_periods: 10.0,
present_value: 1000.0,
future_value: -1397.0288910795477,
formula: "-1397.0289 = -1000.0000 * (1.034000 ^ 10)",
symbolic_formula: "fv = -pv * (1 + r)^n",
}
``````

and if you run this line:

`fv.series().print_table();`

a pretty-printed table will be displayed in the terminal:

``````period      rate        value
------  --------  -----------
0  0.000000  -1_000.0000
1  0.034000  -1_034.0000
2  0.034000  -1_069.1560
3  0.034000  -1_105.5073
4  0.034000  -1_143.0946
5  0.034000  -1_181.9598
6  0.034000  -1_222.1464
7  0.034000  -1_263.6994
8  0.034000  -1_306.6652
9  0.034000  -1_351.0918
10  0.034000  -1_397.0289
``````

This can be very useful for functions in the `cashflow` family, such as a payment.

```let (rate, periods, present_value, future_value, due) = (0.034, 10, 1000, 0, false);
let pmt = payment_solution(rate, periods, present_value, future_value, due);
pmt.print_table();```

Which prints to the terminal:

```// period  payments_to_date  payments_remaining  principal  principal_to_date  principal_remaining  interest  interest_to_date  interest_remaining
// ------  ----------------  ------------------  ---------  -----------------  -------------------  --------  ----------------  ------------------
//      1         -119.6361         -1_076.7248   -85.6361           -85.6361            -914.3639  -34.0000          -34.0000           -162.3609
//      2         -239.2722           -957.0887   -88.5477          -174.1838            -825.8162  -31.0884          -65.0884           -131.2725
//      3         -358.9083           -837.4526   -91.5583          -265.7421            -734.2579  -28.0778          -93.1661           -103.1947
//      4         -478.5443           -717.8165   -94.6713          -360.4134            -639.5866  -24.9648         -118.1309            -78.2300
//      5         -598.1804           -598.1804   -97.8901          -458.3036            -541.6964  -21.7459         -139.8768            -56.4840
//      6         -717.8165           -478.5443  -101.2184          -559.5220            -440.4780  -18.4177         -158.2945            -38.0663
//      7         -837.4526           -358.9083  -104.6598          -664.1818            -335.8182  -14.9763         -173.2708            -23.0901
//      8         -957.0887           -239.2722  -108.2183          -772.4001            -227.5999  -11.4178         -184.6886            -11.6723
//      9       -1_076.7248           -119.6361  -111.8977          -884.2978            -115.7022   -7.7384         -192.4270             -3.9339
//     10       -1_196.3609             -0.0000  -115.7022          -999.0000              -0.0000   -3.9339         -196.3609              0.0000```

## Re-exports

 `pub extern crate num_format;`

## Modules

 cashflow The internal module which supports the solution struct for the Cashflow family of functions (e.g., `payment`). convert_rate Rate conversions. Given a rate and number of compound periods per year, what is this rate when converted to APR, Effective annual, and Periodic rates? Also consider the `apr` `ear` and `epr` helper functions. future_value Future value calculations. Given an initial investment amount, a number of periods such as periods, and fixed or varying interest rates, what is the value of the investment at the end? future_value_annuity Future value annuity calculations. Given a series of cashflows, a number of periods such as years, and a fixed interest rate, what is the value of the series of cashflows (annuity) at the final payment? net_present_value Net Present Value calculations. Given a series of cashflows, an initial investment (the cashflow at time0), a number of periods such as years, and fixed or varying interest rates, what is the net value of the series of cashflows right now? nper Number of periods calculations for scenarios with payments. Returns the number of periods required for a Present Value to achieve a Future Value with a given set of annuities (payments) at a specified periodic rate. The only module still in beta. payment Payment calculations. What is the periodic payment needed for an amortized loan and how much of that is interest or principal? periods Number of periods calculations. Given a periodic rate, present value, and future value, find the number of periods needed to satisfy the equation. present_value Present value calculations. Given a final amount, a number of periods such as years, and fixed or varying interest rates, what is the current value? present_value_annuity Present value annuity calculations. Given a series of cashflows, a number of periods such as years, and fixed or varying interest rates, what is the current value of the series of cashflows (annuity) right now? rate Periodic rate calculations. Given an initial investment amount, a final amount, and a number of periods what does the rate per period need to be? round Utilities for rounding money amounts to the nearest hundredth or ten-thousandth part. tvm The internal module which supports the solution struct for the family of Time-value-of-money equations which do not involve payments. For example, future value, present value, rate, and periods. tvm_convert_rate The internal module which supports the solution struct for Rate Conversion (see `convert_rate`).

## Macros

 assert_approx_equal assert_approx_equal_symmetry_test assert_rounded_2 assert_rounded_4 assert_rounded_6 assert_rounded_8 assert_same_sign_or_zero is_approx_equal is_approx_equal_symmetry_test repeating_vec

## Structs

 CashflowPeriod CashflowSeries CashflowSolution A record of a cash flow calculation such as payment, net present value, or the present value or future value of an annuity. ConvertRateSolution NperSolution NpvPeriod NpvSeries NpvSolution The custom solution information of a NPV scenario. The struct values are immutable by the user of the library. PaymentSeries PaymentSolution ScenarioEntry ScenarioList TvmPeriod The value of an investment at the end of a given period, part of a Time Value of Money calculation. TvmScheduleSolution A record of a Time Value of Money calculation where the rate may vary by period. TvmSeries TvmSolution

## Enums

 CashflowVariable ConvertRateVariable The possible types of rates to convert. Schedule TvmVariable Enumeration used for the `calculated_field` field in `TvmSolution` and [`TvmSchedule`] to keep track of what was calculated, either the periodic rate, the number of periods, the present value, or the future value. ValueType

## Functions

 apr Helper function to convert an quoted annual rate (apr) into all possible conversions (ear, epr). Returns a solution struct. apr_continuous Helper function to convert an APR into an EAR using continuous compounding. Returns solution struct. assert_rounded_2 assert_rounded_4 assert_rounded_6 assert_rounded_8 convert_apr_to_ear Convert a nominal interest rate (Annual rate, APR) to EAR (effective annual rate). Returns f64. convert_apr_to_ear_solution Convert an APR to EAR (effective annual rate). Returns a custom type with additional functionality and extra information available in the dbg!(). convert_apr_to_epr Convert APR (annual rate) to periodic rate. Returns f64. convert_apr_to_epr_solution Convert APR (annual rate) to periodic rate. Returns a custom solution type. convert_ear_to_apr Convert an EAR to APR. Returns f64. convert_ear_to_apr_solution Convert an EAR to APR. Returns solution struct with additional information and functionality. convert_ear_to_epr Convert an EAR (Effective Annual Rate) to periodic rate (aka EPR, effective periodic rate). Returns f64. convert_ear_to_epr_solution Convert an EAR (Effective Annual Rate) to periodic rate (also known as EPR). Returns a solution struct with additional information and functionality. /// Related Functions: convert_epr_to_apr Convert periodic rate to APR (aka Annual rate, nominal interest rate, Annual Percentage Rate). Returns f64. convert_epr_to_apr_solution Convert periodic rate to APR (aka Annual rate, nominal interest rate, Annual Percentage Rate). Returns a custom solution type. convert_epr_to_ear Convert a periodic rate (aka EPR, effective periodic rate) to EAR (effective annual rate). Return a single f64 value. convert_epr_to_ear_solution Convert a periodic rate (EPR) to effective annual rate (EAR), returning a solution struct with additionality information and features. ear Helper function to convert an effective annual rate (ear) into all possible conversions (apr, epr). Returns a solution struct. ear_continuous Helper function to convert an EAR into an APR using continuous compounding. Returns solution struct. epr Helper function to convert a periodic interest rate (EPR) to all rate conversions. Returns solution struct. future_value Returns the value of an investment after it has grown or shrunk over time, using a fixed rate. 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. future_value_schedule Calculates a future value based on rates that change for each period. future_value_schedule_solution Calculates a future value based on rates that change for each period, returning a struct with all of the inputs and results. future_value_solution Calculates the value of an investment after it has grown or shrunk over time and returns a struct with the inputs and the calculated value. This is used for keeping track of a collection of financial scenarios so that they can be examined later. net_present_value Returns the net present value of a future series of constant cashflows and constant rate, subtracting the initial investment cost. Returns f64. net_present_value_schedule Returns the net present value of a schedule of rates and cashflows (can be varying), subtracting the initial investment cost. Returns f64. net_present_value_schedule_solution Returns the net present value of a schedule of rates and cashflows (can be varying), subtracting the initial investment cost. Returns a custom solution struct with detailed information and additional functionality. net_present_value_solution Returns the net present value of a future series of constant cashflows and constant rate, subtracting the initial investment cost. Returns a solution struct with additional features.. nper Returns the number of periods required for an annuity (payments) to reach a future value, at a specified periodic rate. Still in beta. nper_solution Returns f64 for Number of Periods (NPER). Receive the number of periods required for a present value to equal a future value based on a set of payments (annuity) at an interest rate. If there is no initial present value, use 0. This is equivalent to the NPER function in Excel / Google Sheets. payment Returns the payment needed at the end of every period for an amortized loan. payment_solution Calculates the payment needed for each period for an amortized loan and creates a struct showing the interest, the formula, and optionally the period-by-period values. periods Returns the number of periods given a periodic rate along with the present and future values, using simple compounding. periods_solution 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. present_value Returns the current value of a future amount using a fixed rate. present_value_annuity Returns the present value of an annuity (series of constant cashflows) at a constant rate. Returns f64. present_value_annuity_accumulator present_value_annuity_solution Returns the present value of a future series of constant cashflows and constant rate. Returns custom solution type with additional information and functionality. present_value_schedule Calculates a present value based on rates that change for each period. present_value_schedule_solution Calculates a present value based on rates that change for each period and returns a struct with the inputs and the calculated value. present_value_solution Calculates the current value of a future amount using a fixed rate and returns a struct with the inputs and the calculated value. This is used for keeping track of a collection of financial scenarios so that they can be examined later. rate Returns the periodic rate of an investment given the number of periods along with the present and future values. rate_solution Returns the periodic rate of an investment given the number of periods along with the present and future values. round_2 Round to two decimal places. This function uses f64::round() which rounds halfway cases away from 0.0. round_4 Round to four decimal places. This function uses f64::round() which rounds halfway cases away from 0.0. round_6 Round to six decimal places. This function uses f64::round() which rounds halfway cases away from 0.0. round_8 Round to eight decimal places. This function uses f64::round() which rounds halfway cases away from 0.0.