module Benchmark

Initializes a benchmark Job, and yields the Job to the given block.

@example Benchmarking non-destructive operations

Benchmark.inputs(["abc", "aaa", "xyz", ""]) do |job|
  job.report("String#tr"){|string| string.tr("a", "A") }
  job.report("String#gsub"){|string| string.gsub(/a/, "A") }
  job.compare!
end

@example Benchmarking destructive operations

Benchmark.inputs(["abc", "aaa", "xyz", ""], dup_inputs: true) do |job|
  job.report("String#tr!"){|string| string.tr!("a", "A") }
  job.report("String#gsub!"){|string| string.gsub!(/a/, "A") }
  job.compare!
end

@param values [Array]

Input values to be individually yielded to all {Inputs::Job#report
+report+} blocks

@param options [Hash] @option options :dup_inputs [Boolean] (false)

Whether each of +values+ should be +dup+'d before being yielded to
a {Inputs::Job#report +report+} block.  This should be set to true
if any +report+ block destructively modifies its input.

@option options :sample_n [Integer] (10)

Number of samples to take when benchmarking

@option options :sample_dt [Integer] (200,000 ns)

Approximate duration of time each sample should take when
benchmarking, in nanoseconds

@yieldparam job [Benchmark::Inputs::Job] @return [Benchmark::Inputs::Job] @raise [ArgumentError]

if +values+ is empty

# File lib/benchmark/inputs.rb, line 38
def self.inputs(values, **options)
  job = Inputs::Job.new(values, **options)
  yield job
  job
end