bloom_fit 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efa22c92049e3607485a8fcfe471b15cca6e85e6da0c7b19b65f74b9f6ad5fe9
-  data.tar.gz: 5e8432456b1258111671d536165217bc3e82e0e430c3bc63112abc4670f91e78
+  metadata.gz: cd631cdb483e0a84fa05d56eb962fda0f7c7d7a0b002ea708024ce82505a9054
+  data.tar.gz: ee781997465d6f5b590828082e4fadd5b00768298bbdec7845b9f07c3d046549
 SHA512:
-  metadata.gz: 72738a57ccb3a1a8989e86993490c3ba6a4f90925c834c1acd70ba104df8ef2bb318d5c66830786ba662e88df09f9ce46d7184810e3d4ec1c6b4cc0b41fcec44
-  data.tar.gz: 7472e370d1a66a6034ecb2f0d4720b9edd12f21e181a37cae2869e0e34c70a829366e7ee6caf880f4c4d8c789bc18bdbe2f83e6699617ccc77460320f2a2a1af
+  metadata.gz: 7862f2d0189bae865c6fc5e7c7ad24f5c7ab0420415a455a1a0b130835d639c536cb8925b08219eab7dd7a10db1e9299b2868019d3e2259db4dce96de01e50a2
+  data.tar.gz: 41cb7f2fcb8cf80f5345785ce0110e242a29fbe6177284b13b701973ec7b0e7010d788585e406f77712f7ee284ff308633fe060e492b0e153a4a5598658fd465

data/lib/bloom_fit/version.rb

@@ -1,3 +1,3 @@
 class BloomFit
-  VERSION = "0.3.0".freeze
+  VERSION = "0.3.1".freeze
 end

data/lib/bloom_fit.rb

@@ -4,63 +4,150 @@ require "cbloomfilter"
 require "bloom_fit/configuration_mismatch"
 require "bloom_fit/version"
 
+# BloomFit is an in-memory Bloom filter with a small, Set-like API.
+#
+# Bloom filters are probabilistic membership structures: they can report false
+# positives, but they do not report false negatives for values that have been
+# added. That makes BloomFit useful for cheaply ruling out missing values
+# before doing more expensive work, while keeping memory usage low.
+#
+# The class wraps the native +CBloomFilter+ implementation in Ruby-friendly
+# methods such as +add+, +include?+, +merge+, +&+, and +|+. Instances can be
+# serialized with +save+ and reloaded with +BloomFit.load+.
+#
+# Filters can only be combined when they were created with the same +size+ and
+# +hashes+ values; otherwise +BloomFit::ConfigurationMismatch+ is raised.
+#
+#   filter = BloomFit.new(size: 10_000, hashes: 6)
+#   filter.add("cat")
+#   filter.include?("cat") # => true
+#   filter.include?("dog") # => false
+#
+# Choose +size+ and +hashes+ based on the expected number of inserts and the
+# false-positive rate you can tolerate.
 class BloomFit
   extend Forwardable
 
+  # The wrapped native +CBloomFilter+ instance.
+  #
+  # This is mostly useful for low-level integrations and internal filter
+  # operations such as merge, union, and intersection.
   attr_reader :bf
 
+  # Creates an empty Bloom filter.
+  #
+  # The defaults are a reasonable starting point for small in-memory filters,
+  # but the best values depend on how many keys you expect to insert and how
+  # many false positives you can tolerate.
+  #
   # @param size [Integer] number of buckets in a bloom filter
   # @param hashes [Integer] number of hash functions
   def initialize(size: 1_000, hashes: 4)
     @bf = CBloomFilter.new(size, hashes)
   end
 
+  # :method: m
+  #
+  # Returns the configured filter width.
+
+  # :method: k
+  #
+  # Returns the number of hash functions applied to each key.
+
+  # :method: bitmap
+  #
+  # Returns the raw bitmap as a binary string.
+  #
+  # The returned bytes reflect the native representation, so the string may
+  # include padding beyond the configured filter size.
+
+  # :method: include?
+  #
+  # Returns +true+ when +key+ may be present and +false+ when it is definitely
+  # absent.
+  #
+  # Positive results are probabilistic and may be false positives.
+
+  # :method: clear
+  #
+  # Clears the filter by resetting all bits to +0+.
+
+  # :method: set_bits
+  #
+  # Returns the number of bits currently set to +1+.
+
   def_delegators :@bf, :m, :k, :bitmap, :include?, :clear, :set_bits
 
+  # Returns the configured filter width.
   alias size m
+  # Returns the number of hash functions used for each inserted key.
   alias hashes k
   alias key? include?
   alias [] include?
   alias n set_bits
 
+  # Returns +true+ when no bits are set.
+  #
+  # This is an exact check on the filter state, unlike +include?+, which is
+  # probabilistic for positive matches.
   def empty?
     set_bits.zero?
   end
 
-  # Adds the given key to the set and returns +self+.  Mimics the behavior of
-  # +Set#add+
+  # Adds +key+ to the filter and returns +self+.
+  #
+  # This mimics the behavior of Set#add and allows chaining with #<<.
   def add(key)
     @bf.add(key)
     self
   end
   alias << add
 
-  # Adds the given key to the set if the value is truthy.  Mimics the behavior of
-  # +Hash#[]=+
+  # Adds +key+ to the filter when +value+ is truthy.
+  #
+  # This makes BloomFit behave like a write-only membership hash: truthy values
+  # add the key, while +false+ and +nil+ are ignored.
   def []=(key, value)
     @bf.add(key) if value
   end
 
-  # Adds the given key to the set and returns +self+. If the key is already
-  # the in set, returns +nil+. Mimics the behavior of +Set#add?+
+  # Adds +key+ only if it does not already appear to be present.
+  #
+  # Returns +self+ when the key is added and +nil+ when +include?+ is already
+  # true. This mimics Set#add?.
+  #
+  # Because Bloom filters can return false positives, +add?+ may occasionally
+  # return +nil+ for a key that has not actually been inserted before.
   def add?(key)
     return nil if include?(key) # rubocop:disable Style/ReturnNilInPredicateMethodDefinition
     add(key)
   end
 
-  # Returns a string of the set bits in hex format
+  # Returns the bitmap as a hexadecimal string.
+  #
+  # This is useful for debugging, logging, or comparing filter state in a more
+  # compact form than +to_binary+.
   def to_hex
     length = ((size / 8.0).ceil * 8 / 4)
     bitmap.unpack1("H*")[0...length]
   end
 
-  # Returns a string of the set bits in binary format
+  # Returns the bitmap as a binary string of +0+ and +1+ characters.
+  #
+  # The output is truncated to the configured filter width, so it omits any
+  # trailing padding present in the native bitmap.
   def to_binary
     bitmap.unpack1("B*")[0...size]
   end
 
-  # Adds the set from another BloomFit filter or adds all the elements from an
-  # enumerable.  Mimics the behavior of +Set#merge+
+  # Merges another filter or collection of keys into this filter.
+  #
+  # When +other+ is a +BloomFit+, the merge is performed bitwise and both
+  # filters must have the same +size+ and +hashes+ values. When +other+
+  # behaves like a hash, only keys with truthy values are added. Any other
+  # enumerable is treated as a list of keys.
+  #
+  # This method mutates the receiver and mimics Set#merge.
   def merge(other)
     if other.is_a?(BloomFit)
       raise BloomFit::ConfigurationMismatch unless same_parameters?(other)
@@ -74,9 +161,13 @@ class BloomFit
     end
   end
 
-  # Computes the intersection of two Bloom filters. It requires that both
-  # filters have the same size; otherwise, +BloomFit::ConfigurationMismatch+
-  # is raised.
+  # Returns a new filter containing the bitwise intersection of two filters.
+  #
+  # Both filters must have the same +size+ and +hashes+ values or
+  # +BloomFit::ConfigurationMismatch+ is raised.
+  #
+  # Like all Bloom filter operations, membership checks on the result remain
+  # probabilistic and may still produce false positives.
   def &(other)
     raise BloomFit::ConfigurationMismatch unless same_parameters?(other)
     self.class.new(size:, hashes:).tap do |result|
@@ -85,9 +176,12 @@ class BloomFit
   end
   alias intersection &
 
-  # Computes the union of two Bloom filters. It requires that both filters
-  # have the same size; otherwise, +BloomFit::ConfigurationMismatch+ is
-  # raised.
+  # Returns a new filter containing the bitwise union of two filters.
+  #
+  # Both filters must have the same +size+ and +hashes+ values or
+  # +BloomFit::ConfigurationMismatch+ is raised.
+  #
+  # The receiver and +other+ are left unchanged.
   def |(other)
     raise BloomFit::ConfigurationMismatch unless same_parameters?(other)
     self.class.new(size:, hashes:).tap do |result|
@@ -96,6 +190,11 @@ class BloomFit
   end
   alias union |
 
+  # Returns a human-readable summary of the filter's current state.
+  #
+  # The report includes the configured width (+m+), the current number of set
+  # bits (+n+), the hash count (+k+), and the predicted false-positive rate
+  # based on the current fill level.
   def stats
     fpr = ((1.0 - Math.exp(-(k * n).to_f / m))**k) * 100
 
@@ -107,6 +206,9 @@ class BloomFit
     end
   end
 
+  # Rebuilds the filter from the serialized data returned by +marshal_dump+.
+  #
+  # This hook is used by Ruby's +Marshal+ support.
   def marshal_load(ary)
     size, hashes, bitmap = *ary
 
@@ -114,14 +216,20 @@ class BloomFit
     @bf.load(bitmap) if bitmap
   end
 
+  # Returns the data Ruby's +Marshal+ uses to serialize this filter.
   def marshal_dump
     [size, hashes, bitmap]
   end
 
+  # Loads a filter from a file previously written by +save+.
+  #
+  # The file is read using Ruby's +Marshal+ format, so it should only be used
+  # with trusted input.
   def self.load(filename)
     Marshal.load(File.open(filename, "r")) # rubocop:disable Security/MarshalLoad
   end
 
+  # Writes the filter to +filename+ using Ruby's +Marshal+ format.
   def save(filename)
     File.open(filename, "w") do |f|
       f << Marshal.dump(self)
@@ -130,8 +238,7 @@ class BloomFit
 
   protected
 
-  # Returns true if parameters of the +other+ filter are
-  # the same.
+  # Returns +true+ when +other+ has the same +size+ and +hashes+ values.
   def same_parameters?(other)
     bf.m == other.bf.m && bf.k == other.bf.k
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bloom_fit
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Ryan McGeary