ingramj-bitarray 0.4.2 → 0.5.0

data/README

@@ -9,11 +9,17 @@ Example usage:
     bm[5] = 1
     bm.toggle_all_bits
     puts bm
+    
+    bm = BitArray.new("10010110")
+    bm.toggle_bit 3
+    bm.clear_bit 0
 
 
 The test/ directory has a unit test file. It also has a benchmark utility for
 comparison with Peter Cooper's pure Ruby BitField class.
 
+The examples/ directory has bloom filter dictionary-lookup demonstration.
+
 This library has been compiled and tested on:
     
     ruby 1.9.1p129 (2009-05-12 revision 23412) [i686-linux]  (Ubuntu from src)

data/TODO

@@ -1,7 +1,7 @@
 * Comment code. I'd like for it to be useful as a tutorial for extension
   writing, especially with regards to implementing new types.
-* Implement some more methods, like in-place enumerator methods (map!,
-  reverse!, etc).
+* BitArray intersection and union ( & and | )
+* In-place enumerator methods (map!, reverse!, etc.)
 * Maybe allow resizing.
 * Write more tests
 

data/VERSION

@@ -1 +1 @@
-0.4.2
+0.5.0

data/bitarray.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{bitarray}
-  s.version = "0.4.2"
+  s.version = "0.5.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["James E. Ingram"]
-  s.date = %q{2009-05-30}
+  s.date = %q{2009-06-01}
   s.description = %q{A bit array class for Ruby, implemented as a C extension. Includes methods for setting and clearing individual bits, and all bits at once. Also has the standard array access methods, [] and []=, and it mixes in Enumerable.}
   s.email = %q{ingramj@gmail.com}
   s.extensions = ["ext/extconf.rb"]
@@ -22,6 +22,8 @@ Gem::Specification.new do |s|
      "TODO",
      "VERSION",
      "bitarray.gemspec",
+     "examples/bloomfilter.rb",
+     "examples/boolnet.rb",
      "ext/bitarray.c",
      "ext/extconf.rb",
      "test/bitfield.rb",
@@ -38,7 +40,9 @@ Gem::Specification.new do |s|
   s.test_files = [
     "test/bitfield.rb",
      "test/test.rb",
-     "test/bm.rb"
+     "test/bm.rb",
+     "examples/bloomfilter.rb",
+     "examples/boolnet.rb"
   ]
 
   if s.respond_to? :specification_version then

data/examples/bloomfilter.rb

@@ -0,0 +1,83 @@
+#!/usr/bin/env ruby
+require 'digest/sha1'
+require 'bitarray'
+
+# This bloom filter was written as a demonstration of the BitArray class.
+# Therefore, it was written with an eye towards simplicity rather than
+# efficiency or optimization.
+#
+# For information about picking parameters for a Bloom Filter, take a look at
+# the Wikipedia page.
+#
+# http://en.wikipedia.org/wiki/Bloom_filter
+#
+class BloomFilter
+  def initialize(m = 1000000, k = 3)
+    @size = m
+    @hashes = k < 3 ? 3 : k
+    @ba = BitArray.new(@size)
+  end
+
+  def add(input)
+    hash(input).each {|i|
+      @ba.set_bit i
+    }
+  end
+
+  def include?(input)
+    hash(input).each {|i|
+      return false if @ba[i] == 0
+    }
+    return true
+  end
+
+  private
+  # Return an array of @hashes indices to set. 
+  #
+  # We generate as many hash values as needed by using the technique described
+  # by Kirsch and Mitzenmacher[1].
+  #
+  # [1] http://www.eecs.harvard.edu/~kirsch/pubs/bbbf/esa06.pdf
+  def hash(input)
+    h1 = input.hash.abs % @size
+    h2 = Digest::SHA1.hexdigest(input).to_i(16) % @size
+
+    ha = [h1, h2]
+    1.upto(@hashes - 2) do |i|
+      ha << (h1 + i * h2) % @size
+    end
+    return ha
+  end
+end
+
+
+# As a demonstration, load the contents of the dictionary file and let the user
+# look up words. 
+#
+# Using the calculator at http://hur.st/bloomfilter, the optimum number of bits
+# for my system's dictionary file (98569 words), with a false positive rate of
+# 0.001, is 1,417,185 bits (about 173 Kb), and 10 hash functions.
+#
+# Loading the dictionary takes about 4 seconds on my system.
+if __FILE__ == $0
+  print "Loading dictionary..."
+  bf = BloomFilter.new(1417185, 10)
+  File.open('/usr/share/dict/words') {|f|
+    f.each_line {|w| bf.add(w.chomp)}
+  }
+  print "done\n"
+
+  puts "Enter words to look up, ctrl-d to quit."
+  done = false
+  while (!done)
+    print "Word: "
+    s = gets
+    if s 
+      puts "In dictionary: #{bf.include? s.chomp}"
+    else
+      done = true
+    end
+  end
+  puts
+end
+

data/examples/boolnet.rb

@@ -0,0 +1,70 @@
+#!/usr/bin/env ruby
+
+require 'bitarray'
+
+# A Random Boolean Network. Each bit of the network has two "neighbor" bits and
+# an operation, all chosen at random. At each step, every bit is set to a new
+# value by applying its operation to its neighbors.
+#
+# All such networks eventually fall into a cyclic or fixed-point attractor.
+#
+# See http://en.wikipedia.org/wiki/Boolean_network for more information.
+class BoolNet
+  attr_reader :state, :size
+  def initialize(size = 80)
+    @size = size
+    # We use two arrays; one for the current state, and one holding infomation
+    # used to update the state.
+    @state = random_network(size)
+    @update = random_update(size)
+  end
+
+  def step
+    old_state = @state.clone
+    @update.each_with_index { |u,i|
+      case u[0]
+      when :and
+        @state[i] = old_state[u[1]] & old_state[u[2]]
+      when :or
+        @state[i] = old_state[u[1]] | old_state[u[2]]
+      when :xor
+        @state[i] = old_state[u[1]] ^ old_state[u[2]]
+      end
+    }
+    return @state
+  end
+  
+  def run(steps = 23)
+    puts state
+    steps.times {
+      puts step
+    }
+  end
+
+  private
+  def random_network(size)
+    ba = BitArray.new(size)
+    0.upto(size - 1) {|b|
+      if (rand(2) == 1)
+        ba.set_bit b
+      end
+    }
+    return ba
+  end
+
+  def random_update(size)
+    # The update array is an array of [op, n1, n2] elements. op is the symbol
+    # specifying which operation to use. n1 and n2 are indices of our neighbors
+    # in the state array.
+    update = Array.new(size)
+    0.upto(size - 1) {|u|
+      update[u] = [[:and, :or, :xor][rand(3)], rand(size), rand(size)]
+    }
+    return update
+  end
+end
+
+if __FILE__ == $0
+  BoolNet.new.run
+end
+

data/ext/bitarray.c

@@ -172,33 +172,150 @@ rb_bitarray_alloc(VALUE klass)
 }
 
 
-/* call-seq:
- *      BitArray.new(size)
- *
- * Return a new BitArray or the specified size.
- */
+/* Create a new BitArray from a string. Called by rb_bitarray_initialize. */
 static VALUE
-rb_bitarray_initialize(VALUE self, VALUE size)
+rb_bitarray_from_string(VALUE self, VALUE arg)
 {
     struct bit_array *ba;
     Data_Get_Struct(self, struct bit_array, ba);
 
-    long bits = NUM2LONG(size);
-    if (bits <= 0) {
+    /* Extract a C-string from arg. */
+    long str_len = RSTRING_LEN(arg) + 1;
+    char cstr[str_len];
+    strncpy(cstr, StringValueCStr(arg), str_len);
+
+    /* If the string doesn't begin with a '1' or '0', return an empty
+     * BitArray.
+     */
+    if (cstr[0] != '0' && cstr[0] != '1') {
         ba->bits = 0;
         ba->array_size = 0;
         return self;
     }
-    long array_size = ((bits - 1) / UINT_BITS) + 1;
 
-    ba->bits = bits;
-    ba->array_size = array_size;
-    ba->array = ruby_xcalloc(array_size, UINT_BYTES);
+    /* Otherwise, loop through the string and truncate it at the first invalid
+     * character.
+     */
+    long i;
+    for (i = 0; i < str_len; i++) {
+        if (cstr[i] != '0' && cstr[i] != '1') {
+            cstr[i] = '\0';
+            break;
+        }
+    }
+
+    /* Setup the BitArray structure. */
+    ba->bits = strlen(cstr);
+    ba->array_size = ((ba->bits - 1) / UINT_BITS) + 1;
+    ba->array = ruby_xmalloc(ba->array_size * UINT_BYTES);
+
+    /* Initialize the bit array with the string. */
+    for (i = 0; i < ba->bits; i++) {
+        if (cstr[i] == '0') {
+            clear_bit(ba, i);
+        } else {
+            set_bit(ba, i);
+        }
+    }
+
+    return self;
+}
+
+
+/* Create a new BitArray from an Array. Called by rb_bitarray_initialize */
+static VALUE
+rb_bitarray_from_array(VALUE self, VALUE arg)
+{
+    struct bit_array *ba;
+    Data_Get_Struct(self, struct bit_array, ba);
+
+    ba->bits = RARRAY_LEN(arg);
+    ba->array_size = ((ba->bits - 1) / UINT_BITS) + 1;
+    ba->array = ruby_xmalloc(ba->array_size * UINT_BYTES);
+
+    VALUE e;
+    long i;
+    for (i = 0; i < ba->bits; i++) {
+        e = rb_ary_entry(arg, i);
+
+        switch (TYPE(e)) {
+            case T_FIXNUM:      /* fixnums and bignums treated the same. */
+            case T_BIGNUM:
+                NUM2LONG(e) == 0l ? clear_bit(ba, i) : set_bit(ba, i);
+                break;
+            case T_FALSE:       /* false and nil treated the same. */
+            case T_NIL:
+                clear_bit(ba, i);
+                break;
+            default:
+                set_bit(ba, i);
+        }
+    }
 
     return self;
 }
 
 
+/* call-seq:
+ *      BitArray.new(size)
+ *      BitArray.new(string)
+ *      BitArray.new(array)
+ *
+ * When called with a size, creates a new BitArray of the specified size, with
+ * all bits cleared. When called with a string or an array, creates a new
+ * BitArray from the argument.
+ *
+ * If a string is given, it should consist of ones and zeroes. If there are
+ * any other characters in the string, the first invalid character and all
+ * following characters will be ignored.
+ *
+ *   b = BitArray.new("10101010")       => 10101010
+ *   b = BitArray.new("1010abcd")       => 1010
+ *   b = BitArray.new("abcd")           => 
+ *
+ * If an array is given, the BitArray is initialized from its elements using
+ * the following rules:
+ *
+ * 1. 0, false, or nil  => 0
+ * 2. anything else     => 1
+ *
+ * Note that the 0 is a number, not a string. "Anything else" means strings,
+ * symbols, non-zero numbers, subarrays, etc.
+ *
+ *   b = BitArray.new([0,0,0,1,1,0])            => 000110
+ *   b = BitArray.new([false, true, false])     => 010
+ *   b = BitArray.new([:a, :b, :c, [:d, :e]])   => 1111
+ */
+static VALUE
+rb_bitarray_initialize(VALUE self, VALUE arg)
+{
+    if (TYPE(arg) == T_FIXNUM || TYPE(arg) == T_BIGNUM) {
+        struct bit_array *ba;
+        Data_Get_Struct(self, struct bit_array, ba);
+
+        long bits = NUM2LONG(arg);
+        if (bits <= 0) {
+            ba->bits = 0;
+            ba->array_size = 0;
+            return self;
+        }
+        
+        ba->bits = bits;
+        ba->array_size = ((bits - 1) / UINT_BITS) + 1;
+        ba->array = ruby_xcalloc(ba->array_size, UINT_BYTES);
+
+        return self;
+
+    } else if (TYPE(arg) == T_STRING) {
+        return rb_bitarray_from_string(self, arg);
+    } else if (TYPE(arg) == T_ARRAY) { 
+        return rb_bitarray_from_array(self, arg);
+    } else {
+        rb_raise(rb_eArgError, "must be size, string, or array");
+    }
+}
+
+
 /* call-seq:
  *      bitarray.clone          -> a_bitarray
  *      bitarray.dup            -> a_bitarray

data/test/bm.rb

@@ -6,6 +6,10 @@ Benchmark.bm(28) { |bm|
   puts "---------------------------- Object instantiation (10,000 iterations)"
   bm.report("BitField initialize") { 10000.times { BitField.new(256) } }
   bm.report("BitArray initialize") { 10000.times { BitArray.new(256) } }
+  s = "0"*256
+  bm.report("BitArray init from string") { 10000.times { BitArray.new(s) } }
+  a = [0]*256
+  bm.report("BitArray init from array")  { 10000.times { BitArray.new(a) } }
 
   bf = BitField.new(256)
   ba = BitArray.new(256)

data/test/test.rb

@@ -1,4 +1,5 @@
-# Peter Cooper's BitField test file, modified for BitArray.
+# BitArray Unit Tests.
+# Originally modified from Peter Cooper's BitField test file.
 # http://snippets.dzone.com/posts/show/4234
 require "test/unit"
 require "bitarray"
@@ -140,5 +141,24 @@ class TestLibraryFileName < Test::Unit::TestCase
     ba[5] = 1
     assert_equal [0,1,0,0,0,1,0,0,0,0,0,0,0,0,0,0], ba.to_a
   end
+
+  def test_init_from_str
+    ba = BitArray.new("00011")
+    assert_equal "00011", ba.to_s
+    ba = BitArray.new("00011abcd")
+    assert_equal "00011", ba.to_s
+    ba = BitArray.new("abcd0101")
+    assert_equal "", ba.to_s
+  end
+
+
+  def test_init_from_array
+    ba = BitArray.new([0,1,1,1,0])
+    assert_equal "01110", ba.to_s
+    ba = BitArray.new([true, true, false, false, true])
+    assert_equal "11001", ba.to_s
+    ba = BitArray.new([nil, nil, :a, nil, [:b, :c]])
+    assert_equal "00101", ba.to_s
+  end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: ingramj-bitarray
 version: !ruby/object:Gem::Version 
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors: 
 - James E. Ingram
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-05-30 00:00:00 -07:00
+date: 2009-06-01 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -30,6 +30,8 @@ files:
 - TODO
 - VERSION
 - bitarray.gemspec
+- examples/bloomfilter.rb
+- examples/boolnet.rb
 - ext/bitarray.c
 - ext/extconf.rb
 - test/bitfield.rb
@@ -69,3 +71,5 @@ test_files:
 - test/bitfield.rb
 - test/test.rb
 - test/bm.rb
+- examples/bloomfilter.rb
+- examples/boolnet.rb