# `NumberF.Tax`
[🔗](https://github.com/jamesnjovu/elixir_number_functions/blob/v0.3.0/lib/number_f/tax.ex#L1)

Functions for tax calculations including VAT, sales tax, and income tax.

# `calculate_capital_gains_tax`

Calculates tax on capital gains, with optional annual exemption.

## Parameters
  - `gain`: The capital gain amount
  - `rate`: The capital gains tax rate as a decimal
  - `exemption`: Annual tax-free allowance (default: 0)

## Examples

    iex> NumberF.Tax.calculate_capital_gains_tax(20_000, 0.2, 12_300)
    %{gain: 20000.0, taxable_gain: 7700.0, tax: 1540.0, net: 18460.0}

# `calculate_corporate_tax`

Calculates corporate tax on profits.

## Parameters
  - `profit`: The taxable profit
  - `rate`: The corporate tax rate as a decimal

## Examples

    iex> NumberF.Tax.calculate_corporate_tax(100_000, 0.19)
    %{profit: 100000.0, tax: 19000.0, after_tax: 81000.0}

# `calculate_income_tax`

Calculates progressive income tax based on tax brackets.

## Parameters
  - `income`: The taxable income
  - `brackets`: A list of tax brackets, each as a tuple {threshold, rate}
               sorted in ascending order by threshold

## Examples

    iex> brackets = [{0, 0.0}, {12_570, 0.2}, {50_270, 0.4}, {150_000, 0.45}]
    iex> NumberF.Tax.calculate_income_tax(30_000, brackets)
    %{tax: 3486.0, effective_rate: 0.1162}

# `calculate_payroll_tax`

Calculates payroll taxes including employee and employer contributions.

## Parameters
  - `salary`: The gross salary
  - `employee_rate`: The employee contribution rate as a decimal
  - `employer_rate`: The employer contribution rate as a decimal
  - `cap`: Maximum amount subject to payroll tax (default: nil, no cap)

## Examples

    iex> NumberF.Tax.calculate_payroll_tax(50_000, 0.12, 0.138)
    %{salary: 50000.0, employee_contribution: 6000.0, employer_contribution: 6900.0, total_cost: 56900.0, take_home: 44000.0}

# `calculate_sales_tax`

Calculates sales tax for a given amount and rate.

## Parameters
  - `amount`: The amount before tax
  - `rate`: The sales tax rate as a decimal (e.g., 0.06 for 6%)
  - `options`: Additional options
    - `:round_to`: Round the tax amount to the nearest value (default: 0.01)

## Examples

    iex> NumberF.Tax.calculate_sales_tax(100, 0.06)
    %{subtotal: 100.0, tax: 6.0, total: 106.0}

    iex> NumberF.Tax.calculate_sales_tax(100, 0.06, round_to: 0.05)
    %{subtotal: 100.0, tax: 6.0, total: 106.0}

# `calculate_vat`

Calculates Value Added Tax (VAT) for a given amount and rate.

## Parameters
  - `amount`: The amount before tax
  - `rate`: The VAT rate as a decimal (e.g., 0.2 for 20%)
  - `included`: Whether the amount already includes VAT (default: false)

## Examples

    iex> NumberF.Tax.calculate_vat(100, 0.2)
    %{net: 100.0, vat: 20.0, gross: 120.0}

    iex> NumberF.Tax.calculate_vat(120, 0.2, true)
    %{net: 100.0, vat: 20.0, gross: 120.0}

# `calculate_withholding_tax`

Calculates withholding tax for dividends or interest based on a flat rate.

## Parameters
  - `amount`: The gross amount
  - `rate`: The withholding tax rate as a decimal

## Examples

    iex> NumberF.Tax.calculate_withholding_tax(1000, 0.15)
    %{gross: 1000.0, tax: 150.0, net: 850.0}

# `income_tax_brackets`

Returns sample income tax brackets for different countries.
Note: These are simplified examples and may not reflect current tax law.

## Examples

    iex> NumberF.Tax.income_tax_brackets()["US"]
    [{0, 0.1}, {9950, 0.12}, {40_525, 0.22}, {86_375, 0.24}, {164_925, 0.32}, {209_425, 0.35}, {523_600, 0.37}]

# `vat_rates`

Returns common VAT rates for different countries.

## Examples

    iex> NumberF.Tax.vat_rates()["UK"]
    0.2

    iex> NumberF.Tax.vat_rates()["Germany"]
    0.19

---

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