Crate finance_solution

Expand description

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.

Crate finance_solutionCopy item path