multi_bit_field 0.0.1 → 0.0.2

data/README.markdown

@@ -25,12 +25,12 @@ Say you have daily, weekly and monthly counters:
  
 If this model is now sorted in ascending order, it'll sort first by day, then by week and then by month.  You could also compare counters with a paired "limit" field.
 
-The methods only require an integer attribute (any ORM will do.)  Here's how we'd set this up:
+These methods only require an integer attribute (any ORM will do.)  Here's how we'd set this up:
 
 ```ruby
   class User < ActiveRecord::Base
-    has_bit_field :counter, :daily => 0..4, :weekly => 5..9, :monthly => 10..14
-	has_bit_field :limit,   :daily => 0..4, :weekly => 5..9, :monthly => 10..14
+    has_bit_field :counter, :daily_count => 0..4, :weekly_count => 5..9, :monthly_count => 10..14
+	has_bit_field :limit,   :daily_limit => 0..4, :weekly_limit => 5..9, :monthly_limit => 10..14
   end
 ```
 
@@ -39,22 +39,66 @@ this provides the following methods:
 ```ruby
 person = Person.new :daily => 3, :weekly => 5, :monthly => 1
 person.daily 
--> 3
+=> 3
 person.counter
--> 3233
+=> 3233
 
 person = Person.new :counter => 3233
 person.monthly
--> 1
+=> 1
 person.weekly
--> 5
+=> 5
 person.monthly = 4
 person.counter
--> 3236
+=> 3236
+```
+
+We can inspsect what this bitstring looks like to converting it like so:
 
-\# to view the binary string, you can convert to base-2
+```ruby
 person.counter.to_s(2)
 -> 000110010100100
+
+```
+
+We also provide convenient methods for resetting and incrementing fields.  These methods require active-record and active-relation since they use the "update_attributes" and "update_all" methods.
+
+```ruby
+peron.reset(:counter, :daily)
+person.daily
+=> 0
+person.monthly
+=> 4
+
+person.increment(:counter, :daily)
+person.daily
+=> 1
+
+person.reset(:counter, :daily, :monthly)
+person.daily
+=> 0
+person.monthly
+=> 0
+```
+
+The same thing works with bulk assignment:
+
+```ruby
+[person1.daily, person2.daily]
+=> [15, 23]
+
+Person.reset :counter, :daily
+[person1.daily, person2.daily]
+=> [0, 0]
+
+Person.increment :counter, :daily
+=> [1, 1]
+```
+
+By the way, these methods all work with your chainable active-relation query methods!
+
+```ruby
+Person.where(:daily => 0).increment_bitfield(:counter, :daily)
 ```
 
 One limitation you should be aware of:
@@ -65,9 +109,7 @@ Since this technique pins the counters/limits to specific bits, you will need to
 
 I intend to add some more methods in the models for the following features:
 
-  * Add class and instance "bitfield reset" methods
-  	- This may make the plugin more dependent on an ORM/database
-  * Possibly replace current String-converstion solution with bit-functions
+  * Possibly replace current String-converstion solution with integer bit-functions
   * Add comparison methods between bitfields on the same column, or between multiple columns
   * Investigate if there's a use for right/left bit shifting
 

data/lib/multi_bit_field/version.rb

@@ -1,3 +1,3 @@
 module MultiBitField
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/lib/multi_bit_field.rb

@@ -1,21 +1,28 @@
+# MultiBitField creates convenience methods for using
+# multiple filum bit-fields with ActiveRecord.
+# Author:: Aaron Spiegel
+# Copyright:: Copyright (c) 2012 Aaron Spiegel
+# License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
 require 'multi_bit_field/core_ext'
 
 module MultiBitField  
   module ClassMethods
-    # MultiBitField creates convenience methods for using
-    # multiple filum bit-fields with ActiveRecord.
-    # Author:: Aaron Spiegel
-    # Copyright:: Copyright (c) 2012 Aaron Spiegel
-    # License:: MIT License (http://www.opensource.org/licenses/mit-license.php)
+    # alias :reset_bitfields :reset_bitfield
+    
+    # Assign bitfields to a column
     #
     # +has_bit_field :column, :fields
     #
+    # @example
     #   class User < ActiveRecord::Base
     #     has_bit_field :counter, :daily => 0..4, :weekly => 5..9, :monthly => 10..14
     #   end
     #
+    # @param [ Symbol ] column  Integer attribute to store bitfields
+    # @param [ Hash ]   fields  Specify the bitfield name, and the columns
+    #                           of the bitstring assigned to it
     def has_bit_field column, fields
-      set_bitfields! column, fields
+      bitfield_setup! column, fields
       
       fields.each do |field_name, filum|
         class_eval <<-EVAL
@@ -29,24 +36,134 @@ module MultiBitField
         EVAL
       end
     end
-
-    def bitfields
-      @@bitfields
+    
+    # Returns the size of the bitfield in number of bits
+    #
+    # +bitfield_size :column
+    #
+    # @example
+    #  user.bitfield_size :counter
+    #
+    # @param [ Symbol ] column_name  column name that stores the bitfield integer
+    #
+    def bitfield_size column_name
+      @@bitfields[column_name].values.sum.count
+    end
+    
+    # Returns a "reset mask" for a list of fields
+    #
+    # +reset_mask_for :fields
+    #
+    # @example
+    #  user.reset_mask_for :field
+    #
+    # @param [ Symbol ] column     name of the column these fields are in
+    # @param [ Symbol ] field(s) name of the field(s) for the mask
+    def reset_mask_for column_name, *fields
+      fields.inject("1" * bitfield_size(column_name)) do |mask, field_name|
+        column = @@bitfields[column_name]
+        raise ArgumentError, "Unknown column for bitfield: #{column_name}" if column.nil?
+        raise ArugmentError, "Unknown field: #{field_name} for column #{column_name}" if column[field_name].nil?
+        range = column[field_name]
+        mask[range] = "0" * range.count
+        mask
+      end.to_i(2)
     end
     
+    # Returns an "increment mask" for a list of fields
+    #
+    # +increment_mask_for :fields
+    #
+    # @example
+    #  user.increment_mask_for :field
+    #
+    # @param [ Symbol ] column     name of the column these fields are in
+    # @param [ Symbol ] field(s) name of the field(s) for the mask
+    def increment_mask_for column_name, *fields
+      fields.inject("0" * bitfield_size(column_name)) do |mask, field_name|
+        column = @@bitfields[column_name]
+        raise ArgumentError, "Unknown column for bitfield: #{column_name}" if column.nil?
+        raise ArugmentError, "Unknown field: #{field_name} for column #{column_name}" if column[field_name].nil?
+        range = column[field_name]
+        mask[range.last] = "1"
+        mask
+      end.to_i(2)
+    end
+    
+    # Sets one or more bitfields to 0 within a column
+    #
+    # +reset_bitfield :column, :fields
+    #
+    # @example
+    #   User.reset_bitfield :column, :daily, :monthly
+    #
+    # @param [ Symbol ] column     name of the column these fields are in
+    # @param [ Symbol ] field(s)   name of the field(s) to reset
+    def reset_bitfields column_name, *fields
+      mask = reset_mask_for column_name, *fields
+      update_all "#{column_name} = #{column_name} & #{mask}"
+    end
+    alias :reset_bitfield :reset_bitfields
+        
+    # Increases one or more bitfields by 1 value
+    #
+    # +increment_bitfield :column, :fields
+    #
+    # @example
+    #   user.increment_bitfield :column, :daily, :monthly
+    #
+    # @param [ Symbol ] column     name of the column these fields are in
+    # @param [ Symbol ] field(s)   name of the field(s) to reset
+    def increment_bitfields column_name, *fields
+      mask = increment_mask_for column_name, *fields
+      update_all "#{column_name} = #{column_name} + #{mask}"
+    end
+    alias :increment_bitfield :increment_bitfields
+
     private
     
-    def set_bitfields! column, fields
+    def bitfield_setup! column, fields
       if defined?(@@bitfields)
-        # set the 
-        @@bitfields[column] = fields.values.sum.count
+        @@bitfields[column] = fields
       else
-        @@bitfields = { column => fields.values.sum.count }
+        @@bitfields = { column => fields }
       end
     end
   end  
   
   module InstanceMethods
+    # Sets one or more bitfields to 0 within a column
+    #
+    # +reset_bitfield :column, :fields
+    #
+    # @example
+    #   user.reset_bitfield :column, :daily, :monthly
+    #
+    # @param [ Symbol ] column     name of the column these fields are in
+    # @param [ Symbol ] field(s)   name of the field(s) to reset
+    def reset_bitfields column_name, *fields
+      mask = self.class.reset_mask_for column_name, *fields
+      self[column_name] = self[column_name] & mask
+      save
+    end
+    alias :reset_bitfield :reset_bitfields
+    
+    # Increases one or more bitfields by 1 value
+    #
+    # +increment_bitfield :column, :fields
+    #
+    # @example
+    #   user.increment_bitfield :column, :daily, :monthly
+    #
+    # @param [ Symbol ] column     name of the column these fields are in
+    # @param [ Symbol ] field(s)   name of the field(s) to reset
+    def increment_bitfields column_name, *fields
+      mask = self.class.increment_mask_for column_name, *fields
+      self[column_name] = self[column_name] += mask
+      save
+    end
+    alias :increment_bitfield :increment_bitfields
+    
     private
     
     # self[column_name].to_s(2)                -- converts integer to binary string
@@ -54,14 +171,14 @@ module MultiBitField
     # self[column_name].to_s(2)[filum].to_i(2) -- converts it back to an integer
     def get_bits_for(column, filum)
       return nil if self[column].nil?
-      length     = self.class.bitfields[column]
+      length     = self.class.bitfield_size column
       bit_string = self[column].to_i.to_s(2)
       
       sprintf("%0#{length}d", bit_string)[filum].to_i(2)
     end
 
     def set_bits_for(column, filum, value)
-      length     = self.class.bitfields[column]
+      length     = self.class.bitfield_size column
       bit_string = self[column].to_i.to_s(2)
       temp_field = sprintf("%0#{length}d", bit_string)
 

data/test/dummy/log/development.log

@@ -40,3 +40,19 @@ Migrating to CreatePeople (20120225171132)
    (0.4ms)  select sqlite_version(*)
    (0.1ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" 
    (0.0ms)  PRAGMA index_list("people")
+   (0.1ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" 
+   (0.3ms)  select sqlite_version(*)
+   (1.9ms)  CREATE TABLE "people" ("id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "name" varchar(255), "birthday" integer, "created_at" datetime NOT NULL, "updated_at" datetime NOT NULL) 
+   (1.9ms)  CREATE TABLE "schema_migrations" ("version" varchar(255) NOT NULL) 
+   (0.0ms)  PRAGMA index_list("schema_migrations")
+   (1.7ms)  CREATE UNIQUE INDEX "unique_schema_migrations" ON "schema_migrations" ("version")
+   (0.1ms)  SELECT version FROM "schema_migrations"
+   (1.6ms)  INSERT INTO "schema_migrations" (version) VALUES ('20120225171132')
+   (0.1ms)  SELECT "schema_migrations"."version" FROM "schema_migrations" 
+   (0.3ms)  select sqlite_version(*)
+   (4.1ms)  CREATE TABLE "people" ("id" INTEGER PRIMARY KEY AUTOINCREMENT NOT NULL, "name" varchar(255), "birthday" integer, "created_at" datetime NOT NULL, "updated_at" datetime NOT NULL) 
+   (2.0ms)  CREATE TABLE "schema_migrations" ("version" varchar(255) NOT NULL) 
+   (0.2ms)  PRAGMA index_list("schema_migrations")
+   (2.7ms)  CREATE UNIQUE INDEX "unique_schema_migrations" ON "schema_migrations" ("version")
+   (0.2ms)  SELECT version FROM "schema_migrations"
+   (9.2ms)  INSERT INTO "schema_migrations" (version) VALUES ('20120225171132')