bag.rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9903f16469a6e4bb4ae8cafddb1a98ac309b26d575e5419bdfcb936df46a7818
+  data.tar.gz: d1d6915f5dbc2d2350b074238baafe99fb408d855cc2000fda8c24e6ccf73a61
+SHA512:
+  metadata.gz: c88ac313f1270d67bf3b85cf09df979c490d14a0580e238d01c05317bb8ad8b738821fca8b83acba71af1895dafdbaf686faabdb947bbfc4f68d7df851d68874
+  data.tar.gz: 275713e0ed463c06e625ccda517028ebd4e478bb3e3a8937c76e317ee269be51b8d160ac6c90bd1a3b515bba4278cd63ec41f975e3c67c9e6f2641a71603815d

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Shannon Skipper
+
+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,193 @@
+# Bag
+
+A pure Ruby implementation of a **Bag** (multiset), inspired by Smalltalk-80's Bag class.
+
+A Bag is like a Set that remembers how many times you've added each element:
+
+```ruby
+Set.new(%w[quartz quartz obsidian])
+#=> #<Set: {"quartz", "obsidian"}>
+
+Bag.new(%w[quartz quartz obsidian])
+#=> #<Bag "quartz" => 2, "obsidian" => 1>
+
+%w[quartz quartz obsidian].tally
+#=> {"quartz" => 2, "obsidian" => 1}
+```
+
+## Installation
+
+```bash
+gem install bag.rb
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'bag.rb'
+```
+
+## Usage
+
+```ruby
+require 'bag'
+
+words = Bag.new(%w[the quick brown fox jumps over the lazy dog])
+
+words.count('the')
+#=> 2
+words.size
+#=> 9
+words.uniq_size
+#=> 8
+
+words << 'the' << 'the'
+words.add('fox', 2)
+words.remove('lazy')
+
+words.sorted_by_count
+#=> [['the', 4], ['fox', 3], ['quick', 1], ...]
+words.sample
+#=> 'the'
+```
+
+## API
+
+### Creation & Modification
+
+```ruby
+bag = Bag.new
+bag = Bag.new(%i[abyss void abyss chaos abyss])
+#=> #<Bag abyss: 3, void: 1, chaos: 1>
+bag = Bag.new(%i[abyss void abyss].tally)
+#=> #<Bag abyss: 2, void: 1>
+
+bag << 'nihil'
+bag.add('entropy', 5)
+bag.add('nihil', -1)
+
+bag.remove('nihil')
+bag.remove('nihil', 2)
+bag.remove_all('entropy')
+bag.clear
+
+bag.count('abyss')
+bag.include?('void')
+#=> true
+bag.empty?
+#=> false
+```
+
+### Set Operations
+
+```ruby
+bag1 = Bag.new(%i[phosphor phosphor glyph rune])
+bag2 = Bag.new(%i[phosphor glyph glyph sigil])
+
+bag1 + bag2
+#=> #<Bag phosphor: 3, glyph: 3, rune: 1, sigil: 1>
+bag1 & bag2
+#=> #<Bag phosphor: 1, glyph: 1>
+bag1 - bag2
+#=> #<Bag phosphor: 1, rune: 1>
+
+bag1 + {'phosphor' => 1, 'sigil' => 2}
+bag1 + Data.define(:x, :y).new(x: 3, y: 5)
+```
+
+### Enumeration
+
+```ruby
+bag = Bag.new([1, 2, 2, 3, 3, 3])
+
+bag.each { |n| print n }
+#=> 1 2 2 3 3 3
+
+bag.each_with_count { |element, count| puts "#{element}: #{count}" }
+
+bag.map { |n| n * 2 }
+#=> [2, 4, 4, 6, 6, 6]
+bag.filter { |n| n > 1 }
+#=> [2, 2, 3, 3, 3]
+bag.reduce(:+)
+#=> 14
+```
+
+### Analysis
+
+```ruby
+bag = Bag.new(%i[ressentiment pathos ethos logos ressentiment ressentiment])
+
+bag.sorted_by_count
+#=> [[:ressentiment, 3], [:pathos, 1], ...]
+
+bag.sorted_elements
+#=> {ethos: 1, logos: 1, ...}
+
+bag.cumulative_counts
+#=> [[:ressentiment, 3], [:pathos, 4], ...]
+
+bag.sample
+#=> :ressentiment
+bag.sample(3)
+#=> [:ressentiment, :logos, :ressentiment]
+```
+
+### Conversion & Comparison
+
+```ruby
+bag = Bag.new(%i[quasar quasar nebula])
+
+bag.to_a
+#=> [:quasar, :quasar, :nebula]
+bag.to_h
+#=> {quasar: 2, nebula: 1}
+bag.to_set
+#=> #<Set: {:quasar, :nebula}>
+
+Bag.new([1, 2]) < Bag.new([1, 2, 3])
+#=> true
+```
+
+## Examples
+
+### Word Frequency
+
+```ruby
+text = File.read('beowulf.txt')
+words = Bag.new(text.downcase.scan(/\w+/))
+
+words.sorted_by_count.first(10).each do |word, count|
+  puts "#{word}: #{count}"
+end
+```
+
+### Inventory Tracking
+
+```ruby
+inventory = Bag.new
+
+inventory.add('widget', 100)
+inventory.remove('widget', 15)
+inventory.count('widget')
+#=> 85
+```
+
+### Survey Analysis
+
+```ruby
+responses = Bag.new(%w[yes no yes yes maybe yes no])
+
+responses.sorted_by_count
+#=> [['yes', 4], ['no', 2], ['maybe', 1]]
+
+total = responses.size
+responses.each_with_count do |response, count|
+  percentage = (count.fdiv(total * 100)).round(1)
+  puts "#{response}: #{percentage}%"
+end
+```
+
+## Requirements
+
+- Ruby 3+

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'minitest/test_task'
+require 'rubocop/rake_task'
+
+task default: %i[test rubocop]
+
+Minitest::TestTask.create
+
+RuboCop::RakeTask.new do |task|
+  task.plugins << 'rubocop-minitest'
+end

data/lib/bag/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class Bag
+  VERSION = '0.1.0'
+end

data/lib/bag.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require_relative 'bag/version'
+
+class Bag
+  include Comparable
+  include Enumerable
+
+  def initialize(elements = nil)
+    @contents = Hash.new(0)
+    return unless elements
+
+    if elements.is_a?(Hash)
+      elements.each { |element, count| add(element, count) }
+    else
+      elements.each { |element| add element }
+    end
+  end
+
+  def add(element, occurrences = 1)
+    raise ArgumentError, 'bag elements cannot be nil' if element.nil?
+    return self if occurrences.zero?
+
+    @contents[element] += occurrences
+    @contents.delete(element) unless @contents[element].positive?
+    self
+  end
+
+  def <<(element)
+    raise ArgumentError, 'bag elements cannot be nil' if element.nil?
+
+    @contents[element] += 1
+    self
+  end
+
+  def remove(element, occurrences = 1)
+    add(element, -occurrences)
+  end
+
+  def remove_all(element)
+    @contents.delete(element)
+    self
+  end
+
+  def occurrences_of(element) = @contents[element]
+  alias count occurrences_of
+
+  def include?(element) = @contents.key?(element) && @contents[element].positive?
+
+  def size = @contents.values.sum
+  alias length size
+
+  def uniq_size = @contents.size
+
+  def each
+    return enum_for(__method__) unless block_given?
+
+    @contents.each { |element, count| count.times { yield element } }
+    self
+  end
+
+  def each_with_count(&)
+    return enum_for(__method__) unless block_given?
+
+    @contents.each(&)
+    self
+  end
+
+  def to_a = @contents.flat_map { |element, count| [element] * count }
+
+  def to_h = @contents.dup
+
+  def keys = @contents.keys
+
+  def values = @contents.values
+
+  def sorted_by_count
+    @contents.sort_by { |_element, count| -count }.map { |element, count| [element, count] }
+  end
+
+  def sorted_elements
+    @contents.sort.to_h
+  end
+
+  def cumulative_counts
+    cumulative = 0
+    sorted_by_count.map do |element, count|
+      cumulative += count
+      [element, cumulative]
+    end
+  end
+
+  def to_set
+    @contents.keys.to_set
+  end
+
+  def empty? = @contents.empty?
+
+  def clear
+    @contents.clear
+    self
+  end
+
+  def sample(num = nil, random: Random)
+    return (num ? [] : nil) if empty?
+
+    if num
+      raise ArgumentError, 'negative array size' if num.negative?
+
+      return Array.new(num) { sample(random:) }
+    end
+
+    sample_single(random)
+  end
+
+  def +(other)
+    other = from_hash(other)
+    result = Bag.new
+
+    @contents.each { |element, count| result.contents[element] = count }
+    other.contents.each { |element, count| result.contents[element] += count }
+
+    result
+  end
+
+  def &(other)
+    other = from_hash(other)
+    result = Bag.new
+
+    @contents.each do |element, count|
+      other_count = other.contents[element]
+      result.contents[element] = [count, other_count].min if other_count.positive?
+    end
+
+    result
+  end
+
+  def -(other)
+    other = from_hash(other)
+    result = Bag.new
+
+    @contents.each do |element, count|
+      remaining = count - other.contents[element]
+      result.contents[element] = remaining if remaining.positive?
+    end
+
+    result
+  end
+
+  def ==(other)
+    return false unless other.is_a?(Bag)
+
+    @contents == other.contents
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(Bag)
+    return size <=> other.size unless size == other.size
+    return uniq_size <=> other.uniq_size unless uniq_size == other.uniq_size
+
+    compare_contents(other)
+  end
+
+  def inspect = "#<Bag: #{@contents.inspect}>"
+  alias to_s inspect
+
+  def pretty_print(pp)
+    pp.object_group(self) do
+      pp.seplist(@contents, -> { pp.text ',' }) do |element, count|
+        pp.breakable
+        if element.is_a?(Symbol)
+          pp.text element.inspect[1..]
+          pp.text ': '
+        else
+          pp.pp element
+          pp.text ' => '
+        end
+        pp.pp count
+      end
+    end
+  end
+
+  protected
+
+  attr_reader :contents
+
+  private
+
+  def sample_single(random)
+    target_index = random.rand(size)
+    current_sum = 0
+
+    element, = @contents.find do |_, count|
+      current_sum += count
+      target_index < current_sum
+    end
+    element
+  end
+
+  def compare_contents(other)
+    to_a.sort <=> other.to_a.sort
+  rescue ArgumentError
+    nil
+  end
+
+  def from_hash(other)
+    return other if other.is_a?(Bag)
+    raise TypeError, "can't convert #{other.class} to Bag" unless other.respond_to?(:to_h)
+
+    Bag.new(other.to_h)
+  end
+
+  def coerce(other) = [from_hash(other), self]
+end

data.tar.gz.sig

@@ -0,0 +1,2 @@
+0D �
+X���f����0����A��1�-8��j: aVG��Q(X2��3΋���)�#���|�!�H��

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: bag.rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shannon Skipper
+bindir: bin
+cert_chain:
+- |
+  -----BEGIN CERTIFICATE-----
+  MIIBnjCCAUSgAwIBAgIULmCXzaYrvh/BroPeBvKWunNA4hAwCgYIKoZIzj0EAwIw
+  NTEZMBcGA1UEAwwQdGVzdEBleGFtcGxlLmNvbTEYMBYGA1UECgwPR2VtIERldmVs
+  b3BtZW50MB4XDTI1MTEwMTE3MTkzN1oXDTI2MTEwMTE3MTkzN1owNTEZMBcGA1UE
+  AwwQdGVzdEBleGFtcGxlLmNvbTEYMBYGA1UECgwPR2VtIERldmVsb3BtZW50MFkw
+  EwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEuYczd7Vw1YnU4rqc1+5PgDB7RKt3n6hR
+  gpH3SHvFzBgydoBVEWBN6AZO/japfJKPkFyyoq3czTxpf5Gv9BYpG6MyMDAwHQYD
+  VR0OBBYEFCL6dJfmuDOO3qRtOvStGtKZjNIEMA8GA1UdEwEB/wQFMAMBAf8wCgYI
+  KoZIzj0EAwIDSAAwRQIge/heFuZqCd6kY0EEpfngKUarj3EezKMtueh9Fj6366sC
+  IQC60bGRQkfaXYX8ekTdBtg3VFOFe/8/UCX24qhAZxC3cA==
+  -----END CERTIFICATE-----
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A pure Ruby implementation of a bag (multiset) collection that tracks
+  element occurrences
+email:
+- shannonskipper@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/bag.rb
+- lib/bag/version.rb
+homepage: https://github.com/havenwood/bag.rb
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/havenwood/bag.rb
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.0.dev
+specification_version: 4
+summary: A bag (multiset) data structure
+test_files: []

metadata.gz.sig

@@ -0,0 +1 @@
+0D F붽�%�&��ۄU{�a8��P��Q�,�A Q-�v*�
W_�خ�AE�ud��(�5��@<��D