Initial commit

Author: keathley

.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs"]
+]

.gitignore

@@ -0,0 +1,24 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez
+
+# Ignore package tarball (built via "mix hex.build").
+circular_buffer-*.tar
+

README.md

@@ -0,0 +1,22 @@
+# CircularBuffer
+
+CircularBuffer provides a general-purpose CircularBuffer data structure.
+
+Docs: [https://hexdocs.pm/circular_buffer](https://hexdocs.pm/circular_buffer).
+
+## Installation
+
+```elixir
+def deps do
+  [
+    {:circular_buffer, "~> 0.1"}
+  ]
+end
+```
+
+## Should I use this?
+
+The entire codebase is less than 50 lines of code and has been tested using
+property based testing. I believe the implementation is sound but it may not
+be the highest performance library out there.
+

config/config.exs

@@ -0,0 +1,30 @@
+# This file is responsible for configuring your application
+# and its dependencies with the aid of the Mix.Config module.
+use Mix.Config
+
+# This configuration is loaded before any dependency and is restricted
+# to this project. If another project depends on this project, this
+# file won't be loaded nor affect the parent project. For this reason,
+# if you want to provide default values for your application for
+# third-party users, it should be done in your "mix.exs" file.
+
+# You can configure your application as:
+#
+#     config :circular_buffer, key: :value
+#
+# and access this configuration in your application as:
+#
+#     Application.get_env(:circular_buffer, :key)
+#
+# You can also configure a third-party app:
+#
+#     config :logger, level: :info
+#
+
+# It is also possible to import configuration files, relative to this
+# directory. For example, you can emulate configuration per environment
+# by uncommenting the line below and defining dev.exs, test.exs and such.
+# Configuration from the imported file will override the ones defined
+# here (which is why it is important to import them last).
+#
+#     import_config "#{Mix.env()}.exs"

lib/circular_buffer.ex

@@ -0,0 +1,48 @@
+defmodule CircularBuffer do
+  @moduledoc """
+  Circular Buffer built around erlang's queue module.
+
+  When creating a circular buffer you must specify the max size:
+
+  ```
+  cb = CircularBuffer.new(10)
+  ```
+  """
+
+  def new(size) when is_integer(size) and size > 0 do
+    %{q: :queue.new(), max_size: size, count: 0}
+  end
+
+  def insert(cb, item) do
+    if cb.count < cb.max_size do
+      %{cb | q: :queue.cons(item, cb.q), count: cb.count + 1}
+    else
+      new_q =
+        cb.q
+        |> :queue.drop_r
+        |> (fn q -> :queue.cons(item, q) end).()
+
+      %{cb | q: new_q}
+    end
+  end
+
+  def to_list(cb) do
+    cb.q
+    |> :queue.reverse
+    |> :queue.to_list
+  end
+
+  def newest(cb) do
+    case :queue.peek(cb.q) do
+      {_, val} -> val
+      :empty -> nil
+    end
+  end
+
+  def oldest(cb) do
+    case :queue.peek_r(cb.q) do
+      {_, val} -> val
+      :empty -> nil
+    end
+  end
+end

mix.exs

@@ -0,0 +1,57 @@
+defmodule CircularBuffer.MixProject do
+  use Mix.Project
+
+  @version "0.1.0"
+
+  def project do
+    [
+      app: :circular_buffer,
+      version: @version,
+      elixir: "~> 1.8",
+      start_permanent: Mix.env() == :prod,
+      deps: deps(),
+      description: description(),
+      package: package(),
+      name: "CircularBuffer",
+      source_url: "https://github.com/keathley/circular_buffer",
+      docs: docs()
+    ]
+  end
+
+  # Run "mix help compile.app" to learn about applications.
+  def application do
+    [
+      extra_applications: [:logger]
+    ]
+  end
+
+  # Run "mix help deps" to learn about dependencies.
+  defp deps do
+    [
+      {:propcheck, "~> 1.2", only: [:dev, :test]},
+      {:ex_doc, "~> 0.19", only: [:dev, :test]}
+    ]
+  end
+
+  def description do
+    """
+    General purpose circular buffer.
+    """
+  end
+
+  def package do
+    [
+      name: "circular_buffer",
+      licenses: ["MIT"],
+      links: %{"GitHub" => "https://github.com/keathley/circular_buffer"}
+    ]
+  end
+
+  def docs do
+    [
+      source_ref: "v#{@version}",
+      source_url: "https://github.com/keathley/circular_buffer",
+      main: "CircularBuffer"
+    ]
+  end
+end

mix.lock

@@ -0,0 +1,9 @@
+%{
+  "earmark": {:hex, :earmark, "1.4.2", "3aa0bd23bc4c61cf2f1e5d752d1bb470560a6f8539974f767a38923bb20e1d7f", [:mix], [], "hexpm"},
+  "ex_doc": {:hex, :ex_doc, "0.21.2", "caca5bc28ed7b3bdc0b662f8afe2bee1eedb5c3cf7b322feeeb7c6ebbde089d6", [:mix], [{:earmark, "~> 1.3.3 or ~> 1.4", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm"},
+  "makeup": {:hex, :makeup, "1.0.0", "671df94cf5a594b739ce03b0d0316aa64312cee2574b6a44becb83cd90fb05dc", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.14.0", "cf8b7c66ad1cff4c14679698d532f0b5d45a3968ffbcbfd590339cb57742f1ae", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm"},
+  "nimble_parsec": {:hex, :nimble_parsec, "0.5.2", "1d71150d5293d703a9c38d4329da57d3935faed2031d64bc19e77b654ef2d177", [:mix], [], "hexpm"},
+  "propcheck": {:hex, :propcheck, "1.2.0", "e2b84f2f1a4c46b6b2aa22a0f6ddf97696f99d4a5c8f71d45f6519741e727eca", [:mix], [{:proper, "~> 1.3", [hex: :proper, repo: "hexpm", optional: false]}], "hexpm"},
+  "proper": {:hex, :proper, "1.3.0", "c1acd51c51da17a2fe91d7a6fc6a0c25a6a9849d8dc77093533109d1218d8457", [:make, :mix, :rebar3], [], "hexpm"},
+}

test/circular_buffer_test.exs

@@ -0,0 +1,93 @@
+defmodule CircularBufferTest do
+  use ExUnit.Case, async: false
+  use PropCheck
+
+  alias CircularBuffer, as: CB
+
+  property "new/1 accepts a max size" do
+    forall i <- integer() do
+      try do
+        buffer = CB.new(i)
+        buffer.max_size == i
+      rescue
+        FunctionClauseError ->
+          i <= 0
+
+        _ ->
+          false
+      end
+    end
+  end
+
+  property "the count matches the number of elements in the buffer" do
+    forall {size, is} <- {pos_integer(), list(integer())} do
+      buffer = Enum.reduce(is, CB.new(size), fn i, cb -> CB.insert(cb, i) end)
+      :queue.len(buffer.q) == buffer.count
+    end
+  end
+
+  property "the number of elements never exceeds the size of the buffer" do
+    forall {size, is} <- size_and_list() do
+      buffer = Enum.reduce(is, CB.new(size), fn i, cb -> CB.insert(cb, i) end)
+      :queue.len(buffer.q) <= size
+    end
+  end
+
+  property "the 'oldest' elements are dropped from the buffer" do
+    forall {size, is} <- size_and_list() do
+      iis = Enum.with_index(is)
+
+      buffer =
+        iis
+        |> Enum.reduce(CB.new(size), fn i, cb -> CB.insert(cb, i) end)
+
+      slice =
+        iis
+        |> Enum.reverse
+        |> Enum.take(size)
+
+      :queue.to_list(buffer.q) == slice
+    end
+  end
+
+  property "newest/1 returns the newest element in the buffer" do
+    forall {size, is} <- size_and_list() do
+      iis = Enum.with_index(is)
+
+      buffer = Enum.reduce(iis, CB.new(size), fn i, cb -> CB.insert(cb, i) end)
+
+      CB.newest(buffer) == Enum.at(Enum.reverse(iis), 0)
+    end
+  end
+
+  property "oldest/1 returns the oldest element in the buffer" do
+    forall {size, is} <- size_and_list() do
+      iis = Enum.with_index(is)
+
+      buffer = Enum.reduce(iis, CB.new(size), fn i, cb -> CB.insert(cb, i) end)
+
+      oldest =
+        iis
+        |> Enum.reverse()
+        |> Enum.drop(size-1)
+        |> Enum.at(0)
+
+      CB.oldest(buffer) == oldest
+    end
+  end
+
+  def size_and_list do
+    let size <- pos_integer() do
+      let is <- ints(size*2, []) do
+        {size, is}
+      end
+    end
+  end
+
+  defp ints(0, acc), do: acc
+  defp ints(size, acc) do
+    let i <- integer() do
+      ints(size-1, [i | acc])
+    end
+  end
+end

test/test_helper.exs

@@ -0,0 +1 @@
+ExUnit.start()