Document List.first :k,:kv,:p,:end

And remove documentation for first-index / last-index

Author: lizmat

doc/Type/List.pod

@@ -247,7 +247,9 @@ Defined as:
 Usage:
 
     grep MATCHER, LIST
+    grep MATCHER, LIST, :RETURN_AS
     LIST.grep(MATCHER)
+    LIST.grep(MATCHER, :RETURN_AS)
 
 Returns a sequence of elements against which C<$matcher> smart-matches.
 The elements are returned in the order in which they appear in the original
@@ -297,56 +299,51 @@ Examples:
 
 Defined as:
 
-    multi sub    first(Mu $matcher, *@elems)
-    multi method first(List:D:  Mu $matcher)
+    multi sub    first(Mu $matcher, *@elems, :k, :kv, :p, :end)
+    multi method first(List:D:  Mu $matcher, :k, :kv, :p, :end)
 
 Usage:
 
-    first MATCHER, LIST
-    LIST.first(MATCHER)
+    first MATCHER, LIST, :RETURN_AS, :FROM_END
+    LIST.first(MATCHER, :RETURN_AS, :FROM_END)
 
 Returns the first item of the list which smart-matches against C<$matcher>,
-fails when no values match.
+returns Nil when no values match.  The optional named parameter C<:end>
+indicates that the search should be from the B<end> of the list, rather than
+from the start.
 
 Examples:
 
-    say (1, 22/7, 42).first: * > 5;     # 42
-    say $f = ('hello', 1, 22/7, 42, 'world').first: Complex;
-    say $f.perl;                        #  Failure.new(exception => X::AdHoc.new(payload => "No values matched"))
+    say (1, 22/7, 42, 300).first: * > 5;                  # 42
+    say (1, 22/7, 42, 300).first: * > 5, :end;            # 300
+    say ('hello', 1, 22/7, 42, 'world').first: Complex;   # (Nil)
 
-=head2 routine first-index
-
-Defined as:
-
-    multi method first-index(List:D: Mu $matcher)
-
-Usage:
-
-    LIST.first-index(MATCHER)
-
-Returns the first index against which C<$matcher> smart-matches, or C<Nil> if
-no match was found.
+The optional named parameters C<:k>, C<:kv>, C<:p> provide the same
+functionality as on slices:
 
-Example:
+=over 4
 
-    say (1, 22/7, 42, 300, 72).first-index: * > 5;   # 2
+=item k
 
-=head2 routine last-index
+Return the index value of the matching element.  Index is always counted from
+the beginning of the list, regardless of whether the C<:end> named parameter
+is specified or not.
 
-Defined as:
+=item kv
 
-    multi method last-index(List:D: Mu $matcher)
+Return both the index and matched element.
 
-Usage:
+=item p
 
-    LIST.last-index(MATCHER)
+Return the index and the matched element as a C<Pair>.
 
-Returns the last index against which C<$matcher> smart-matches, or C<Nil> if
-no match was found.
+=back
 
-Example:
+Examples:
 
-    say (1, 22/7, 42, 300, 72).last-index: * > 5;   # 4
+    say (1, 22/7, 42, 300).first: * > 5, :k;        # 2
+    say (1, 22/7, 42, 300).first: * > 5, :p;        # 2 => 42
+    say (1, 22/7, 42, 300).first: * > 5, :kv, :end; # 3 300
 
 =head2 routine classify