bit_magic 0.1.1

data/lib/bit_magic/bit_field.rb

@@ -0,0 +1,103 @@
+require_relative "./error"
+
+module BitMagic
+
+  # Helper class to encapsulate bit field values and read/write operations
+  # Note that indices are based off ruby bit reading, so least-significant bits
+  # are to the right and negative numbers are handled as two's complement.
+  #
+  # @attr [Integer] value the current integer value that contains the bit fields
+  class BitField
+    attr_reader :value
+    
+    # Initialize the BitField with an optional value. Default is 0
+    #
+    # @param [Integer] value the integer that contains the bit fields
+    def initialize(value = 0)
+      if value.is_a?(Integer)
+        @value = value
+      else
+        raise InputError.new("BitField#new expects an integer value, #{value.inspect} is not an integer")
+      end
+    end
+    
+    # Read the specified bit indices into a hash with bit index as key
+    #
+    # @param [Integer] bits one or more bit indices to read.
+    #
+    # @example Read a list of bits into a hash
+    #   bit_field = BitField.new(5)
+    #   bit_field.read_bits(0, 1, 2)
+    #   #=> {0=>1, 1=>0, 2=>1}
+    #   # because 5 is 101 in binary
+    # 
+    # @return [Hash] a hash with the bit index as key and bit (1 or 0) as value
+    def read_bits(*args)
+      {}.tap do |m|
+        args.each { |bit| m[bit] = @value[bit] }
+      end
+    end
+    
+    # Read the specified bit indices as a group, in the order given
+    #
+    # @param [Integer] bits one or more bit indices to read. Order matters!
+    # 
+    # @example Read bits or a list of bits into an integer
+    #   bit_field = BitField.new(101) # 1100101 in binary, lsb on the right
+    #   bit_field.read_field(0, 1, 2) #=> 5 # or 101
+    #   bit_field.read_field(0) #= 1
+    #   bit_field.read_field( (2..6).to_a ) #=> 25 # or 11001
+    #
+    # @return [Integer] the value of the bits read together into an integer
+    def read_field(*args)
+      m = 0
+      args.flatten.each_with_index do |bit, i|
+        if bit.is_a?(Integer)
+          m |= ((@value[bit] || 0) << i)
+        end
+      end
+      m
+    end
+    
+    alias :[] :read_field
+    
+    # Write to the specified bits, changing the internal @value to the new value
+    #
+    # @param [Hash] bit_values a hash with the key being a bit index and value
+    #   being the value (must be 1, 0, true or false)
+    #
+    # @example Write new bit withs with their corresponding values
+    #   bit_field = BitField.new
+    #   bit_field.write_bits(0 => true) #=> 1
+    #   bit_field.write_bits(1 => true, 4 => true) #=> 19 # 10011
+    #   bit_field.write_bits(0 => false, 4 => false) #=> 2 # 10
+    #
+    # @return [Integer] the value after writing the new bits their new values
+    def write_bits(bit_values = {})
+      bit_values.each_pair do |index, val|
+        
+        if !index.is_a?(Integer)
+          raise InputError.new("BitField#write can only access bits by their index, #{index.inspect} is not a valid index")
+        end
+        
+        if index < 0
+          raise InputError.new("BitField#write can not write to negative indices")
+        end
+        
+        if !(val === true) and !(val === false) and !(val === 1) and !(val === 0)
+          raise InputError.new("BitField#write must have a boolean value, #{val.inspect} is not a boolean")
+        end
+        
+        if val === true or val === 1
+          @value |= (1 << index)
+        else
+          @value &= ~(1 << index)
+        end
+      
+      end
+      
+      @value
+    end
+    
+  end
+end

data/lib/bit_magic/bits.rb

@@ -0,0 +1,285 @@
+require_relative './bit_field'
+
+module BitMagic
+  # This is a wrapper class for objects that want bitfield functionality.
+  # It implements bit field read, write and attribute field read and updating.
+  #
+  # This is usually used alongside Magician (an adapter helper class).
+  #
+  # If you're using this class directly, you can subclass it and set DEFAULT_OPTIONS
+  # on your subclass to change default options.
+  #
+  # @example Subclass this class to change defaults
+  #   # (do not set attribute_name to 'object_id' in real code, it's an example)
+  #   class MyBits < BitMagic::Bits
+  #     DEFAULT_OPTIONS = BitMagic::Bits::DEFAULT_OPTIONS.merge({default: 99, :attribute_name => 'object_id'})
+  #   end
+  #   # and now, if you initialize a new MyBits...
+  #   MyBits.new(Object.new).options
+  #   # will have default: 99 (instead of 0), and attribute_name: 'object_id'
+  #   
+  #
+  # @attr_reader instance the instance we're doing operations for
+  # @attr_reader [Hash] field_list a hash of field name => field bits key-pairs
+  # @attr_reader [Hash] options options for this instance
+  class Bits
+    # This casts a given input value into a boolean.
+    BOOLEAN_CASTER = lambda {|i| !(i == false or i == 0) }
+    
+    # Default options
+    #
+    # The bool_caster is expected to be overwritten depending on your use-case.
+    # eg, form fields can send '0' or 'f' to mean false.
+    DEFAULT_OPTIONS = {
+      :attribute_name => 'flags',
+      :default => 0,
+      :updater => Proc.new {|bits, new_value| bits.instance.send(:"#{bits.attribute_name}=", new_value) },
+      :bool_caster => BOOLEAN_CASTER
+      }.freeze
+    
+    attr_reader :instance, :field_list, :options
+    
+    # This class wraps around any arbitrary objects (instance) that respond to
+    # certain methods (a getter and setter for the flag field).
+    #
+    # @param [Object] instance some arbitrary object with bit_magic interest
+    # @param [BitMagic::Adapters::Magician, Hash] magician_or_field_list either
+    #   an instance of Magician (usually from an adapter) or a Hash with
+    #   field name => bit/field bits array as key-pair.
+    # @param [Hash] options additional options to override defaults
+    # @option options [String] :attribute_name the name for the attribute, will
+    #   be used as the getter and setter (by appending '=') on the instance object
+    #   default: 'flags'
+    # @option options [Integer] :default the default value. default: 0
+    # @option options [Proc] :updater a callable (Proc/lambda/Method) used to
+    #   update the bit field attribute after it has been changed.
+    #   default: calls "#{attribute_name}=(newValue)" on instance
+    # @option options [Proc] :bool_caster a callable (Proc/lambda/Method) used to
+    #   cast some input value into a boolean (used with #write)
+    #   default: cast false or 0 (integer) as false, everything else as true
+    #
+    # @example Initialize a Bits object
+    #   Example = Struct.new('Example', :flags)
+    #   # above, Example is a class with the 'flags' instance method
+    #   # below, we initialize an instance with flags set to 0
+    #   bits = BitMagic::Bits.new(Example.new(0), {:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4})
+    #
+    # @return [BitMagic::Bits] a Bits object
+    def initialize(instance, magician_or_field_list = {}, options = {})
+      if defined?(BitMagic::Adapters::Magician) and magician_or_field_list.is_a?(BitMagic::Adapters::Magician)
+        @magician = magician_or_field_list
+        @field_list = @magician.field_list
+        @options = @magician.action_options.merge(options)
+      else
+        @field_list = magician_or_field_list
+        @options = self.class::DEFAULT_OPTIONS.merge(options)
+      end
+      @instance = instance
+    end
+    
+    # Get the attribute name option (a method on the instance that returns the
+    # current bit field value).
+    #
+    # In the future, attribute name may be a Proc. This class could also possibly
+    # be subclassed and this method overwritten if advanced lookup is necessary.
+    #
+    # @return [String] name of the method we will use to get the bit field value
+    def attribute_name
+      @options[:attribute_name]
+    end
+    
+    # Get the current value from the instance. It should return an integer if the
+    # value exists, otherwise anything falsy will be set to the default value
+    # given during initialization.
+    # 
+    # @return [Integer] the current value for the bit field
+    def value
+      value = @instance.send(attribute_name)
+      value ||= @options[:default]
+      value
+    end
+    
+    # Update the bit field value on the instance with a new value using the updater
+    # Proc given during initialization.
+    #
+    # @param [Integer] new_value the new value for the bit field
+    #
+    # @return returns the value returned by the updater, usually is the new_value
+    def update(new_value)
+      if @options[:updater].respond_to?(:call)
+        @options[:updater].call(self, new_value)
+      end
+    end
+    
+    # Check whether all the given field name or bits are enabled (true or 1)
+    # On fields with more than one bit, will return true if any of the bits are
+    # enabled (value > 0)
+    # 
+    # @param [Symbol, Integer] fields one or more field names or bit indices
+    #
+    # @example Check fields to see if they are enabled
+    #   # The struct is just an example, normally you would define a new class
+    #   Example = Struct.new('Example', :flags)
+    #   exo = Example.new(0)
+    #   bits = Bits.new(exo, {:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4})
+    #   # we initialized flags to 0, so nothing is enabled
+    #   bits.enabled?(:is_odd) #=> false
+    #   bits.enabled?(:amount, :is_cool) #=> false
+    #   bits.enabled?(10, 5, :is_odd) #=> false
+    #
+    #   # We now change flags on our instance object
+    #   exo.flags = 5 # is_odd = 1, amount = 2, is_cool = 0
+    #   bits.enabled?(:is_odd) #=> true
+    #   bits.enabled?(:amount, :is_cool) #=> false
+    #   bits.enabled?(:amount, :is_odd) #=> true
+    #   bits.enabled?(:is_cool) #=> false
+    #   
+    #
+    # @return [Boolean] true if ALL the given field bits are enabled
+    def enabled?(*fields)
+      memo = true
+      field = self.field
+      
+      fields.flatten.each do |name|
+        break unless memo
+        memo &&= (read(name, field) >= 1)
+      end
+      
+      memo
+    end
+    
+    # Check whether all the given field names or bits are disabled (false or 0)
+    # On fields with more than one bit, will return true only if the value of the
+    # field is 0 (no bits set).
+    # 
+    # @param [Symbol, Integer] fields one or more field names or bit indices
+    #
+    # @example Check fields to see if they are disabled
+    #   # The struct is just an example, normally you would define a new class
+    #   Example = Struct.new('Example', :flags)
+    #   exo = Example.new(0)
+    #   bits = Bits.new(exo, {:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4})
+    #   # we initialized flags to 0, so everything is disabled
+    #   bits.disabled?(:is_odd) #=> true
+    #   bits.disabled?(:amount, :is_cool) #=> true
+    #   bits.disabled?(10, 5, :is_odd) #=> true
+    #
+    #   # We now change flags on our instance object
+    #   exo.flags = 5 # is_odd = 1, amount = 2, is_cool = 0
+    #   bits.disabled?(:is_odd) #=> false
+    #   bits.disabled?(:amount, :is_cool) #=> false
+    #   bits.disabled?(:amount, :is_odd) #=> false
+    #   bits.disabled?(:is_cool) #=> true
+    #
+    # @return [Boolean] true if ALL the given field bits are disabled (all bits
+    #   are not set or false)
+    def disabled?(*fields)
+      memo = true
+      field = self.field
+      
+      fields.flatten.each do |name|
+        break unless memo
+        memo &&= (read(name, field) == 0)
+      end
+      
+      memo
+    end
+    
+    # Get a BitField instance for the current value.
+    #
+    # Note: Value changes are NOT tracked and updated into the instance, so call
+    # this method directly as needed.
+    #
+    # @return [BitMagic::BitField] a BitField object with the current value
+    def field
+      BitField.new(self.value)
+    end
+    
+    # Read a field or bit from its bit index or name
+    #
+    # @param [Symbol, Integer] name either the name of the bit (a key in field_list)
+    #   or a integer bit position
+    # @param [BitField optional] field a specific BitField to read from.
+    #   default: return value of #field
+    #
+    # @example Read bit values
+    #   # The struct is just an example, normally you would define a new class
+    #   Example = Struct.new('Example', :flags)
+    #   exo = Example.new(9)
+    #   bits = Bits.new(exo, {:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4})
+    #   bits.read(:is_odd) #=> 1
+    #   bits.read(:amount) #=> 4
+    #   bits.read(:is_cool) #=> 0
+    #   bits.read(:amount, BitField.new(78)) #=> 7
+    #   # Bonus: aliased as []
+    #   bits[:is_odd] #=> 1
+    #
+    # @return [Integer] a value of the bit (0 or 1) or bits (number from 0 to
+    #   (2**bit_length) - 1) or nil if the field name is not in the list
+    def read(name, field = nil)
+      field ||= self.field
+      
+      if name.is_a?(Integer)
+        field.read_field(name)
+      elsif bits = @field_list[name]
+        field.read_field(bits)
+      end
+    end
+    
+    alias :[] :read
+    
+    # Write a field or bit from its field name or index
+    #
+    # Note: only the total bits of the field is used from the given value, so
+    # any additional bits are ignored. eg: writing a field with one bit as value
+    # of 4 will set the bit to 0, writing 5 sets it to 1.
+    #
+    # @param [Symbol, Integer, Array<Integer>] name a field name, or bit position,
+    #   or array of bit positions
+    # @param [Integer, Array<Integer>] target_value the target value for the field
+    #   (note: technically, this can be anything that responds to :[](index), but
+    #   usage in that type of context is discouraged without adapter support)
+    #
+    # @example Write values to bit fields
+    #   # The struct is just an example, normally you would define a new class
+    #   Example = Struct.new('Example', :flags)
+    #   exo = Example.new(0)
+    #   bits = Bits.new(exo, {:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4})
+    #   bits.write(:is_odd, 1) #=> 1
+    #   bits.write(:amount, 5) #=> 11
+    #   exo.flags #=> 11
+    #   # Bonus, aliased as :[]=, but note in this mode, the return value is same as given value
+    #   bits[:is_cool] = 1 #=> 1
+    #   exo.flags #=> 27
+    # 
+    # @return the return value of the updater Proc, usually is equal to the final
+    #   master value (with all the bits) after writing this bit
+    def write(name, target_value)
+      if name.is_a?(Symbol)
+        self.write(@field_list[name], target_value)
+      elsif name.is_a?(Integer)
+        self.update self.field.write_bits(name => @options[:bool_caster].call(target_value))
+      elsif name.respond_to?(:[]) and target_value.respond_to?(:[])
+        bits = {}
+        
+        name.each_with_index do |bit, i|
+          bits[bit] = @options[:bool_caster].call(target_value[i])
+        end
+        
+        self.update self.field.write_bits bits
+      end
+    end
+    
+    alias :[]= :write
+    
+    # Inspect output. 
+    #
+    # @return [String] an #inspect value for this instance
+    def inspect
+      short_options = {}
+      short_options[:default] = @options[:default]
+      short_options[:attribute_name] = @options[:attribute_name]
+      "#<#{self.class.to_s} #{@magician ? "bit_magic=#{@magician.bit_magic_name.inspect} " : nil}value=#{self.value}> options=#{short_options.inspect}"
+    end
+  end
+end

data/lib/bit_magic/bits_generator.rb

@@ -0,0 +1,399 @@
+require_relative './bits'
+
+module BitMagic
+  # This module generates integers that are bit representations of given bits,
+  # arrays of possible values with given bits, and arrays of possible values
+  # given some condition on the bits.
+  #
+  # In short, it gives you a list of possible integer values from a list of bits.
+  #
+  # @attr_reader [Hash] field_list a hash of :name => bit or :name => [bit, bit, ..., bits] 
+  #   key-value pairs for easier access of named bits/bit ranges
+  # @attr_reader [Hash] options options given to the generator
+  # @attr_reader [Integer] length the total number of bits specified
+  # @attr_reader [Integer] bits an array of bits used in field_list, list of
+  #   all the bits with which we will be working with
+  # 
+  class BitsGenerator
+    attr_reader :field_list, :options, :length, :bits
+    DEFAULT_OPTIONS = {default: 0, bool_caster: Bits::BOOLEAN_CASTER}.freeze
+    
+    # Initialize the generator.
+    #
+    # @param [BitMagic::Adapters::Magician, Hash] magician_or_field_list a Magician
+    #   object that contains field_list, bits, and options OR a Hash object of 
+    #   :name => bit index or bit index array, key-value pairs
+    # @param [Hash] options options and defaults, will override Magician action_options
+    #   if given
+    # @option options [Integer] :default a default value, default: 0
+    # @option options [Proc] :bool_caster a callable Method, Proc or lambda that
+    #   is used to cast a value into a boolean
+    #
+    # @return [BitsGenerator] the resulting object
+    def initialize(magician_or_field_list, options = {})
+      if defined?(BitMagic::Adapters::Magician) and magician_or_field_list.is_a?(BitMagic::Adapters::Magician)
+        @magician = magician_or_field_list
+        @field_list = @magician.field_list
+        @options = @magician.action_options.merge(options)
+        @length = @magician.bits_length
+        @bits = @magician.bits.uniq
+      else
+        @field_list = magician_or_field_list
+        @options = DEFAULT_OPTIONS.merge(options)
+        @bits = @field_list.values.flatten.uniq
+        @length = @bits.length
+      end
+    end
+    
+    # Given a field name or list of field names, return their corresponding bits
+    # Field names are the key values of the field_list hash during initialization
+    #
+    # @param [Symbol, Integer] one or more keys for the field name or an integer
+    #    for a known bit index
+    #
+    # @example Get a list of bits
+    #   gen = BitMagic::BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.bits_for(:is_odd) #=> [0]
+    #   gen.bits_for(:amount) #=> [1, 2, 3]
+    #   gen.bits_for(:is_odd, :amount) #=> [0, 1, 2, 3]
+    #   gen.bits_for(:is_cool, 5, 6) #=> [4, 5, 6]
+    #   gen.bits_for(9, 10) #=> [9, 10]
+    #
+    # @return [Array<Integer>] an array of bit indices
+    def bits_for(*field_names)
+      bits = []
+      
+      field_names.flatten.each do |i|
+        if i.is_a?(Integer)
+          bits << i
+          next
+        end
+        
+        if i.respond_to?(:to_sym) and @field_list[i.to_sym]
+          bits << @field_list[i.to_sym]
+        end
+      end
+      
+      bits.flatten
+    end
+    
+    # Iterates over the entire combination of all possible values utilizing the
+    # list of bits we are given.
+    #
+    # Warning: Because we are iteration over possible values, the total available
+    # values grows exponentially with the given number of bits. For example, if
+    # you use only 8 bits, there are 2*8 = 256 possible values, with 20 bits it
+    # grows to 2**20 = 1048576. At 32 bits, 2**32 = 4294967296.
+    #
+    # Warning 2: We're using combinations to generate each individual number, so
+    # there's additional overhead causing O(n!) complexity. Use carefully when 
+    # you have large bit lists (more than 16 bits total). Check timing and memory.
+    # 
+    # @param [optional, Array<Integer>] each_bits a list of bits used to generate
+    #   the combination list. default: the list of bits given during initialization
+    # @param [Proc] block a callable method to yield individual values
+    #
+    # @yield num will yield to the given block multiple times, each time with one
+    #   of the integer values that are possible from the given bits list
+    #
+    # @example Iterate over a list of bits
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   values = []
+    #   gen.each_value { |val| values << val } #=> 32
+    #   values #=> [0, 1, 2, 4, 8, 16, 3, 5, 9, 17, 6, 10, 18, 12, 20, 24, 7, 11, 19, 13, 21, 25, 14, 22, 26, 28, 15, 23, 27, 29, 30, 31]
+    #   values2 = []
+    #   gen.each_value([0, 5]) { |val| values2 << val } #=> 4
+    #   values2 #=> [0, 1, 32, 33]
+    #
+    #
+    # @return [Integer] total number of values yielded
+    def each_value(each_bits = nil, &block)
+      # Warning! This has exponential complexity (time and space)
+      # 2**n to be precise, use sparingly
+      
+      yield 0
+      count = 1
+      
+      if @options[:default] != 0
+        yield @options[:default]
+        count += 1
+      end
+      
+      each_bits = self.bits if each_bits == nil
+      
+      1.upto(each_bits.length).each do |i|
+        each_bits.combination(i).each do |bits_list|
+          num = bits_list.reduce(0) { |m, j| m |= (1 << j) }
+          yield num
+          count += 1
+        end
+      end
+      
+      count
+    end
+    
+    # Gives you an array of all possible integer values based off the bit
+    # combinations of the bit list.
+    #
+    # Note: This will include all possible values from the bit list, but there
+    # are no guarantees on their order. If you need an ordered list, sort the result.
+    #
+    # Warning: Please see the warnings on each_value.
+    # 
+    # Warning: Memory usage grows exponentially to the number of bits! For example,
+    # on a 64 bit platform (assuming pointers are 8 bytes) if you have 8 bits,
+    # this array will have 256 values, taking up 2KB of memory. At 20 bits, it's
+    # 1048576 values, taking up 8MB. At 32 bits, 4294967296 values take up 34GB!
+    #
+    # @param [optional, Array<Integer>] each_bits a list of bits used to generate
+    #   the combination list. default: the list of bits given during initialization
+    # @param [Hash] opts additional options
+    # @option opts [Integer] :warn_threshold will output warning messages if
+    #   the total number of bits is above this number. false to disable. default: 20 
+    #
+    # @example Get an array for all values from our bit list
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.all_values
+    #
+    # @return [Array<Integer>] an array of all possible values from the bit list
+    #   Order is not guaranteed to be consistent.
+    def all_values(each_bits = nil, opts = {warn_threshold: 12})
+      # Shuffle things around so that people can call #all_values(warn_threshold: false)
+      if each_bits.is_a?(Hash)
+        opts = each_bits
+        each_bits = nil
+      end
+      
+      each_bits = self.bits if each_bits == nil
+      
+      if opts[:warn_threshold] and each_bits.length > opts[:warn_threshold]
+        warn "There are #{each_bits.length} bits. You will have #{2**(each_bits.length)} values in the result. Please carefully benchmark the execution time and memory usage of your use-case."
+        warn "You can disable this warning by using #all_values(warn_threshold: false)"
+      end
+      
+      values = []
+      
+      self.each_value(each_bits) {|num| values << num }
+      
+      values
+    end
+    
+    # Gives you an array of values where at least one of the bits of the field
+    # names list is set to true (ie any of the bits are true).
+    #
+    # Possible values are derived from the bits list during initialization.
+    #
+    # Note: Order is not guaranteed. All numbers will be present, but there is
+    # no expectation that the numbers will be in the same order every time. If
+    # you need an ordered list, you can sort the result.
+    # 
+    # @param [Symbol, Integer] one or more keys for the field name or an integer
+    #    for a known bit index
+    #
+    # @example Retrieve a list for odd numbers or cool numbers
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.any_of(:is_odd) #=> [1, 3, 5, 9, 17, 7, 11, 19, 13, 21, 25, 15, 23, 27, 29, 31]
+    #   gen.any_of(:is_cool) #=> [16, 17, 18, 20, 24, 19, 21, 25, 22, 26, 28, 23, 27, 29, 30, 31]
+    #   gen.any_of(:is_odd, :is_cool) # is_odd or is_cool, same as union of arrays above
+    #   #=> [1, 16, 3, 5, 9, 17, 18, 20, 24, 7, 11, 19, 13, 21, 25, 22, 26, 28, 15, 23, 27, 29, 30, 31]
+    #
+    #
+    # @return [Array<Integer>] an array of integer values with at least one of
+    #   the bits set (true, bit is 1).  Will be blank if no field names given.
+    def any_of(*field_names)
+      [].tap do |list|
+        any_num = any_of_number(*field_names)
+        self.each_value { |num| list << num if (num & any_num) > 0 }
+      end
+    end
+    alias :with_any :any_of
+    
+    # Gives you an array of values where all of these bits of the field names
+    # list is set to false (ie without all of these bits as true).
+    # 
+    # Possible values are derived from the bits list during initialization.
+    #
+    # Note: Order is not guaranteed. All numbers will be present, but there is
+    # no expectation that the numbers will be in the same order every time. If
+    # you need an ordered list, you can sort the result.
+    # 
+    # @param [Symbol, Integer] one or more keys for the field name or an integer
+    #    for a known bit index
+    #
+    # @example Retrieve a list for even numbers, or uncool numbers
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.none_of(:is_odd) #=> [0, 2, 4, 8, 16, 6, 10, 18, 12, 20, 24, 14, 22, 26, 28, 30]
+    #   gen.none_of(:is_cool) #=> [0, 1, 2, 4, 8, 3, 5, 9, 6, 10, 12, 7, 11, 13, 14, 15]
+    #   gen.none_of(:is_odd, :is_cool) #=> [0, 2, 4, 8, 6, 10, 12, 14]
+    #   gen.none_of(:is_odd, :is_cool, :amount) #=> [0]
+    #
+    # @return [Array<Integer>] an array of integer values with all bits of given
+    #   field names unset (false, bit is 0). Will be blank if no field names given.
+    def none_of(*field_names)
+      [].tap do |list|
+        lack_num = any_of_number(*field_names)
+        self.each_value { |num| list << num if (num & lack_num) == 0 }
+      end
+    end
+    alias :without_all :none_of
+    
+    # Gives you an array of values where at least one of the bits of the field
+    # names list is set to false (ie without any of these bits as true).
+    # 
+    # Possible values are derived from the bits list during initialization.
+    #
+    # Note: Order is not guaranteed. All numbers will be present, but there is
+    # no expectation that the numbers will be in the same order every time. If
+    # you need an ordered list, you can sort the result.
+    # 
+    # @param [Symbol, Integer] one or more keys for the field name or an integer
+    #    for a known bit index
+    #
+    # @example Retrieve a list for even numbers, and uncool numbers
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.instead_of(:is_odd) #=> [0, 2, 4, 8, 16, 6, 10, 18, 12, 20, 24, 14, 22, 26, 28, 30]
+    #   gen.instead_of(:is_odd, :is_cool) #=> [0, 1, 2, 4, 8, 16, 3, 5, 9, 6, 10, 18, 12, 20, 24, 7, 11, 13, 14, 22, 26, 28, 15, 30]
+    #   gen.instead_of(:is_odd, :is_cool, :amount) #=> [0, 1, 2, 4, 8, 16, 3, 5, 9, 17, 6, 10, 18, 12, 20, 24, 7, 11, 19, 13, 21, 25, 14, 22, 26, 28, 15, 23, 27, 29, 30]
+    #
+    # @return [Array<Integer>] an array of integer values with at least one of
+    #   the bits unset (false, bit is 0). Will be blank if no field names given.
+    def instead_of(*field_names)
+      [].tap do |list|
+        none_num = any_of_number(*field_names)
+        self.each_value { |num| list << num if (num & none_num) != none_num }
+      end
+    end
+    alias :without_any :instead_of
+    
+    def all_of(*field_names)
+      [].tap do |list|
+        all_num = any_of_number(*field_names)
+        self.each_value { |num| list << num if (num & all_num) == all_num }
+      end
+    end
+    alias :with_all :all_of
+    
+    # Gives you an array of values where the given field names are exactly
+    # equal to their given field values.
+    # 
+    # Possible values are derived from the bits list during initialization.
+    #
+    # Note: Order is not guaranteed. All numbers will be present, but there is
+    # no expectation that the numbers will be in the same order every time. If
+    # you need an ordered list, you can sort the result.
+    # 
+    # @param [Hash] one or more field names or an integer for a known bit index
+    #   as the key, and the value (integer or boolean) for that field as the hash
+    #   value. Values that have more bits than available will be truncated for
+    #   comparison. eg. a field with one bit setting value to 2 means field is 0
+    #
+    # @example Get different amount values
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.equal_to(:amount => 5) #=> [10, 11, 26, 27]
+    #   gen.equal_to(:amount => 7) #=>  [14, 15, 30, 31]
+    #   gen.equal_to(:amount => 7, :is_odd => 1, :is_cool => 1) #=> [31]
+    #
+    # @return [Array<Integer>] an array of integer values where the bits and values
+    #   match the given input
+    def equal_to(field_values = {})
+      all_num, none_num = self.equal_to_numbers(field_values)
+      
+      [].tap do |list|
+        self.each_value { |num| list << num if (num & all_num) == all_num and (num & none_num) == 0 }
+      end
+    end
+    
+    # Will return an array of two numbers, the first of which has all bits set
+    # where the corresponding value bit is 1, and the second has all bits set
+    # where the corresponding value bit is 0.
+    # These numbers can be used in advanced bitwise operations to test fields
+    # for exact equality.
+    # 
+    # @param [Hash] one or more field names or an integer for a known bit index
+    #   as the key, and the value (integer or boolean) for that field as the hash
+    #   value. Values that have more bits than available will be truncated for
+    #   comparison. eg. a field with one bit setting value to 2 means field is 0
+    #
+    # @example Retrieve the representation for various amounts
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.equal_to_numbers(:amount => 5) #=> [10, 4]
+    #   # 5 is 101, 10 is 1010 and 4 is 100. (Note that amount uses bits 1, 2, 3)
+    #   gen.equal_to_numbers(:amount => 7) #=> [14, 0]
+    #   gen.equal_to_numbers(:amount => 7, :is_odd => 1) #=> [15, 0]
+    #
+    # 
+    # @return [Array<Integer>] an array of two integers, first representing bits
+    #   of given field bit values as 1 set to 1, and the second representing bits
+    #   of given field bit values as 0 set to 1. See the example.
+    def equal_to_numbers(field_values = {})
+      fields = {}
+      
+      field_values.each_pair do |field_name, v|
+        bits = self.bits_for(field_name)
+        fields[bits] = v if bits.length > 0
+      end
+      
+      all_num = 0
+      none_num = 0
+      fields.each_pair { |field_bits, val|
+        field_bits.each_with_index do |bit, i|
+          if @options[:bool_caster].call(val[i])
+            all_num |= (1 << bit)
+          else
+            none_num |= (1 << bit)
+          end
+        end
+      }
+      
+      [all_num, none_num]
+    end
+    
+    # Get an integer with the given field names' bits all set. This number can
+    # be used in bitwise operations to test field conditionals.
+    # 
+    # @param [Symbol, Integer] one or more keys for the field name or an integer
+    #    for a known bit index
+    #
+    # @example Get a number representing odd numbers, or an arbitrary amount
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.any_of_number(:is_odd) #=> 1 # because 1 in binary is 00001
+    #   gen.any_of_number(:amount) #=> 14 # because 14 is 01110
+    #   gen.any_of_number(:is_odd, :amount, :is_cool) #=> 31
+    #   # 31 is 11111 because all five bits (0 to 4) are true (one)
+    #
+    #
+    # @return [Integer] the integer with all field names' bits are true 
+    def any_of_number(*field_names)
+      self.bits_for(*field_names).reduce(0) { |m, bit| m | (1 << bit) }
+    end
+    alias :with_any_number :any_of_number
+    alias :with_all_number :any_of_number
+    alias :all_of_number :any_of_number
+    
+    # Get an integer with the given field names' bits all unset. This number can
+    # be used in bitwise operations to test field conditionals.
+    #
+    # Note: Because of ruby's handling of two's complement, this number is  
+    # almost always a negative number.
+    # 
+    # @param [Symbol, Integer] one or more keys for the field name or an integer
+    #    for a known bit index
+    #
+    # @example Get a number representing even numbers, or an arbitrary amount
+    #   gen = BitsGenerator.new(:is_odd => 0, :amount => [1, 2, 3], :is_cool => 4)
+    #   gen.none_of_number(:is_odd) #=> -2 # because -2 in binary is 1...11110
+    #   gen.none_of_number(:amount) #=> -15
+    #   # -15 in binary is 1...10001
+    #   gen.none_of_number(:is_odd, :amount, :is_cool) #=> -32
+    #   # -32 is 1...00000 because all five bits (0 to 4) are false (zero)
+    #   
+    # 
+    # @return [Integer] the integer with all the field names' bits set to false
+    def none_of_number(*field_names)
+      ~self.any_of_number(*field_names)
+    end
+    alias :without_any_number :none_of_number
+    alias :without_all_number :none_of_number
+    
+  end
+end