``````# limited_queue

[![Hex.pm Version](http://img.shields.io/hexpm/v/limited_queue.svg?style=flat)](https://hex.pm/packages/limited_queue)

`limited_queue` is a simple Elixir queue, with a constant-time `size/1` and a maximum capacity.

## Usage

```elixir
defp deps do
[{:limited_queue, "~> 0.1.0"}]
end
```

Create a new queue with a capacity and drop strategy, then push and pop values from it.

```elixir
queue =
|> LimitedQueue.push("a")
|> LimitedQueue.push("b")
|> LimitedQueue.push("c")

{:ok, queue, "a"} = LimitedQueue.pop(queue)
{:ok, queue, "b"} = LimitedQueue.pop(queue)
{:error, :empty} = LimitedQueue.pop(queue)
0 = LimitedQueue.size(queue)
2 = LimitedQueue.capacity(queue)
```

You can also `append/2` multiple values to a queue at once, and get information about how many were dropped.

```elixir

{queue, dropped} = LimitedQueue.append(queue, ["a", "b", "c"])
1 = dropped
2 = LimitedQueue.size(queue)

{:ok, queue, "a"} = LimitedQueue.pop(queue)
{:ok, queue, "b"} = LimitedQueue.pop(queue)
{:error, :empty} = LimitedQueue.pop(queue)
```

`split/2` allows getting multiple values from the queue at once.

```elixir

{queue, 0} = LimitedQueue.append(queue, ["a", "b", "c"])

{queue, values} = LimitedQueue.split(queue, 2)
["a", "b"] = values
1 = LimitedQueue.size(queue)
```

## Documentation

This library contains internal documentation.
Documentation is available on [HexDocs](https://hexdocs.pm/limited_queue),
or you can generate the documentation from source:

```bash
\$ mix deps.get
\$ mix docs
```

## Running the Tests

Tests can be run by running `mix test` in the root directory of the library.

## Compared to `deque`

`LimitedQueue` has similar performance to [deque](https://hex.pm/packages/deque) depending on the situation (see Benchmarks).
It has a more special-purpose limited interface, it is a single-sided queue, and its internals are built on Erlang's `:queue`.

## Performance and Benchmarking

Benchmarks can be run by running `mix run bench/<benchmark file>.exs` in the root directory of the library.