Module finance_solution::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.

APR: Annual Percentage Rate, also written as Nominal Rate, or annual discount rate. An annualized represenation of the interest rate.

For general use, try the apr function by providing rate and compounding periods per year, for example apr(0.034, 12).

To calculate the Annual Percentage Rate (APR) of a given rate, use the convert_ear_to_apr or convert_epr_to_apr functions.

To convert an Annual Percentage Rate (APR) into a different rate, use the convert_apr_to_ear or convert_apr_to_epr functions.

EPR: Effective Periodic Rate, also written as Periodic Rate. The rate of the compounding period.

For general use, try the epr function by providing rate and compounds_per_year, for example epr(0.034, 12).

To calculate the Effective Periodic Rate (EPR) of a given rate use the convert_apr_to_epr or convert_ear_to_epr functions.

To convert an Effective Period Rate (EPR) into a different rate, use the convert_epr_to_ear or convert_epr_to_apr functions.

EAR: Effective Annual Rate. The effective rate of a year which (typically) has multiple compounding periods within the year.

For general use, try the ear function by providing rate and compounding periods per year, for example ear(0.034, 12).

To calculate the Effective Annual Rate (EAR) of a given rate use the convert_apr_to_ear or convert_epr_to_ear functions.

To convert an Effective Annual Rate (EAR) into a different rate, use the convert_ear_to_apr or convert_ear_to_epr functions.

Examples

All functions in this module can be written with the suffix _solution, except for the apr, ear, epr helper functions which already provide a solution struct. The solution functions provide helpful information in the dbg!() output, for example:

use finance_solution::*;
// Example 1: Give the apr function an apr and compounding-periods-per-year. 
let rate = apr(0.034, 12);
dbg!(rate);

prints to terminal:

{
input_name: Apr
input_rate: 0.034
compounds_per_year: 12
apr_in_percent: 3.4000%
epr_in_percent: 0.2833%
ear_in_percent: 3.4535%
apr: 0.034
epr: 0.0028333333333333335
ear: 0.03453486936028982
apr_formula:
epr_formula: 0.034 / 12
ear_formula: (1 + (0.034/12))^12 - 1
}

Example 2: explicit call to f64 function

let apr = convert_apr_to_ear(0.034, 12);
dbg!(apr);

prints to terminal:

0.03453486936028982

Example 3: explicit call to a _solution function

let apr = convert_rate::convert_apr_to_ear_solution(0.034, 12);  // provides same output as apr! macro                                                       
dbg!(apr.ear());

prints to terminal:

{
input_name: Apr
input_rate: 0.034
compounds_per_year: 12
apr_in_percent: 3.4000%
epr_in_percent: 0.2833%
ear_in_percent: 3.4535%
apr: 0.034
epr: 0.0028333333333333335
ear: 0.03453486936028982
apr_formula:
epr_formula: 0.034 / 12
ear_formula: (1 + (0.034/12))^12 - 1
}

Here are a few variations of how someone can use the convert_rate module functions:

// What is the future value of $500 in 1 year 
// if the APR is 3.4% and it's compounded monthly?
// Solve twice, first using EPR and then using EAR.
 
// to solve, first convert the annual rate into a periodic rate (monthly):
let epr = convert_rate::convert_apr_to_epr(0.034, 12);
assert_approx_equal!(epr, 0.002833333333333333);

// then solve for future value:
let fv = future_value::future_value_solution;
let answer_1 = fv(epr, 12, 500, false);
dbg!(&answer_1);

prints to terminal:

{
    calculated_field: FutureValue
    rate: 0.0028333333333333335
    periods: 12
    present_value: 500.0
    future_value: 517.2674346801452
    formula: "500.0000 * (1.002833 ^ 12)"
}

Now let's doublecheck the previous answer.

// Double-check the previous answer_1 by solving the future_value
// using 1 year as the period and the effective annual rate, 
// instead of using 12 monthly periods of the periodic rate.
let rate = apr(0.034, 12);
let answer_2 = future_value::future_value_solution(rate.ear(), 1, 500, false);
dbg!(&answer_2.future_value()); // outputs: 517.2674346801449
// assert_approx_equal!(answer_1.future_value, answer_2.future_value); // true

Note: you might notice the last two decimal places are different:

&answer1.future_value() = 517.2674346801452
&answer2.future_value() = 517.2674346801449

This is not a mistake, this is a natural phenomenon of computer calculations to have slight inaccuracies in floating point number calculations. Both answers are technically correct. Users of the crate can use our round module, or assert_approx_equal! macro for working with floating point representations. Notice how we used assert_approx_equal! in the example above to assert two slightly different numbers as being equal.

Now you've learned Time-Value-of-Money problems can be solved using different rates and periods, while providing the same correct answer. And you've learned how to use this crate for rate conversions! 😊

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.
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.