fixed_size_buffer 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1754b5a2e7a437b5fc4b705b420d7ba81a03bd0265aba64001b850c3c7b5d95c
+  data.tar.gz: 5dbc25d63dc6fe6f1485790080010339b1f7381e19ee4f518dcbf2c033be1dad
+SHA512:
+  metadata.gz: ae54776240a4611208a9af5c535eb050bf5cfae228f1acf86d298b7230dd4572717fa944d7b5ef22febc65ed8d837966e4eb3756d351cb9fe3b1fc373b6b07ae
+  data.tar.gz: f52a8abf718310388808f5f629b4dcacb622f403f8088ee37aebb8a9e2c6468290909d5cb8fef0f58deaac7e2fd99e35543d00c58f7ca32059da5fff8291a583

data/CHANGELOG.md

@@ -0,0 +1,4 @@
+Release v0.1.0
+====================
+
+Initial public release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Justin Howard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,96 @@
+FixedSizeBuffer
+==================
+
+[![Gem Version](https://badge.fury.io/rb/fixed_size_buffer.svg)](https://badge.fury.io/rb/fixed_size_buffer)
+[![CI](https://github.com/justinhoward/fixed_size_buffer/workflows/CI/badge.svg)](https://github.com/justinhoward/fixed_size_buffer/actions?query=workflow%3ACI+branch%3Amaster)
+[![Code Quality](https://app.codacy.com/project/badge/Grade/e647db61b5064a6e97fc20ffe7f0430e)](https://www.codacy.com/gh/justinhoward/fixed_size_buffer/dashboard?utm_source=github.com&utm_medium=referral&utm_content=justinhoward/fixed_size_buffer&utm_campaign=Badge_Grade)
+[![Code Coverage](https://app.codacy.com/project/badge/Grade/e647db61b5064a6e97fc20ffe7f0430e)](https://www.codacy.com/gh/justinhoward/fixed_size_buffer/dashboard?utm_source=github.com&utm_medium=referral&utm_content=justinhoward/fixed_size_buffer&utm_campaign=Badge_Grade)
+[![Inline docs](http://inch-ci.org/github/justinhoward/fixed_size_buffer.svg?branch=master)](http://inch-ci.org/github/justinhoward/fixed_size_buffer)
+
+A ring buffer with a fixed capacity
+
+```ruby
+buffer = FixedSizeBuffer.new(3)
+buffer.write(1)
+buffer.write(2)
+buffer.to_a # [1, 2]
+buffer.read # => 1
+buffer.read # => 2
+```
+
+What is a Ring Buffer?
+------------------------
+
+A ring buffer is a continuously writable and continuously readable data
+structure that is contained in a fixed amount of memory. It can be
+conceptualized as writing values around a circular array. As we write, we move
+clockwise around the circle, and the reader trails around in the same direction.
+
+The advantages of a ring buffer as opposed to pushing and shifting an array is
+that a ring buffer only can be heap allocated once, and since it's a fixed size,
+it never needs to be reallocated.
+
+Installation
+---------------
+
+Add it to your `Gemfile`:
+
+```ruby
+gem 'fixed_size_buffer'
+```
+
+Or install it manually:
+
+```sh
+gem install fixed_size_buffer
+```
+
+API Documentation
+--------------
+
+API docs can be read [on rubydoc.info][api docs], inline in the source code, or
+you can generate them yourself with Ruby `yard`:
+
+```sh
+bin/yardoc
+```
+
+Then open `doc/index.html` in your browser.
+
+Usage
+-----------
+
+Create a new ring buffer with a given capacity
+
+```ruby
+buffer = FixedSizeBuffer.new(100)
+```
+
+Then write and read from the buffer
+
+```ruby
+buffer = FixedSizeBuffer.new(2)
+buffer.empty? # => true
+buffer.size # => 0
+buffer.write('hello')
+buffer.write('world')
+buffer.size # => 2
+buffer.full? # => true
+buffer.to_a # => ['hello', 'world']
+buffer.peek # => 'hello'
+buffer.read # => 'hello'
+buffer.read # => 'world'
+buffer.read # => nil
+```
+
+Once the buffer fills up, it will overwrite the oldest values.
+
+```ruby
+buffer = FixedSizeBuffer.new(2)
+buffer.write('hello')
+buffer.write('world')
+buffer.write('again')
+buffer.read # => 'world'
+```
+
+[api docs]: https://www.rubydoc.info/github/justinhoward/fixed_size_buffer/master

data/lib/fixed_size_buffer.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'fixed_size_buffer/version'
+
+# A ring buffer with a fixed capacity
+#
+# Principal of Operation
+# ========================
+# A ring buffer is a continuously writable and continuously readable
+# data structure that is contained in a fixed amount of memory. It can be
+# conceptualized as writing values around a circular array. As we write,
+# we move clockwise around the circle, and reading trails around in the
+# same direction.
+#
+# If the reader catches up to the writer, the buffer is empty. If the writer
+# wraps around and catches up to the reader, the buffer is full. In our case,
+# we allow the writer to continue writing to a full buffer, which causes
+# the oldest values to be dropped.
+#
+# Implementation
+# =======================
+# This ring buffer is implemented as a fixed-size array. We also maintain
+# a read index and a write index. These are the positions where the next read
+# or write will occur. We increase the write pointer by one each time we write
+# to the buffer. We also increase the read pointer by one every time we read.
+#
+# The buffer is considered empty if the read and write pointers are in the
+# same position. In this state, reading will not move the read pointer, and
+# `nil` will be returned.
+#
+# An empty buffer of capacity 3.
+# ```text
+#        rw
+# |  |  |  |  |
+# ```
+#
+# The buffer is considered full if the write pointer is in the position
+# immediately before the read pointer. In this state, writing will overwrite
+# the next position, which will be the oldest value in the buffer. Writing
+# in this state will also move the read pointer forward so that the next
+# read will continue from the next-oldest value.
+#
+# A full buffer of capacity 3. Note that the 2 here is already considered
+# overwritten.
+# ```text
+#       w   r
+# | 5 | 2 | 3 | 4 |
+# ```
+#
+# Another full buffer with the same values but in a wrapped-around position.
+# ```text
+#   r           w
+# | 3 | 4 | 5 | 2 |
+# ```
+#
+# Notice that the array for this buffer has one extra position. This is used to
+# differentiate between an empty buffer (read/write pointers in same position),
+# and a full buffer (write pointer just before read pointer). The value
+# in-between the read and write pointers for a full buffer will not be read.
+class FixedSizeBuffer
+  attr_reader :capacity
+
+  # Create a new empty {FixedSizeBuffer}
+  #
+  # Start state
+  #  rw
+  # |  |  |  |  |
+  #
+  # @param capacity [Integer] The number of items this buffer can hold
+  def initialize(capacity)
+    @capacity = capacity
+    @buffer = Array.new(capacity + 1)
+    @read = 0
+    @write = 0
+  end
+
+  # Read one value from the buffer
+  #
+  # The value will be "consumed", meaning it will no longer be readable. If the
+  # buffer is empty, this will return nil, so if it matters, check `empty?`
+  # before calling `read`.
+  #
+  # @return [Object, nil] The value that was read, or nil if empty
+  def read
+    return nil if empty?
+
+    value = @buffer[@read]
+    @read = (@read + 1) % @buffer.size
+    value
+  end
+
+  # Read a value from the buffer without consuming it
+  #
+  # Like {#read}, this will return nil when the buffer is empty, so
+  # check {#empty} if you need to distinguish between the two states.
+  #
+  # @return [Object, nil] The value that was read, or nil if empty
+  def peek
+    return nil if empty?
+
+    @buffer[@read]
+  end
+
+  # Write one value to the buffer
+  #
+  # Write a value to thee buffer
+  #
+  # @param value [Object] The value to write
+  # @return [void]
+  def write(value)
+    @buffer[@write] = value
+
+    # If the buffer is full before a write, we drop the oldest value by
+    # moving the read pointer as well
+    @read = (@read + 1) % @buffer.size if full?
+    @write = (@write + 1) % @buffer.size
+    nil
+  end
+
+  # Is the buffer full?
+  #
+  # A full buffer does not prevent writes, but it does mean that the next
+  # write will overwrite an unread value.
+  #
+  # @return [Boolean] True if the buffer is full
+  def full?
+    # When full, the write pointer will be one less than the read pointer
+    # (mod buffer size).
+    (@write + 1) % @buffer.size == @read
+  end
+
+  def empty?
+    # When empty, the read and write pointers will be in the same place.
+    @read == @write
+  end
+
+  # The number of unread items
+  #
+  # @return [Integer] The buffer size
+  def size
+    if @write >= @read
+      @write - @read
+    else
+      @buffer.size - @read + @write
+    end
+  end
+
+  # Get an array of all the unread items in the buffer
+  #
+  # Unlike {#read}, this does not consume buffer items
+  #
+  # @return [Array<Object>] An array having length of {#size}
+  def to_a
+    if @write >= @read
+      @buffer[@read...@write]
+    else
+      @buffer[@read...@buffer.size] + @buffer[0...@write]
+    end
+  end
+end

data/lib/fixed_size_buffer/version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+class FixedSizeBuffer
+  # The current FixedSizeBuffer gem version
+  VERSION = '0.1.0'
+
+  def self.version
+    Gem::Version.new(VERSION)
+  end
+end

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: fixed_size_buffer
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Justin Howard
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2021-03-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.81.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 0.81.0
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.38.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '='
+      - !ruby/object:Gem::Version
+        version: 1.38.1
+description:
+email:
+- jmhoward0@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/fixed_size_buffer.rb
+- lib/fixed_size_buffer/version.rb
+homepage: https://github.com/justinhoward/fixed_size_buffer
+licenses:
+- MIT
+metadata:
+  changelog_uri: https://github.com/justinhoward/fixed_size_buffer/blob/master/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key:
+specification_version: 4
+summary: A circular data structure
+test_files: []