rust_finprim/rate/
cagr.rs

1use crate::ONE;
2use rust_decimal::prelude::*;
3
4/// CAGR - Compound Annual Growth Rate
5///
6/// The compound annual growth rate (CAGR) is the rate of return that would be required for an investment
7/// to grow from its beginning balance to its ending balance, assuming the profits were reinvested at the
8/// end of each period of the investment’s life span.
9///
10/// # Arguments
11/// * `beginning_balance` - The initial investment or balance
12/// * `ending_balance` - The final investment or balance
13/// * `n` - The number of years
14///
15/// # Returns
16/// * The compound annual growth rate (CAGR)
17///
18/// # Example
19/// * Beginning balance of $1000, ending balance of $2000 after 5 years
20/// ```
21/// use rust_finprim::rate::cagr;
22/// use rust_decimal_macros::*;
23///
24/// let beginning_balance = dec!(1000);
25/// let ending_balance = dec!(2000);
26/// let n = dec!(5);
27///
28/// cagr(beginning_balance, ending_balance, n);
29/// ```
30pub fn cagr(beginning_balance: Decimal, ending_balance: Decimal, n: Decimal) -> Decimal {
31    (ending_balance / beginning_balance).powd(ONE / n) - ONE
32}
33
34#[cfg(test)]
35mod tests {
36    #[cfg(not(feature = "std"))]
37    extern crate std;
38    use super::*;
39    use rust_decimal_macros::dec;
40    #[cfg(not(feature = "std"))]
41    use std::assert;
42    #[cfg(not(feature = "std"))]
43    use std::prelude::v1::*;
44
45    #[test]
46    fn test_cagr() {
47        let beginning_balance = dec!(1000);
48        let ending_balance = dec!(500);
49        let n = dec!(5);
50        let result = cagr(beginning_balance, ending_balance, n);
51        let expected = dec!(-0.12945);
52        assert!(
53            (result - expected).abs() < dec!(1e-5),
54            "Failed on case: {}. Expected: {}, Result: {}",
55            "Beginning balance of $1000, ending balance of $500 after 5 years",
56            expected,
57            result
58        );
59    }
60}
rust_finprim/rate/cagr.rs

rust_finprim/rate/
cagr.rs
