# `FuelSurcharge`

Fuel surcharge (FSC) math the way most broker and shipper contracts write it.

A contract names a **base price** (the "peg", often somewhere between $1.20 and
$2.50 a gallon) and an **MPG divisor** (usually 5, 6 or 6.5). Each week the
current diesel average is compared with the peg, and the gap is turned into a
per-mile surcharge:

    surcharge per mile = (current price - base price) / mpg

If diesel is at or below the peg, the surcharge is zero. All money values are
floats rounded to the cent (per-mile values to a tenth of a cent).

# `bracket_table`

```elixir
@spec bracket_table(number(), number(), number(), number(), number()) :: [
  {float(), float()}
]
```

Builds a bracket table like the ones printed in shipper contracts: one row
per price step from `from` to `to`, each with its per-mile surcharge.

    iex> FuelSurcharge.bracket_table(1.25, 6, 3.50, 3.70, 0.10)
    [{3.5, 0.375}, {3.6, 0.392}, {3.7, 0.408}]

# `for_trip`

```elixir
@spec for_trip(number(), number(), number(), number()) :: float()
```

Surcharge owed for a whole trip.

Pass `loaded_miles` only; most contracts do not pay FSC on deadhead.

    iex> FuelSurcharge.for_trip(3.85, 1.25, 6, 812)
    351.6

# `per_mile`

```elixir
@spec per_mile(number(), number(), number()) :: float()
```

Per-mile surcharge for a diesel price, a base peg and an MPG divisor.

    iex> FuelSurcharge.per_mile(3.85, 1.25, 6)
    0.433

    iex> FuelSurcharge.per_mile(1.10, 1.25, 6)
    0.0

# `percent_of_linehaul`

```elixir
@spec percent_of_linehaul(number(), number(), number(), number(), number()) :: float()
```

Surcharge as a share of the linehaul, useful when a rate confirmation shows
one all-in number and you want to know how much of it is really fuel.

    iex> FuelSurcharge.percent_of_linehaul(3.85, 1.25, 6, 812, 2100)
    16.7

---

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