idempotent_enumerable 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5ac991903381b9f945b1f4cc0d2336efc0523b2d
+  data.tar.gz: 963db8eb4ae066178ce0b22df3b9fbf1315549db
+SHA512:
+  metadata.gz: 97fa573e2be5ae08a6837e988f75adc737fbcbd436223b37581dfdce045062312d9b30590a300e9dbaa4b4147bef6935181ed77e3e9c4cc913e0d4fd64d28f8a
+  data.tar.gz: ef45aa843263e4232d3f09b6b89970cf971e607d06262d2ec6a4094692238792de99e06b37d9ed2e0cd660426098db546f6dbfa0421ab79e4d9e9c1e193e1c3e

data/.rubocop_todo.yml

@@ -0,0 +1 @@
+

data/README.md

@@ -0,0 +1,217 @@
+# IdempotentEnumerable
+
+[![Gem Version](https://badge.fury.io/rb/idempotent_enumerable.svg)](http://badge.fury.io/rb/idempotent_enumerable)
+[![Build Status](https://travis-ci.org/zverok/idempotent_enumerable.svg?branch=master)](https://travis-ci.org/zverok/idempotent_enumerable)
+[![Coverage Status](https://coveralls.io/repos/zverok/idempotent_enumerable/badge.svg?branch=master)](https://coveralls.io/r/zverok/idempotent_enumerable?branch=master)
+
+
+`IdempotentEnumerable` is like Ruby core's `Enumerable` but tries to preserve the class of the
+collection it included in, where reasonable.
+
+## Features/Showcase
+
+```ruby
+require 'set'
+
+s = Set.new(1..5)
+# => #<Set: {1, 2, 3, 4, 5}>
+s.reject(&:odd?)
+# => [2, 4] -- FFFUUUU
+
+require 'idempotent_enumerable'
+Set.include IdempotentEnumerable
+
+s.reject(&:odd?)
+# => #<Set: {2, 4}> -- Nice!
+```
+
+`IdempotentEnumerable` relies on fact your `each` method returns an instance of `Enumerator` (or
+other `Enumerable` object) when called without block. Which, honestly, it should do anyways.
+
+To construct back an instance of original class, `IdempotentEnumerable` relies on the fact
+`OriginalClass.new(array)` call will work. But, if your class provides another way for construction
+from array, you can still use the module:
+
+```ruby
+h = {a: 1, b: 2, c: 3}
+# => {:a=>1, :b=>2, :c=>3}
+h.first(2)
+# => [[:a, 1], [:b, 2]]
+
+Hash.include IdempotentEnumerable
+
+# To make hash from array of pairs, one should use `Hash[array]` notation.
+Hash.idempotent_enumerable.constructor = :[]
+
+h.first(2)
+# => {:a=>1, :b=>2}
+```
+
+`IdempotentEnumerable` also supports complicated collections, with `each` accepting additional
+arguments, out of the box ([daru](https://github.com/SciRuby/daru) used as an example):
+
+```ruby
+require 'daru'
+
+Daru::DataFrame.include IdempotentEnumerable
+
+df = Daru::DataFrame.new([[1,2,3], [4,5,6], [7,8,9]])
+# #<Daru::DataFrame(3x3)>
+#        0   1   2
+#    0   1   4   7
+#    1   2   5   8
+#    2   3   6   9
+
+# :column argument would be passed to DataFrame#each, so we are selecting columns
+df.select(:column) { |col| col.sum > 6 }
+# #<Daru::DataFrame(3x2)>
+#        0   1
+#    0   4   7
+#    1   5   8
+#    2   6   9
+```
+
+## Reasons
+
+`IdempotentEnumerable` can be used as:
+
+* soft patch to existing Ruby collections (like `Set` or `Hash`);
+* custom reimplementations of generic collections (some `FasterArray`);
+* custom specialized collection, like [Nokogiri::XML::NodeSet](http://www.rubydoc.info/github/sparklemotion/nokogiri/Nokogiri/XML/NodeSet),
+  which quacks like `Array`, but also provides XML/CSS navigation methods. Unfortunately, if you'll
+  do something like `doc.search('a').reject { |a| a.text.include?('Google') }`, you'll receive regular
+  `Array` that haven't any useful `#at`/`#search` methods anymore.
+
+## Installation and usage
+
+`gem install idempotent_enumerable` or `gem 'idempotent_enumerable'` in your `Gemfile`.
+
+Then follow examples in this README.
+
+## List of methods redefined
+
+### Methods that return single collection
+
+* [drop](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-drop);
+* [drop_while](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-drop_while);
+* [first](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-first) (when used with argument);
+* [grep](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-grep);
+* [grep_v](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-grep_v) (RUBY_VERSION >= 2.3);
+* [max](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-max) (when used with argument, RUBY_VERSION >= 2.2);
+* [max_by](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-max_by) (when used with argument, RUBY_VERSION >= 2.2);
+* [min](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-min) (when used with argument, RUBY_VERSION >= 2.2);
+* [min_by](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-min_by) (when used with argument, RUBY_VERSION >= 2.2);
+* [reduce](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-reduce);
+* [reject](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-reject);
+* [select](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-select);
+* [sort](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-sort);
+* [sort_by](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-sort_by);
+* [take](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-take);
+* [take_while](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-take_while);
+* [uniq](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-uniq)  (RUBY_VERSION >= 2.4).
+
+### Methods that return (or emit) several collections
+
+For methods like [partition](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-partition) that
+somehow split an enumerable sequence into several, `IdempotentEnumerable` preserves the type of
+**internal** sequence. E.g.:
+
+```ruby
+Set.include IdempotentEnumerable
+set = Set.new(1..5)
+set.partition(&:odd?)
+# => [#<Set: {1, 3, 5}>, #<Set: {2, 4}>]
+set.each_slice(3).to_a
+# => [#<Set: {1, 2, 3}>, #<Set: {4, 5}>]
+```
+
+* [chunk](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-chunk);
+* [chunk_while](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-chunk_while) (RUBY_VERSION >= 2.3);
+* [each_cons](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-each_cons);
+* [each_slice](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-each_slice);
+* [group_by](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-group_by) (returns hash with
+  keys being group keys and values being original collection type);
+* [partition](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-partition);
+* [slice_after](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-slice_after) (RUBY_VERSION >= 2.2);
+* [slice_before](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-slice_before);
+* [slice_when](https://ruby-doc.org/core-2.4.2/Enumerable.html#method-i-slice_when) (RUBY_VERSION >= 2.2).
+
+### Optionally redefined methods
+
+Generally speaking, `map` and `flat_map` can return collection of anything, probably not coercible
+to original collection type, so they are **not** redefined by default.
+
+But they can be redefined with optional `idempotent_enumerable.redefine_map!` call:
+
+```ruby
+Set.include IdempotentEnumerable
+set = Set.new(1..5)
+set.map(&:to_s)
+# => ["1", "2", "3", "4", "5"]
+Set.idempotent_enumerable.redefine_map!
+set.map(&:to_s)
+# => #<Set: {"1", "2", "3", "4", "5"}>
+```
+
+`redefine_map!` has two options:
+* `only:` (by default `[:map, :flat_map]`) to specify that you want to redefine only one of those
+  methods;
+* `all:` to specify which condition all elements of produced collection should satisfy to coerce.
+
+Example of the latter:
+
+```ruby
+Hash.include IdempotentEnumerable
+Hash.idempotent_enumerable.constructor = :[]
+# only convert back to hash if `map` have returned array of pairs
+Hash.idempotent_enumerable.redefine_map! all: ->(e) { e.is_a?(Array) && e.count == 2 }
+{a: 1, b: 2}.map(&:join)
+# => ["a1", "b2"]  -- no coercion
+{a: 1, b: 2}.map { |k, v| [k.to_s, v.to_s] }
+# => {"a"=>"1", "b"=>"2"} -- coercion
+```
+
+## Performance penalty
+
+...is, of course, present, yet not that awful (depends on your standards).
+
+```ruby
+require 'benchmark/ips'
+
+set1 = Set.new((1..100))
+
+class SetI < Set
+  include IdempotentEnumerable
+end
+set2 = SetI.new((1..100))
+
+Benchmark.ips do |x|
+  x.report('Enumerable') { set1.reject(&:odd?) }
+  x.report('IdempotentEnumerable') { set2.reject(&:odd?) }
+
+  x.compare!
+end
+```
+
+Output:
+
+```
+Warming up --------------------------------------
+          Enumerable    10.681k i/100ms
+IdempotentEnumerable     4.035k i/100ms
+Calculating -------------------------------------
+          Enumerable    112.134k (± 3.5%) i/s -    566.093k in   5.055148s
+IdempotentEnumerable     42.197k (± 4.1%) i/s -    213.855k in   5.078339s
+
+Comparison:
+          Enumerable:   112134.2 i/s
+IdempotentEnumerable:    42196.6 i/s - 2.66x  slower
+```
+
+## Author
+
+[Victor Shepelev](http://zverok.github.io/)
+
+## License
+
+MIT

data/benchmarks/set.rb

@@ -0,0 +1,17 @@
+require 'bundler/setup'
+require 'idempotent_enumerable'
+require 'set'
+require 'benchmark/ips'
+
+set1 = Set.new((1..100))
+class SetI < Set
+  include IdempotentEnumerable
+end
+set2 = SetI.new((1..100))
+
+Benchmark.ips do |x|
+  x.report('Enumerable') { set1.reject(&:odd?) }
+  x.report('IdempotentEnumerable') { set2.reject(&:odd?) }
+
+  x.compare!
+end

data/idempotent_enumerable.gemspec

@@ -0,0 +1,39 @@
+Gem::Specification.new do |s|
+  s.name     = 'idempotent_enumerable'
+  s.version  = '0.0.1'
+  s.authors  = ['Victor Shepelev']
+  s.email    = 'zverok.offline@gmail.com'
+  s.homepage = 'https://github.com/zverok/idempotent_enumerable'
+
+  s.summary = 'Like Enumerable but preserves original collection class'
+  s.description = <<-EOF
+    IdempotentEnumerable is like Enumerable, but tries to preserve original collection type when possible.
+  EOF
+  s.licenses = ['MIT']
+
+  s.required_ruby_version = '>= 2.1.0'
+
+  s.files = `git ls-files`.split($RS).reject do |file|
+    file =~ /^(?:
+    spec\/.*
+    |Gemfile
+    |Rakefile
+    |\.rspec
+    |\.gitignore
+    |\.rubocop.yml
+    |\.travis.yml
+    )$/x
+  end
+  s.require_paths = ["lib"]
+
+  s.add_development_dependency 'rubocop', '>= 0.50'
+  s.add_development_dependency 'rspec', '>= 3'
+  s.add_development_dependency 'rubocop-rspec', '>= 1.17.1'
+  s.add_development_dependency 'rspec-its', '~> 1'
+  s.add_development_dependency 'saharspec', '~> 0.0.2'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rubygems-tasks'
+  s.add_development_dependency 'yard'
+  s.add_development_dependency 'benchmark-ips'
+  s.add_development_dependency 'coveralls'
+end

data/lib/idempotent_enumerable.rb

@@ -0,0 +1,142 @@
+module IdempotentEnumerable
+  include Enumerable
+
+  def self.included(klass)
+    def klass.idempotent_enumerable
+      @idempotent_enumerable ||= Configurator.new(self)
+    end
+  end
+
+  %i[drop_while reject select sort_by take_while].each do |method|
+    define_method(method) do |*arg, &block|
+      return to_enum(method, *arg) unless block
+      idempotently_construct(each(*arg).send(method, &block))
+    end
+  end
+
+  alias find_all select
+
+  def chunk(*arg, &block)
+    # FIXME: should return enumerator
+    return to_enum(:chunk, *arg) unless block
+    each(*arg).chunk(&block).map { |key, group| [key, idempotently_construct(group)] }
+  end
+
+  if RUBY_VERSION >= '2.3.0'
+    def chunk_while(*arg, &block)
+      idempotent_enumerator(each(*arg).chunk_while(&block))
+    end
+  end
+
+  def drop(num, *arg)
+    idempotently_construct(each(*arg).drop(num))
+  end
+
+  def each_cons(num, *arg)
+    return to_enum(:each_cons, num, *arg) unless block_given?
+    each(*arg).each_cons(num) { |slice| yield(idempotently_construct(slice)) }
+  end
+
+  def each_slice(num, *arg)
+    return to_enum(:each_slice, num, *arg) unless block_given?
+    each(*arg).each_slice(num) { |slice| yield(idempotently_construct(slice)) }
+  end
+
+  def first(*arg)
+    arg, num = idempotent_split_arg(arg)
+    num ? idempotently_construct(each(*arg).first(*num)) : each(*arg).first
+  end
+
+  def grep(*arg, pattern, &block)
+    idempotently_construct(each(*arg).grep(pattern, &block))
+  end
+
+  if RUBY_VERSION >= '2.3.0'
+    def grep_v(pattern, *arg, &block)
+      idempotently_construct(each(*arg).grep_v(pattern, &block))
+    end
+  end
+
+  def group_by(*arg, &block)
+    each(*arg).group_by(&block).map { |key, val| [key, idempotently_construct(val)] }.to_h
+  end
+
+  def min(*arg)
+    arg, num = idempotent_split_arg(arg)
+    num ? idempotently_construct(each(*arg).min(*num)) : each(*arg).min
+  end
+
+  def min_by(*arg, &block)
+    return to_enum(:min_by, *arg) unless block
+    arg, num = idempotent_split_arg(arg)
+    num ? idempotently_construct(each(*arg).min_by(*num, &block)) : each(*arg).min_by(&block)
+  end
+
+  def max(*arg)
+    arg, num = idempotent_split_arg(arg)
+    num ? idempotently_construct(each(*arg).max(*num)) : each(*arg).max
+  end
+
+  def max_by(*arg, &block)
+    return to_enum(:max_by, *arg) unless block
+    arg, num = idempotent_split_arg(arg)
+    num ? idempotently_construct(each(*arg).max_by(*num, &block)) : each(*arg).max_by(&block)
+  end
+
+  def partition(*arg, &block)
+    return to_enum(:partition, *arg) unless block
+    each(*arg).partition(&block).map(&method(:idempotently_construct))
+  end
+
+  def slice_before(pattern = nil, &block)
+    idempotent_enumerator(pattern ? each.slice_before(pattern) : each.slice_before(&block))
+  end
+
+  if RUBY_VERSION >= '2.2'
+    def slice_after(pattern = nil, &block)
+      idempotent_enumerator(pattern ? each.slice_after(pattern) : each.slice_after(&block))
+    end
+
+    def slice_when(*arg, &block)
+      idempotent_enumerator(each(*arg).slice_when(&block))
+    end
+  end
+
+  def sort(*arg, &block)
+    idempotently_construct(each(*arg).sort(&block))
+  end
+
+  def take(num, *arg)
+    idempotently_construct(each(*arg).take(num))
+  end
+
+  if RUBY_VERSION >= '2.4.0'
+    def uniq(*arg, &block)
+      idempotently_construct(each(*arg).uniq(&block))
+    end
+  end
+
+  private
+
+  def idempotently_construct(array)
+    self.class.send(self.class.idempotent_enumerable.constructor, array)
+  end
+
+  def idempotent_enumerator(enumerator)
+    Enumerator.new { |y| enumerator.each { |chunk| y << idempotently_construct(chunk) } }
+  end
+
+  # For methods like min(), with optional argument (count of min elements), AND complex collections
+  # that have args for their #each method, we need to split args to "args to #each" and
+  # "args to #min".
+  #
+  # Doesn't work if #each has variable number of args, unfortunately.
+  #
+  def idempotent_split_arg(arg)
+    arity = method(:each).arity
+    return [arg] if arity < 0 || arg.count <= arity
+    [arg[0...arity], arg[arity..-1]]
+  end
+end
+
+require_relative 'idempotent_enumerable/configurator'

data/lib/idempotent_enumerable/configurator.rb

@@ -0,0 +1,34 @@
+module IdempotentEnumerable
+  class Configurator
+    attr_writer :constructor
+
+    def initialize(host)
+      @host = host
+    end
+
+    def constructor
+      @constructor || :new
+    end
+
+    REDEFINEABLE = %i[map flat_map collect collect_concat].freeze
+
+    def redefine_map!(only: REDEFINEABLE, all: nil)
+      (Array(only) & REDEFINEABLE).each { |method| redefine(method, all) }
+      self
+    end
+
+    private
+
+    def redefine(method, all)
+      @host.send(:define_method, method) do |*arg, &block|
+        return to_enum(method) unless block
+        res = each(*arg).send(method, &block)
+        if !all || res.all?(&all)
+          idempotently_construct(res)
+        else
+          res
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,190 @@
+--- !ruby/object:Gem::Specification
+name: idempotent_enumerable
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-10-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.50'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.17.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.17.1
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: saharspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.0.2
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: coveralls
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "    IdempotentEnumerable is like Enumerable, but tries to preserve original
+  collection type when possible.\n"
+email: zverok.offline@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop_todo.yml"
+- README.md
+- benchmarks/set.rb
+- idempotent_enumerable.gemspec
+- lib/idempotent_enumerable.rb
+- lib/idempotent_enumerable/configurator.rb
+homepage: https://github.com/zverok/idempotent_enumerable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.10
+signing_key: 
+specification_version: 4
+summary: Like Enumerable but preserves original collection class
+test_files: []