trick_bag 0.55.0 → 0.56.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 768645a9651bf65821b78ea38047105f374f65d9
-  data.tar.gz: 5424fa9c01caea081e7b0215ba554a29273c74ab
+  metadata.gz: d4818c34b17f75700285ef836328c5dd0a543862
+  data.tar.gz: 081c5c721ca498f42bcc05031e2f4ddac2d73ac8
 SHA512:
-  metadata.gz: ef6dc3e7939320304554e4ef73e72103379f1fb0c56a450f9b4239e23fb56c9ec897e43293b0d3ad85b0a41a57795368b1382a323f17dbcc7cc6e3890ce144e8
-  data.tar.gz: 49f68b998c1f5a0675fc6eecb208d3dba0976c22da83a0782d6ad7711f8d9e65f9fbc26ee7565052001a9a681212444a59e548e4c0c50511c70305893976dea8
+  metadata.gz: 088282d53b429a5657106ac4e1e94988a47468db31018e812c20479c3545995baa8f474d1d45ceaa1ee018f6af2930d58f215004994cf65a6790900b2a9186e3
+  data.tar.gz: 7487f2e3e6d233af9c420797d092aab6c0a96a0d56b2a7479d70a12f02da0cbf80c3c5045a9e272d7cb2f09f987b66ac88b3720e2a48b2a561ad40bbca8136aa

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+
+rvm:
+- 2.0.0
+- 1.9.3
+- jruby-19mode
+
+script: "bundle exec rspec spec"

data/README.md

@@ -1,3 +1,5 @@
+[![Build Status](https://travis-ci.org/keithrbennett/trick_bag.svg?branch=master)](https://travis-ci.org/keithrbennett/trick_bag)
+
 # TrickBag
 
 This gem is a collection of useful classes and modules for Ruby development.
@@ -21,7 +23,6 @@ Or install it yourself as:
 
 See the unit tests in the spec directory tree for usage examples.
 
-TODO: Write usage instructions here
 
 ## Contributing
 

data/RELEASE_NOTES.md

@@ -1,3 +1,8 @@
+## v0.56.0
+
+* Added Bitmap class/support.
+
+
 ## v0.55.0
 
 * Version confusion; this should have been the "real" 0.54.0.

data/lib/trick_bag/collections/collection_access.rb

@@ -6,6 +6,7 @@ module CollectionAccess
 
   module_function
 
+
   # Accesses a collection with a single string that represents n levels of depth.
   # See the spec file for examples, but here's one:
   #
@@ -23,11 +24,27 @@ module CollectionAccess
   # @separator the string to use to separate the
   def access(collection, key_string, separator = '.')
 
+    is_number_string = ->(s) do
+      begin
+        Integer(s)
+        true
+      rescue
+        false
+      end
+    end
+
     keys = key_string.split(separator)
     return_object = collection
 
     keys.each_with_index do |key, index|
-      key = key.to_i if return_object.kind_of?(Array)
+
+      if return_object.kind_of?(Array)
+        unless is_number_string.(key)
+          raise "Key is not a number string: #{key}"
+        end
+        key = key.to_i
+      end
+
       begin
         return_object = return_object[key]
       rescue => e

data/lib/trick_bag/numeric/bitmap.rb

@@ -0,0 +1,204 @@
+require 'forwardable'
+
+module TrickBag
+module Numeric
+
+
+# Provides class methods for converting between the various representations
+# of a bitmap: number, binary encoded string, array, and sparse array.
+#
+# An instance can be created that will hold on to bitmap data and be used
+# to test bits and convert to other formats.
+class Bitmap
+
+  extend Forwardable
+
+  # This is the internal representation of the bitmap value:
+  attr_reader :number
+
+  [:&, :|, :^, :hash].each do |method_name|
+    def_delegator :@number, method_name
+  end
+
+  def number=(new_number)
+    self.assert_nonnegative(new_number)
+    @number = new_number
+  end
+
+
+  # The constructor is made private because:
+  #
+  # 1) each type of initialization requires its own validation, and it
+  #    would be wasteful to do the validation unnecessarily
+  # 2) to enforce that the more descriptively
+  #    named class methods should be used to create instances.
+  private_class_method :new
+
+
+  # Class methods for converting between representations:
+
+  # Converts from a binary string to a number, e.g. "\x01\x00" => 256
+  def self.binary_string_to_number(string)
+    string = string.clone.force_encoding(Encoding::ASCII_8BIT)
+    string.bytes.inject(0) do |number, byte|
+      number * 256 + byte.ord
+    end
+  end
+
+
+  # Converts a number to a binary encoded string, e.g. 256 => "\x01\x00"
+  def self.number_to_binary_string(number, min_length = 0)
+    assert_nonnegative(number)
+    binary_string = ''.force_encoding(Encoding::ASCII_8BIT)
+
+    while number > 0
+      byte_value = number & 0xFF
+      binary_string << byte_value
+      number >>= 8
+    end
+
+    binary_string.reverse.rjust(min_length, "\x00")
+  end
+
+
+  # Converts a number to an array of place values, e.g. 9 => [8, 0, 0, 1]
+  def self.number_to_value_array(number)
+    assert_nonnegative(number)
+    array = []
+    bit_value = 1
+    while number > 0
+      array << ((number & 1 == 1) ? bit_value : 0)
+      number >>= 1
+      bit_value <<= 1
+    end
+    array.reverse
+  end
+
+
+  # Converts from a value array to a number, e.g. [8, 0, 0, 1] => 9
+  def self.value_array_to_number(value_array)
+    value_array.inject(&:+)
+  end
+
+
+  # Converts a number to an array of bit values, e.g. 9 => [1, 0, 0, 1]
+  def self.number_to_bit_array(number)
+    assert_nonnegative(number)
+    array = []
+    while number > 0
+      array << (number & 1)
+      number >>= 1
+    end
+    array.reverse
+  end
+
+
+  # Converts an array of bit values, e.g. [1, 0, 0, 1], to a number, e.g. 9
+  def self.bit_array_to_number(bit_array)
+    return nil if bit_array.empty?
+    multiplier = 1
+    bit_array.inject(0) do |result, n|
+      result += n * multiplier
+      multiplier *= 2
+      result
+    end
+  end
+
+
+  # Converts a number to a sparse array containing bit positions that are set/true/1.
+  # Note that these are bit positions, e.g. 76543210, and not bit column values
+  # such as 128/64/32/16/8/4/2/1.
+  def self.number_to_set_bit_positions_array(number)
+    assert_nonnegative(number)
+    array = []
+    position = 0
+    while number > 0
+      array << position if number & 1 == 1
+      position += 1
+      number >>= 1
+    end
+    array
+  end
+
+
+  # Converts an array of bit position numbers to a numeric value, e.g. [0, 2] => 5
+  def self.set_bit_position_array_to_number(position_array)
+    return nil if position_array.empty?
+    position_array.inject(0) do |result, n|
+      result += 2 ** n
+    end
+  end
+
+
+  def self.binary_string_to_bit_value_array(string)
+    number = binary_string_to_number(string)
+    number_to_bit_array(number)
+  end
+
+  # Class methods to create instances from the various representation types
+  # handled in the class methods above:
+
+  def self.from_number(number)
+    new(number)
+  end
+
+  def self.from_binary_string(string)
+    new(binary_string_to_number(string))
+  end
+
+  def self.from_value_array(array)
+    new(value_array_to_number(array))
+  end
+
+  def self.from_bit_array(array)
+    new(bit_array_to_number(array))
+  end
+
+  def self.from_set_bit_position_array(array)
+    new(set_bit_position_array_to_number(array))
+  end
+
+  def self.from_number(number)
+    new(number)
+  end
+
+
+  def self.assert_nonnegative(number)
+    unless number.is_a?(Integer) && number >= 0
+      raise ArgumentError.new(
+          "Parameter must be a nonnegative Integer (Fixnum, Bignum) " +
+          "but is #{number.inspect} (a #{number.class})")
+    end
+  end
+
+
+  def to_binary_string(min_length = 0)
+    self.class.number_to_binary_string(number, min_length)
+  end
+
+  def to_value_array
+    self.class.number_to_value_array(number)
+  end
+
+  def to_bit_array
+    self.class.number_to_bit_array(number)
+  end
+
+  def to_set_bit_position_array
+    self.class.number_to_set_bit_positions_array(number)
+  end
+
+
+  def initialize(number)
+    self.class.assert_nonnegative(number)
+    @number = number
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && other.number == self.number
+  end
+end
+end
+end
+
+

data/lib/trick_bag/timing/timing.rb

@@ -15,8 +15,16 @@ module Timing
   #   that returns a truthy value that indicates no further retries are necessary
   # @param sleep_interval  number of seconds (fractions ok) to wait between tries
   # @param timeout_secs maximum number of seconds (fractions ok) during which to retry
+  # @return true if/when the predicate returns true, false if it times out
   #
   # Ex: TrickBag::Timing.retry_until_true_or_timeout(->{false}, 1.0, 5)
+  #
+  # Example Code:
+  #
+  # require 'trick_bag'
+  # predicate = -> { false }
+  # print "Waiting 10 seconds for true to be returned (but it won't):\n"
+  # TrickBag::Timing.retry_until_true_or_timeout(predicate, 1, 10)
   def retry_until_true_or_timeout(
       predicate, sleep_interval, timeout_secs, output_stream = $stdout)
 

data/lib/trick_bag/validations/other_validations.rb

@@ -30,6 +30,8 @@ module Validations
   end
 
 
+  # Note: This method is not supported in JRuby.
+  #
   # When a gem project has a .gemspec, this uses bundle exec to verify that requiring
   # that gem name does not result in an error. (An error would occur, for example,
   # if a gem required by the project gem is not specified as a dependency in
@@ -38,6 +40,9 @@ module Validations
   # @return a hash containing the :exit_status (0 = success), output (stdout + stderr),
   # and the :process_status (Process::Status object).
   def test_gem_dependency_specs(gem_name)
+
+    raise "This method not supported in JRuby" if /java/.match(RUBY_PLATFORM)
+
     command = %Q{bundle exec ruby -e "require '#{gem_name}'"}
 
     output, process_status = Open3.capture2e(command)

data/lib/trick_bag/version.rb

@@ -1,3 +1,3 @@
 module TrickBag
-  VERSION = "0.55.0"
+  VERSION = "0.56.0"
 end

data/spec/trick_bag/collections/collection_access_spec.rb

@@ -52,6 +52,11 @@ describe CollectionAccess do
       h = { 'h' => ['a', 'b'] }
       expect(-> { CollectionAccess.access(h, 'x.1.2') }).to raise_error
     end
+
+    it 'raises an error when accessing a string that should be a number' do
+      h = { 'x' => ['a', 'b'] }
+      expect(-> { CollectionAccess.access(h, 'x.x') }).to raise_error
+    end
   end
 
 

data/spec/trick_bag/numeric/bitmap_spec.rb

@@ -0,0 +1,225 @@
+require_relative '../../spec_helper'
+
+require 'trick_bag/numeric/bitmap'
+
+module TrickBag
+module Numeric
+
+
+  describe Bitmap do
+
+
+    specify 'the constructor should not permit being explicitly called outside the class' do
+      expect(-> { Bitmap.new }).to raise_error
+    end
+
+
+    context '.binary_string_to_number' do
+
+      it 'computes byte values correctly' do
+        expect(Bitmap.binary_string_to_number("\xFF")).to eq(255)
+        expect(Bitmap.binary_string_to_number("\x0D")).to eq(13)
+      end
+
+      it 'considers the left-most byte most significant' do
+        expect(Bitmap.binary_string_to_number("\x01\x00")).to eq(256)
+      end
+
+      # Unspecified encoding results in UTF-8 anyway, but this makes it explicit:
+      it 'correctly handles non-ASCII_8BIT strings' do
+        expect(Bitmap.binary_string_to_number("\x01\x00".force_encoding(Encoding::UTF_8))).to eq(256)
+      end
+    end
+  end
+
+
+  context '.number_to_binary_string' do
+
+    specify '256 => "\x01\00"' do
+      expect(Bitmap.number_to_binary_string(256)).to eq("\x01\x00")
+    end
+
+    specify 'a negative number should result in an error' do
+      expect { Bitmap.number_to_binary_string(-1) }.to raise_error(ArgumentError)
+    end
+
+    specify 'when requested, zero padding will left pad with zeros' do
+      expect(Bitmap.number_to_binary_string(256, 8)).to eq("#{"\x00" * 6}\x01\x00")
+    end
+  end
+
+
+  context '.number_to_value_array' do
+
+    specify '9 => [8, 0, 0, 1]' do
+      expect(Bitmap.number_to_value_array(9)).to eq([8, 0, 0, 1])
+    end
+
+    specify '256 => [256] + ([0] * 8)' do
+      expect(Bitmap.number_to_value_array(256)).to eq([256] + [0] * 8)
+    end
+
+    specify 'a negative number should result in an error' do
+      expect { Bitmap.number_to_value_array(-1) }.to raise_error(ArgumentError)
+    end
+  end
+
+  context '.value_array_to_number' do
+
+    specify '[8, 0, 0, 1] => 9' do
+      expect(Bitmap.value_array_to_number([8, 0, 0, 1])).to eq(9)
+    end
+
+    specify '[] => nil' do
+      expect(Bitmap.value_array_to_number([])).to eq(nil)
+    end
+  end
+
+  context '.bit_array_to_number' do
+
+    specify '[1, 0, 0, 1] => 9' do
+      expect(Bitmap.bit_array_to_number([1, 0, 0, 1])).to eq(9)
+    end
+
+    specify '[] => nil' do
+      expect(Bitmap.bit_array_to_number([])).to eq(nil)
+    end
+  end
+
+
+  context '.number_to_bit_array' do
+
+    specify '9 => [1, 0, 0, 1]' do
+      expect(Bitmap.number_to_bit_array(9)).to eq([1, 0, 0, 1])
+    end
+
+    specify '256 => [1] + ([0] * 8)' do
+      expect(Bitmap.number_to_bit_array(256)).to eq([1] + [0] * 8)
+    end
+
+    specify 'a negative number should result in an error' do
+      expect { Bitmap.number_to_bit_array(-1) }.to raise_error(ArgumentError)
+    end
+  end
+
+
+  context '.binary_string_to_bit_value_array' do
+    it 'computes byte values correctly' do
+      expect(Bitmap.binary_string_to_bit_value_array("\xFF")).to eq([1] * 8)
+      expect(Bitmap.binary_string_to_bit_value_array("\x0D")).to eq([1,1,0,1])
+    end
+
+    it 'considers the left-most byte most significant' do
+      expect(Bitmap.binary_string_to_bit_value_array("\x01\x00")).to eq([1] + [0] * 8)
+    end
+
+    # Unspecified encoding results in UTF-8 anyway, but this makes it explicit:
+    it 'correctly handles non-ASCII_8BIT strings' do
+      expect(Bitmap.binary_string_to_bit_value_array("\x01\x00".force_encoding(Encoding::UTF_8))).to eq([1] + [0] * 8)
+    end
+  end
+
+
+  context '.number_to_set_bit_positions_array' do
+
+    specify '9 => [0, 3]' do
+      expect(Bitmap.number_to_set_bit_positions_array(9)).to eq([0, 3])
+    end
+
+    specify 'a negative number should result in an error' do
+      expect { Bitmap.number_to_set_bit_positions_array(-1) }.to raise_error(ArgumentError)
+    end
+  end
+
+
+  context '.set_bit_position_array_to_number' do
+
+    specify '[0, 8] => 256' do
+      expect(Bitmap.set_bit_position_array_to_number([0, 8])).to eq(257)
+    end
+
+    specify '[] => nil' do
+      expect(Bitmap.set_bit_position_array_to_number([])).to eq(nil)
+    end
+  end
+
+
+  context 'test factory methods' do
+
+    specify 'from_number' do
+      expect(Bitmap.from_number(256).number).to eq(256)
+    end
+
+    specify 'from_binary_string' do
+      expect(Bitmap.from_binary_string("\x01\x00").number).to eq(256)
+    end
+
+    specify 'from_value_array' do
+      expect(Bitmap.from_value_array([8, 0, 0, 1]).number).to eq(9)
+    end
+
+    specify 'from_bit_array' do
+      expect(Bitmap.from_bit_array([1, 0, 0, 1]).number).to eq(9)
+    end
+
+    specify 'from_set_bit_position_array' do
+      expect(Bitmap.from_set_bit_position_array([0, 3]).number).to eq(9)
+    end
+  end
+
+  context 'test output methods' do
+
+    specify 'to_binary_string' do
+      bitmap = Bitmap.from_number(258)
+      expect(bitmap.to_binary_string).to eq("\x01\x02")
+    end
+
+    specify 'to_value_array' do
+      bitmap = Bitmap.from_number(258)
+      # expect(bitmap.to_value_array).to eq([0, 2, 0, 0, 0, 0, 0, 0, 256])
+      expect(bitmap.to_value_array).to eq([256, 0, 0, 0, 0, 0, 0, 2, 0])
+    end
+
+    specify 'to_bit_array' do
+      bitmap = Bitmap.from_number(258)
+      expect(bitmap.to_bit_array).to eq([1, 0, 0, 0, 0, 0, 0, 1, 0])
+    end
+
+    specify 'to_set_bit_position_array' do
+      bitmap = Bitmap.from_number(258)
+      expect(bitmap.to_set_bit_position_array).to eq([1, 8])
+    end
+  end
+
+
+  context 'binary operators' do
+    specify '3 & 2 => 2' do
+      expect(Bitmap.from_number(3) & 2).to eq(2)
+    end
+
+    specify '3 | 2 => 3' do
+      expect(Bitmap.from_number(3) | 2).to eq(3)
+    end
+
+    specify '3 ^ 2 => 1' do
+      expect(Bitmap.from_number(3) ^ 2).to eq(1)
+    end
+
+  end
+
+  context 'hash, ==' do
+    specify 'instances created with the same value are ==' do
+      expect(Bitmap.from_number(1234)).to eq(Bitmap.from_number(1234))
+    end
+
+    specify 'instances created with different values are !=' do
+      expect(Bitmap.from_number(1234)).to_not eq(Bitmap.from_number(5678))
+    end
+
+    specify 'instances created with the same value have the same hash' do
+      expect(Bitmap.from_number(1234).hash).to eq(Bitmap.from_number(1234).hash)
+    end
+  end
+  end
+end
+

data/spec/trick_bag/timing/timing_spec.rb

@@ -7,12 +7,19 @@ module TrickBag
   describe Timing do
 
     context '.retry_until_true_or_timeout' do
-      it 'returns when the predicate returns true' do
+      it 'returns true when the predicate returns true' do
         count = 0
         predicate = ->{ count += 1; count == 3 }
-        Timing.retry_until_true_or_timeout(predicate, 0, 1, StringIO.new)
+        return_value = Timing.retry_until_true_or_timeout(predicate, 0, 1, StringIO.new)
+        expect(return_value).to be(true)
         expect(count).to eq(3)
       end
+
+      it 'returns false when the predicate fails to return true and a timeout occurs' do
+        predicate = -> { false }
+        return_value = Timing.retry_until_true_or_timeout(predicate, 0, 0.1, StringIO.new)
+        expect(return_value).to be(false)
+      end
     end
 
 

data/spec/trick_bag/validations/other_validations_spec.rb

@@ -28,11 +28,17 @@ module TrickBag
     end
 
     specify 'this gem contains all necessary gem dependency specifications' do
-      require 'open3'
-      result = test_gem_dependency_specs('trick_bag')
-      exit_status = result[:exit_status]
-      if exit_status  != 0
-        fail "Exit status was #{exit_status}, output was:\n#{output}."
+
+      if /java/.match(RUBY_PLATFORM)
+        STDERR.puts "Running in JRuby; bypassing test of Validations.test_gem_dependency_specs, not supported."
+        expect(-> { test_gem_dependency_specs('trick_bag') }).to raise_error
+      else
+        require 'open3'
+        result = test_gem_dependency_specs('trick_bag')
+        exit_status = result[:exit_status]
+        if exit_status  != 0
+          fail "Exit status was #{exit_status}, output was:\n#{output}."
+        end
       end
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: trick_bag
 version: !ruby/object:Gem::Version
-  version: 0.55.0
+  version: 0.56.0
 platform: ruby
 authors:
 - Keith Bennett
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-25 00:00:00.000000000 Z
+date: 2015-01-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: os
@@ -88,6 +88,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".travis.yml"
 - Gemfile
 - Guardfile
 - LICENSE.txt
@@ -109,6 +110,7 @@ files:
 - lib/trick_bag/io/temp_files.rb
 - lib/trick_bag/io/text_mode_status_updater.rb
 - lib/trick_bag/meta/classes.rb
+- lib/trick_bag/numeric/bitmap.rb
 - lib/trick_bag/numeric/multi_counter.rb
 - lib/trick_bag/numeric/start_and_max.rb
 - lib/trick_bag/numeric/totals.rb
@@ -136,6 +138,7 @@ files:
 - spec/trick_bag/io/temp_files_spec.rb
 - spec/trick_bag/io/text_mode_status_updater_spec.rb
 - spec/trick_bag/meta/classes_spec.rb
+- spec/trick_bag/numeric/bitmap_spec.rb
 - spec/trick_bag/numeric/multi_counter_spec.rb
 - spec/trick_bag/numeric/start_and_max_spec.rb
 - spec/trick_bag/numeric/totals_spec.rb
@@ -167,7 +170,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.2
 signing_key: 
 specification_version: 4
 summary: Miscellaneous general useful tools.
@@ -187,6 +190,7 @@ test_files:
 - spec/trick_bag/io/temp_files_spec.rb
 - spec/trick_bag/io/text_mode_status_updater_spec.rb
 - spec/trick_bag/meta/classes_spec.rb
+- spec/trick_bag/numeric/bitmap_spec.rb
 - spec/trick_bag/numeric/multi_counter_spec.rb
 - spec/trick_bag/numeric/start_and_max_spec.rb
 - spec/trick_bag/numeric/totals_spec.rb
@@ -197,3 +201,4 @@ test_files:
 - spec/trick_bag/validations/object_validations_spec.rb
 - spec/trick_bag/validations/other_validations_spec.rb
 - spec/trick_bag/validations/regex_validations_spec.rb
+has_rdoc: