# `Money.Financial`
[🔗](https://github.com/kipcole9/money/blob/v6.0.0-rc.0/lib/money/financial.ex#L1)

A set of financial functions, primarily related to discounted cash flows.

Some of the algorithms are from [finance formulas](http://www.financeformulas.net)

# `future_value`

```elixir
@spec future_value([{number(), Money.t()}], number()) :: Money.t()
```

Calculates the future value for a list of cash flows and an interest rate.

* `flows` is a list of tuples representing a cash flow.  Each flow is
represented as a tuple of the form `{period, %Money{}}`

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

## Example

    iex> Money.Financial.future_value([{4, Money.new(:USD, 10000)}, {5, Money.new(:USD, 10000)}, {6, Money.new(:USD, 10000)}], 0.13)
    Money.new(:USD, "34068.99999999999999999999999")

    iex> Money.Financial.future_value [{0, Money.new(:USD, 5000)},{1, Money.new(:USD, 2000)}], 0.12
    Money.new(:USD, "7600.000000000000000000000000")

# `future_value`

```elixir
@spec future_value(Money.t(), number(), number()) :: Money.t()
```

Calculates the future value for a present value, an interest rate
and a number of periods.

* `present_value` is a %Money{} representation of the present value

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

* `periods` in an integer number of periods

## Examples

    iex> Money.Financial.future_value Money.new(:USD, 10000), 0.08, 1
    Money.new(:USD, "10800.00")

    iex> Money.Financial.future_value Money.new(:USD, 10000), 0.04, 2
    Money.new(:USD, "10816.0000")

    iex> Money.Financial.future_value Money.new(:USD, 10000), 0.02, 4
    Money.new(:USD, "10824.32160000")

# `interest_rate`

```elixir
@spec interest_rate(Money.t(), Money.t(), number()) :: Decimal.t()
```

Calculates the effective interest rate for a given present value,
a future value and a number of periods.

* `present_value` is a %Money{} representation of the present value

* `future_value` is a %Money{} representation of the future value

* `periods` is an integer number of a period

## Examples

    iex> Money.Financial.interest_rate Money.new(:USD, 10000), Money.new(:USD, 10816), 2
    Decimal.new("0.04")

    iex> Money.Financial.interest_rate Money.new(:USD, 10000), Money.new(:USD, "10824.3216"), 4
    Decimal.new("0.02")

# `internal_rate_of_return`

```elixir
@spec internal_rate_of_return([{integer(), Money.t()}]) :: float()
```

Calculates the interal rate of return for a given list of cash flows.

* `flows` is a list of tuples representing a cash flow.  Each flow is
  represented as a tuple of the form `{period, %Money{}}`

# `net_present_value`

```elixir
@spec net_present_value([{integer(), Money.t()}], number()) :: Money.t()
```

Calculates the net present value of an initial investment, a list of
cash flows and an interest rate.

* `flows` is a list of tuples representing a cash flow.  Each flow is
represented as a tuple of the form `{period, %Money{}}`

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

* `investment` is a %Money{} struct representing the initial investment

## Example

    iex> flows = [{0, Money.new(:USD, 5000)},{1, Money.new(:USD, 2000)},{2, Money.new(:USD, 500)},{3, Money.new(:USD,10_000)}]
    iex> Money.Financial.net_present_value flows, 0.08, Money.new(:USD, 100)
    Money.new(:USD, "15118.84367220444038002337042")
    iex> Money.Financial.net_present_value flows, 0.08
    Money.new(:USD, "15218.84367220444038002337042")

# `net_present_value`

```elixir
@spec net_present_value([{integer(), Money.t()}], number(), Money.t()) :: Money.t()
@spec net_present_value(Money.t(), float(), number()) :: Money.t()
```

Calculates the net present value of an initial investment, a recurring
payment, an interest rate and a number of periods

* `investment` is a %Money{} struct representing the initial investment

* `future_value` is a %Money{} representation of the future value

* `interest_rate` is a float representation of an interest rate.  For
  example, 12% would be represented as `0.12`

* `periods` in an integer number of a period

## Example

    iex> Money.Financial.net_present_value Money.new(:USD, 10000), 0.13, 2
    Money.new(:USD, "7831.466833737959119743127888")

    iex> Money.Financial.net_present_value Money.new(:USD, 10000), 0.13, 2, Money.new(:USD, 100)
    Money.new(:USD, "7731.466833737959119743127888")

# `net_present_value`

```elixir
@spec net_present_value(Money.t(), float(), number(), Money.t()) :: Money.t()
```

# `payment`

```elixir
@spec payment(Money.t(), float(), number()) :: Money.t()
```

Calculates the payment for a given loan or annuity given a
present value, an interest rate and a number of periods.

* `present_value` is a %Money{} representation of the present value

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

* `periods` is an integer number of periods

## Example

    iex> Money.Financial.payment Money.new(:USD, 100), 0.12, 20
    Money.new(:USD, "13.38787800396606622792492299")

# `periods`

```elixir
@spec periods(Money.t(), Money.t(), float()) :: Decimal.t()
```

Calculates the number of periods between a present value and
a future value with a given interest rate.

* `present_value` is a %Money{} representation of the present value

* `future_value` is a %Money{} representation of the future value

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

## Example

    iex> Money.Financial.periods Money.new(:USD, 1500), Money.new(:USD, 2000), 0.005
    Decimal.new("57.68013595323872502502238648")

# `present_value`

```elixir
@spec present_value([{integer(), Money.t()}], number()) :: Money.t()
```

Calculates the present value for a list of cash flows and an interest rate.

* `flows` is a list of tuples representing a cash flow.  Each flow is
represented as a tuple of the form `{period, %Money{}}`

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

## Example

    iex> Money.Financial.present_value([{4, Money.new(:USD, 10000)}, {5, Money.new(:USD, 10000)}, {6, Money.new(:USD, 10000)}], 0.13)
    Money.new(:USD, "16363.97191111964880256655144")

    iex> Money.Financial.present_value [{0, Money.new(:USD, -1000)},{1, Money.new(:USD, -4000)}], 0.1
    Money.new(:USD, "-4636.363636363636363636363636")

# `present_value`

```elixir
@spec present_value(Money.t(), number(), number()) :: Money.t()
```

Calculates the present value for future value, an interest rate
and a number of periods

* `future_value` is a %Money{} representation of the future value

* `interest_rate` is a float representation of an interest rate.  For
example, 12% would be represented as `0.12`

* `periods` in an integer number of periods

## Examples

    iex> Money.Financial.present_value Money.new(:USD, 100), 0.08, 2
    Money.new(:USD, "85.73388203017832647462277092")

    iex> Money.Financial.present_value Money.new(:USD, 1000), 0.10, 20
    Money.new(:USD, "148.6436280241436864020760472")

---

*Consult [api-reference.md](api-reference.md) for complete listing*