polish finish_in_order

[grosser]

• update docs
• fix code
• simplify code
• document code
• make test check for index + result too
• reduce memory usage
  followup to Add :finish_in_order option #339

[shaicoleman]

A nested array is inefficient, and requires significantly more memory allocations.
The rest of the changes look good to me

# gem install benchmark-memory
require 'benchmark/memory'

Benchmark.memory do |x|
  Pair = Struct.new(:a, :b)

  x.report('two arrays') do
   array_1 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
   array_2 = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 end
  x.report('hash') do
    hash = { 1 => 1, 2 => 2, 3 => 3, 4 => 4, 5 => 5, 6 => 6, 7 => 7, 8 => 8, 9 => 9, 10 => 10 }
  end
  x.report('nested array') do
    array = [[1, 1], [2, 2], [3, 3], [4, 4], [5, 5], [6, 6], [7, 7], [8, 8], [9, 9], [10, 10]]
  end
  x.report('struct') do
    array = [Pair.new(1, 1), Pair.new(2, 2), Pair.new(3, 3), Pair.new(4, 4), Pair.new(5, 5), 
             Pair.new(6, 6), Pair.new(7, 7), Pair.new(8, 8), Pair.new(9, 9), Pair.new(10, 10)]
  end
  x.compare!
end

Comparison:
          two arrays:         80 allocated
                hash:        512 allocated - 6.40x more
        nested array:        560 allocated - 7.00x more
              struct:        560 allocated - 7.00x more

[grosser]

hehe nice! :D

I think it's not as easy to benchmark since we are doing lots of array expansions too,
but agree that most likely 2 arrays are the most efficient way ... just a bit ugly, I'll take another look

[grosser]

I did not find a clean way of using less arrays.
being able to do break unless (done = options[:finish_done][i]) is kinda neat
otherwise I have to have 3 arrays, 1 for result, 1 for item, 1 for "done" which kinda sucks
and if I use a hash and check for key? then that's also more computation

... keeping it clean/simple until someone else has a nice idea or need for this 🤷

[grosser]

1.24.0