Add "none" style to cmpthese(), alter result

Message-ID: <20011112110733.B7626@sizzle.whoville.com>

p4raw-id: //depot/perl@12956

diff --git a/lib/Benchmark.pm b/lib/Benchmark.pm
index 4d3b3e2..51ff8b3 100644 (file)
--- a/lib/Benchmark.pm
+++ b/lib/Benchmark.pm
@@ -196,17 +196,48 @@ Clear all cached times.
 
 =item cmpthese ( COUT, CODEHASHREF, [ STYLE ] )
 
-=item cmpthese ( RESULTSHASHREF )
+=item cmpthese ( RESULTSHASHREF, [ STYLE ] )
 
-Optionally calls timethese(), then outputs comparison chart.  This 
-chart is sorted from slowest to fastest, and shows the percent 
-speed difference between each pair of tests.  Can also be passed 
-the data structure that timethese() returns:
+Optionally calls timethese(), then outputs comparison chart.  This:
 
-    $results = timethese( .... );
+    cmpthese( -1, { a => "++\$i", b => "\$i *= 2" } ) ;
+
+outputs a chart like:
+
+           Rate    b    a
+    b 2831802/s   -- -61%
+    a 7208959/s 155%   --
+
+This chart is sorted from slowest to fastest, and shows the percent speed
+difference between each pair of tests.
+
+c<cmpthese> can also be passed the data structure that timethese() returns:
+
+    $results = timethese( -1, { a => "++\$i", b => "\$i *= 2" } ) ;
     cmpthese( $results );
 
-Returns the data structure returned by timethese() (or passed in).
+in case you want to see both sets of results.
+
+Returns a reference to an ARRAY of rows, each row is an ARRAY of cells from the
+above chart, including labels. This:
+
+    my $rows = cmpthese( -1, { a => '++$i', b => '$i *= 2' }, "none" );
+
+returns a data structure like:
+
+    [
+        [ '',       'Rate',   'b',    'a' ],
+        [ 'b', '2885232/s',  '--', '-59%' ],
+        [ 'a', '7099126/s', '146%',  '--' ],
+    ]
+
+B<NOTE>: This result value differs from previous versions, which returned
+the C<timethese()> result structure.  If you want that, just use the two
+statement C<timethese>...C<cmpthese> idiom shown above.
+
+Incidently, note the variance in the result values between the two examples;
+this is typical of benchmarking.  If this were a real benchmark, you would
+probably want to run a lot more iterations.
 
 =item countit(TIME, CODE)
 
@@ -661,10 +692,9 @@ sub timethese{
 }
 
 sub cmpthese{
-    my $results = ref $_[0] ? $_[0] : timethese( @_ );
+    my ($results, $style) = ref $_[0] ? @_ : ( timethese( @_[0,1] ), $_[2] ) ;
 
-    return $results
-       if defined $_[2] && $_[2] eq 'none';
+    $style = "" unless defined $style;
 
     # Flatten in to an array of arrays with the name as the first field
     my @vals = map{ [ $_, @{$results->{$_}} ] } keys %$results;
@@ -760,6 +790,8 @@ sub cmpthese{
        push @rows, \@row;
     }
 
+    return \@rows if $style eq "none";
+
     # Equalize column widths in the chart as much as possible without
     # exceeding 80 characters.  This does not use or affect cols 0 or 1.
     my @sorted_width_refs = 
@@ -791,7 +823,7 @@ sub cmpthese{
        printf $format, @$_;
     }
 
-    return $results;
+    return \@rows ;
 }