# `TAlib.Indicators.BBands`
[🔗](https://github.com/benyblack/talib/blob/main/lib/indicators/bbands.ex#L1)

Bollinger Bands [Wikipedia](https://en.wikipedia.org/wiki/Bollinger_Bands).

* middle = SMA(close, period)
* upper = middle + mult * StdDev(close, period)
* lower = middle - mult * StdDev(close, period)

See `TAlib` for the input conventions: prices are always given in
chronological order, oldest first. Every function returns `nil` when
there is not enough data.

# `bbands`

```elixir
@spec bbands([number()], pos_integer(), number()) ::
  %{upper: float(), middle: float(), lower: float()} | nil
```

Calculate the latest Bollinger Bands as a map.

## Parameters

  - prices: list of prices, oldest first.
  - period: SMA lookback window, a positive integer (default 20).
  - mult: standard deviation multiplier, a number (default 2).

## Examples

    iex> %{upper: u, middle: m, lower: l} = TAlib.Indicators.BBands.bbands([1, 2, 3, 4, 5], 4, 2)
    iex> {Float.round(u, 4), Float.round(m, 4), Float.round(l, 4)}
    {5.7361, 3.5, 1.2639}

# `bbands_list`

```elixir
@spec bbands_list([number()], pos_integer(), number()) :: [map() | nil]
```

Calculate the full Bollinger Bands series.

Returns a list aligned with `prices`: the first `period - 1` entries are
`nil`, and every later entry is a map with `:upper`, `:middle` and
`:lower`.

## Parameters

  - prices: list of prices, oldest first.
  - period: SMA lookback window, a positive integer (default 20).
  - mult: standard deviation multiplier, a number (default 2).

## Examples

    iex> TAlib.Indicators.BBands.bbands_list([1, 2, 3, 4, 5], 4, 2) |> Enum.count(&is_nil/1)
    3

# `init`

```elixir
@spec init([number()], pos_integer(), number()) ::
  {TAlib.Indicators.BBands.State.t(), [map() | nil]}
```

Warm up streaming Bollinger Bands state from `history`.

Returns `{state, values}` with `values` the full bands series of
`history` (identical to `bbands_list/3`), and `state` ready to
continue it one price at a time in O(1) via `next/2`. History needs
at least `period` prices.

## Examples

    iex> {state, values} = TAlib.Indicators.BBands.init([1, 2, 3, 4, 5], 4, 2)
    iex> List.last(values)
    %{upper: 5.73606797749979, lower: 1.2639320225002102, middle: 3.5}
    iex> {_state, %{upper: u, middle: 4.5, lower: l}} = TAlib.Indicators.BBands.next(state, 6)
    iex> {Float.round(u, 4), Float.round(l, 4)}
    {6.7361, 2.2639}

# `next`

```elixir
@spec next(TAlib.Indicators.BBands.State.t(), number()) ::
  {TAlib.Indicators.BBands.State.t(), map() | nil}
```

Advance streaming Bollinger Bands state by one price, in O(1):
`{state, %{upper: , middle: , lower: }}`.

    iex> {state, _} = TAlib.Indicators.BBands.init([1, 2, 3, 4, 5], 4, 2)
    iex> {_state, %{upper: u, middle: m, lower: l}} = TAlib.Indicators.BBands.next(state, 6)
    iex> {Float.round(u, 4), m, Float.round(l, 4)}
    {6.7361, 4.5, 2.2639}

---

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