# `Logistiki.Accounting.Money`
[🔗](https://github.com/thanos/logistiki/blob/v0.1.0/lib/logistiki/accounting/money.ex#L1)

A small money helper around `Decimal` amounts and a currency string.

Money is represented throughout Logistiki as a `%Decimal{}` amount paired
with a currency string. This module provides convenience constructors and
guards. Amounts are always positive in postings; the debit/credit direction
encodes sign.

## Fields

  * `amount` — `Decimal.t()` — the monetary amount
  * `currency` — `String.t()` — the currency code (e.g. `"USD"`)

## Example

    iex> m = Logistiki.Accounting.Money.new("1000.00", "USD")
    %Logistiki.Accounting.Money{amount: Decimal.new("1000.00"), currency: "USD"}

# `t`

```elixir
@type t() :: %Logistiki.Accounting.Money{amount: Decimal.t(), currency: String.t()}
```

The struct type. See the module documentation for field details and examples.

# `add`
*since 0.1.0* 

```elixir
@spec add(t(), t()) :: t()
```

Adds two money values of the same currency.

## Arguments

  * `a` — `%__MODULE__{}`.
  * `b` — `%__MODULE__{}` — must have the same `currency` as `a`.

## Returns

  * `%__MODULE__{}` — `a.amount + b.amount` in the shared currency.

## Examples

    iex> a = Logistiki.Accounting.Money.new("100", "USD")
    iex> b = Logistiki.Accounting.Money.new("50", "USD")
    iex> Logistiki.Accounting.Money.add(a, b)
    %Logistiki.Accounting.Money{amount: Decimal.new("150"), currency: "USD"}

# `negate`
*since 0.1.0* 

```elixir
@spec negate(t()) :: t()
```

Negates the amount.

## Arguments

  * `m` — `%__MODULE__{}`.

## Returns

  * `%__MODULE__{}` — with `amount` negated.

## Examples

    iex> m = Logistiki.Accounting.Money.new("100", "USD")
    iex> Logistiki.Accounting.Money.negate(m)
    %Logistiki.Accounting.Money{amount: Decimal.new("-100"), currency: "USD"}

# `new`
*since 0.1.0* 

```elixir
@spec new(Decimal.t() | integer() | String.t(), String.t() | atom()) :: t()
```

Builds a money value, coercing numeric inputs to `Decimal`.

## Arguments

  * `amount` — `Decimal.t() | integer() | String.t` — the amount (e.g.
    `Decimal.new("1000.00")`, `1000`, or `"1000.00"`).
  * `currency` — `String.t()` or `atom()` — the currency code (e.g. `"USD"`
    or `:USD`).

## Returns

  * `%__MODULE__{}` — the money value.

## Examples

    iex> Logistiki.Accounting.Money.new(Decimal.new("100"), "USD")
    %Logistiki.Accounting.Money{amount: Decimal.new("100"), currency: "USD"}

    iex> Logistiki.Accounting.Money.new("50.00", "EUR")
    %Logistiki.Accounting.Money{amount: Decimal.new("50.00"), currency: "EUR"}

    iex> Logistiki.Accounting.Money.new(42, :USD)
    %Logistiki.Accounting.Money{amount: Decimal.new(42), currency: "USD"}

# `positive?`
*since 0.1.0* 

```elixir
@spec positive?(t()) :: boolean()
```

True when the amount is greater than zero.

## Arguments

  * `m` — `%__MODULE__{}`.

## Returns

  * `boolean()`.

## Examples

    iex> Logistiki.Accounting.Money.positive?(Logistiki.Accounting.Money.new("100", "USD"))
    true
    iex> Logistiki.Accounting.Money.positive?(Logistiki.Accounting.Money.zero("USD"))
    false

# `sub`
*since 0.1.0* 

```elixir
@spec sub(t(), t()) :: t()
```

Subtracts `b` from `a` (same currency).

## Arguments

  * `a` — `%__MODULE__{}`.
  * `b` — `%__MODULE__{}` — must have the same `currency`.

## Returns

  * `%__MODULE__{}` — `a.amount - b.amount`.

## Examples

    iex> a = Logistiki.Accounting.Money.new("100", "USD")
    iex> b = Logistiki.Accounting.Money.new("30", "USD")
    iex> Logistiki.Accounting.Money.sub(a, b)
    %Logistiki.Accounting.Money{amount: Decimal.new("70"), currency: "USD"}

# `to_cents`
*since 0.1.0* 

```elixir
@spec to_cents(t()) :: integer()
```

Converts the amount to integer cents (rounded down).

## Arguments

  * `m` — `%__MODULE__{}`.

## Returns

  * `integer()` — the amount × 100, rounded down.

## Examples

    iex> Logistiki.Accounting.Money.to_cents(Logistiki.Accounting.Money.new("1000.00", "USD"))
    100000
    iex> Logistiki.Accounting.Money.to_cents(Logistiki.Accounting.Money.new("10.99", "USD"))
    1099

# `zero`
*since 0.1.0* 

```elixir
@spec zero(String.t()) :: t()
```

Returns the zero amount for `currency`.

## Arguments

  * `currency` — `String.t()` — e.g. `"USD"`.

## Returns

  * `%__MODULE__{amount: Decimal.new(0), currency: currency}`.

## Examples

    iex> Logistiki.Accounting.Money.zero("USD")
    %Logistiki.Accounting.Money{amount: Decimal.new(0), currency: "USD"}

# `zero?`
*since 0.1.0* 

```elixir
@spec zero?(t()) :: boolean()
```

True when the amount equals zero.

## Arguments

  * `m` — `%__MODULE__{}`.

## Returns

  * `boolean()`.

## Examples

    iex> Logistiki.Accounting.Money.zero?(Logistiki.Accounting.Money.zero("USD"))
    true

---

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