add vsearch example

Addresses <http://sourceforge.net/p/pdl/bugs/359>, <#43>.
PDLPorters · Mar 3, 2015 · 444ce66 · 444ce66
1 parent aedd1ea
commit 444ce66
Showing 1 changed file with 56 additions and 4 deletions.
diff --git a/Basic/Primitive/primitive.pd b/Basic/Primitive/primitive.pd
@@ -2263,18 +2263,18 @@ insertion point which still leaves the piddle sorted.
 invoke B<vsearch_insert_rightmost>, returning the right-most possible
 insertion point which still leaves the piddle sorted.
 
-=item C<insert_match>
+=item C<match>
 
 invoke B<vsearch_match>, returning the index of a matching element,
 else -(insertion point + 1)
 
-=item C<insert_bin_inclusive>
+=item C<bin_inclusive>
 
 invoke B<vsearch_bin_inclusive>, returning an index appropriate for binning
 on a grid where the left bin edges are I<inclusive> of the bin. See
 below for further explanation of the bin.
 
-=item C<insert_bin_exclusive>
+=item C<bin_exclusive>
 
 invoke B<vsearch_bin_exclusive>, returning an index appropriate for binning
 on a grid where the left bin edges are I<exclusive> of the bin. See
@@ -2284,6 +2284,58 @@ below for further explanation of the bin.
 
 The default value of C<mode> is C<sample>.
 
+=for example
+
+  use PDL;
+
+  my @modes = qw( sample insert_leftmost insert_rightmost match
+                  bin_inclusive bin_exclusive );
+
+  # Generate a sequence of 3 zeros, 3 ones, ..., 3 fours.
+  my $x = zeroes(3,5)->yvals->flat;
+
+  for my $mode ( @modes ) {
+    # if the value is in $x
+    my $contained = 2;
+    my $idx_contained = vsearch( $contained, $x, { mode => $mode } );
+    my $x_contained = $x->copy;
+    $x_contained->slice( $idx_contained ) .= 9;
+
+    # if the value is not in $x
+    my $not_contained = 1.5;
+    my $idx_not_contained = vsearch( $not_contained, $x, { mode => $mode } );
+    my $x_not_contained = $x->copy;
+    $x_not_contained->slice( $idx_not_contained ) .= 9;
+
+    print sprintf("%-23s%30s\n", '$x', $x);
+    print sprintf("%-23s%30s\n",   "$mode ($contained)", $x_contained);
+    print sprintf("%-23s%30s\n\n", "$mode ($not_contained)", $x_not_contained);
+  }
+
+  # $x                     [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
+  # sample (2)             [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
+  # sample (1.5)           [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
+  # 
+  # $x                     [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
+  # insert_leftmost (2)    [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
+  # insert_leftmost (1.5)  [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
+  # 
+  # $x                     [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
+  # insert_rightmost (2)   [0 0 0 1 1 1 2 2 2 9 3 3 4 4 4]
+  # insert_rightmost (1.5) [0 0 0 1 1 1 9 2 2 3 3 3 4 4 4]
+  # 
+  # $x                     [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
+  # match (2)              [0 0 0 1 1 1 2 9 2 3 3 3 4 4 4]
+  # match (1.5)            [0 0 0 1 1 1 2 2 9 3 3 3 4 4 4]
+  # 
+  # $x                     [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
+  # bin_inclusive (2)      [0 0 0 1 1 1 2 2 9 3 3 3 4 4 4]
+  # bin_inclusive (1.5)    [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
+  # 
+  # $x                     [0 0 0 1 1 1 2 2 2 3 3 3 4 4 4]
+  # bin_exclusive (2)      [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
+  # bin_exclusive (1.5)    [0 0 0 1 1 9 2 2 2 3 3 3 4 4 4]
+
 =cut
 
 sub vsearch {
@@ -2539,7 +2591,7 @@ for my $func ( [
         },
     ],
     [
-        # x[i] is the INnclusive left edge of the bin
+        # x[i] is the INclusive left edge of the bin
         # return i, s.t. x[i] <= value < x[i+1].
         # returns -1 if x[0] > value
         # returns N-1 if x[-1] <= value