in_array 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 56fbd9784a0391640e694ebad710d6a8c5f532d5
-  data.tar.gz: bd5283bf27cbe715ad63d6f5a6e40d230fa66c9d
+  metadata.gz: 1a8e4f410010aceefc1816040c2b3b54a8bcd8b6
+  data.tar.gz: 49119bd6a51e2db2e9a51bf517939c0d10659dc7
 SHA512:
-  metadata.gz: 1876848dbefc29438ecd6e4dfd601041b6ee8bc30cad24df54e6f52af510536727d4e2d5213b95e07863e12856dafe5281a79417df8be054959ce9be73e1705d
-  data.tar.gz: 78dc1d785c9218e842709d929b751e713b94d434d28358774ec6ef785d2773ccf7e2df9aeda6a1eee1f1ce274e5417553eda45933096668883d6f859377e2460
+  metadata.gz: 884f59125deddec82a8d302cfd608b75264c6c17e69432b2b79ee9a54d004d00a699e55ef220d156dc208e6726df6e0a8caee3c898120cae594b22d09a2bd6d4
+  data.tar.gz: 243cf3a7acbcb93d451951c3057a0eaa6be59ad34de0117257def81e4bf39499360db155f74b381b337bfe5b1629f38237352f8f8a19e5b66eacb6c307ee567e

data/.gitignore

@@ -2,3 +2,5 @@ rdoc/
 *.gem
 *.zip
 *.tmp
+pkg
+Gemfile.lock

data/README.md

@@ -3,24 +3,140 @@
 This project contains the Ruby in_array gem. This is perhaps the tiniest gem
 ever created. It allows all objects to respond to the :in_array method that
 encapsulates the object in an array unless it is already an array. So
+```ruby
+'Hello'.in_array    # ['Hello']
+['Hello'].in_array  # ['Hello']
+my_object.in_array  # [my_object]
+[1,2,3].in_array    # [1,2,3]
+```
+This very simple gem accomplishes a very simple task that is nonetheless useful.
+For example a method can now easily accept a single object or an array of
+objects:
 
-    'Hello'.in_array    ====> ['Hello']
-    ['Hello'].in_array  ====> ['Hello']
-    my_object.in_array  ====> [my_object]
-    [1,2,3].in_array    ====> [1,2,3]
+```ruby
+def my_method(args, other)
+  args.in_array.each{|arg| process(arg, other) }
+end
+```
+Now all of the following will work correctly:
+```ruby
+my_method 12, 11
+my_method 42, 11
+my_method [12, 42], 11
+```
+From an instructive view point, this gem also demonstrates the use of
+inheritance as opposed to simulated polymorphism.
 
-While not a terribly useful gem, it does demonstrate the use of inheritance
-and true as opposed to simulated polymorphism.
+## Installation
 
-## Usage
+Add this line to your application's Gemfile:
 
-    require 'in_array'
+    gem 'in_array'
 
-then, in those places where array-ness was problematic, use:
+And then execute:
 
-    my_object.in_array.each do |option| #etc, etc, etc...
+    $ bundle
 
-instead of
+Or install it yourself as:
+
+    $ gem install in_array
+
+
+## Usage
+This is as simple as:
+```ruby
+require 'in_array'
+```
 
+then, in those places where array-ness was problematic, use:
+```ruby
+my_object.in_array.each do |option| #etc, etc, etc...
+```
+
+instead of
+```ruby
     my_object = [my_object] unless my_object.is_a?(Array)
     my_object.each do |option| #etc, etc, etc...
+```
+
+#### Extending the Protocol
+
+The in_array gem sets up a simple protocol that permits its behavior to be
+easily added to user defined classes that behave (aka duck type) as arrays. The
+following snippet shows how this is done:
+```ruby
+class MyArray
+  #This class behaves like an array.
+  include InArrayAlready
+
+  #Rest of the class omitted.
+end
+
+```
+
+## Performance
+
+All other aspects aside, good code should not exact a significant speed
+penalty. The benchmark tests that follow show that the in_array gem should be
+expected to improve performance when compared with the simulated polymorphism
+alternative.
+
+The first test assumes a simple scenario with only the Array class. Polymorphism
+is simulated using the is_a? method:
+
+    C:\Sites\in_array>ruby bench\simple_bench.rb
+    Warming up --------------------------------------
+    Process with in_array
+                             5.178k i/100ms
+    Process with is_a?
+                             4.037k i/100ms
+    Calculating -------------------------------------
+    Process with in_array
+                             54.001k (± 5.4%) i/s -    274.434k
+    Process with is_a?
+                             41.897k (± 5.3%) i/s -    209.924k
+
+    Comparison:
+    Process with in_array:    54000.9 i/s
+    Process with is_a?   :    41897.1 i/s - 1.29x slower
+
+The second scenario adds a user defined array like class. In this case, two
+methods of simulated polymorphism are tested, based on include? and a hash
+of allowed array classes. Here are those results.
+
+    C:\Sites\in_array>ruby bench\complex_bench.rb
+    Warming up --------------------------------------
+    Process with in_array
+                             5.163k i/100ms
+    Process with hash[]
+                             1.779k i/100ms
+    Process with include?
+                             1.895k i/100ms
+    Calculating -------------------------------------
+    Process with in_array
+                             54.239k (± 5.3%) i/s -    273.639k
+    Process with hash[]
+                             17.924k (± 3.2%) i/s -     90.729k
+    Process with include?
+                             19.232k (± 3.8%) i/s -     96.645k
+
+    Comparison:
+    Process with in_array:    54238.6 i/s
+    Process with include?:    19231.7 i/s - 2.82x slower
+    Process with hash[]  :    17923.9 i/s - 3.03x slower
+
+## Contributing
+
+#### Plan A
+
+1. Fork it ( https://github.com/PeterCamilleri/in_array/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+#### Plan B
+
+Go to the GitHub repository and raise an issue calling attention to some
+aspect that could use some TLC or a suggestion or an idea.
+

data/bench/complex_bench.rb

@@ -0,0 +1,52 @@
+require "benchmark/ips"
+require 'in_array'
+
+class MyArray
+  #Pretend that this class behaves like an array.
+  include InArrayAlready
+end
+
+class Object
+  def slow_in_array
+    if [Array, MyArray].include? self.class
+      self
+    else
+      [ self ]
+    end
+  end
+
+  ARRAY_CLUB = {Array => true, MyArray => true }
+
+  def accel_in_array
+    if ARRAY_CLUB[self.class]
+      self
+    else
+      [ self ]
+    end
+  end
+end
+
+Test1 = (1..100).to_a
+Test2 = Array(100) { MyArray.new }
+
+def use_in_array
+  a1 = Test1.map {|e| e.in_array  }
+  a2 = Test2.map {|e| e.in_array  }
+end
+
+def use_accel_in_array
+  a1 = Test1.map {|e| e.accel_in_array  }
+  a2 = Test2.map {|e| e.accel_in_array  }
+end
+
+def use_slow_in_array
+  a1 = Test1.map {|e| e.slow_in_array  }
+  a2 = Test2.map {|e| e.slow_in_array  }
+end
+
+Benchmark.ips do |x|
+  x.report("Process with in_array") { use_in_array }
+  x.report("Process with hash[]  ") { use_accel_in_array }
+  x.report("Process with include?") { use_slow_in_array }
+  x.compare!
+end

data/bench/simple_bench.rb

@@ -0,0 +1,31 @@
+require "benchmark/ips"
+require 'in_array'
+
+class Object
+  def slow_in_array
+    if self.is_a? Array
+      self
+    else
+      [ self ]
+    end
+  end
+end
+
+Test1 = (1..100).to_a
+Test2 = Array(100) { |i| [ i ] }
+
+def use_in_array
+  a1 = Test1.map {|e| e.in_array  }
+  a2 = Test2.map {|e| e.in_array  }
+end
+
+def use_slow_in_array
+  a1 = Test1.map {|e| e.slow_in_array  }
+  a2 = Test2.map {|e| e.slow_in_array  }
+end
+
+Benchmark.ips do |x|
+  x.report("Process with in_array") { use_in_array }
+  x.report("Process with is_a?   ") { use_slow_in_array }
+  x.compare!
+end

data/lib/in_array/version.rb

@@ -3,5 +3,5 @@
 #* version.rb - The version string for flex array.
 module InArray
   #The version string for flex array.
-  VERSION = "0.1.3"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: in_array
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Peter Camilleri
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-02-27 00:00:00.000000000 Z
+date: 2016-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest_visible
@@ -103,8 +103,9 @@ extra_rdoc_files:
 files:
 - ".gitignore"
 - Gemfile
-- Gemfile.lock
 - README.md
+- bench/complex_bench.rb
+- bench/simple_bench.rb
 - in_array.gemspec
 - lib/in_array.rb
 - lib/in_array/version.rb

data/Gemfile.lock

@@ -1,36 +0,0 @@
-PATH
-  remote: .
-  specs:
-    in_array (0.1.2)
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    json (1.8.1)
-    minitest (4.7.5)
-    rainbow (2.0.0)
-    rake (10.3.2)
-    rdoc (4.0.1)
-      json (~> 1.4)
-    reek (1.3.8)
-      rainbow (>= 1.99, < 3.0)
-      ruby2ruby (>= 2.0.8, < 3.0)
-      ruby_parser (~> 3.3)
-      sexp_processor
-    ruby2ruby (2.1.3)
-      ruby_parser (~> 3.1)
-      sexp_processor (~> 4.0)
-    ruby_parser (3.6.3)
-      sexp_processor (~> 4.1)
-    sexp_processor (4.4.4)
-
-PLATFORMS
-  x86-mingw32
-
-DEPENDENCIES
-  bundler (~> 1.3)
-  in_array!
-  minitest (~> 4.7.5)
-  rake
-  rdoc (~> 4.0.1)
-  reek (~> 1.3.8)