Perl 6 Documentationroutine first
Documentation for routine first assembled from the following types:
class Any
From Any
(Any) method first
Defined as:
multi method first(Bool )multi method first(Regex , :, *)multi method first(Callable , :, * is copy)multi method first(Mu , :, *)multi method first(:, *)multi sub first(Bool , |)multi sub first(Mu , +values, *)
In general, coerces the invocant to a list by applying its .list method and uses List.first on it.
However, this is a multi with different signatures, which are implemented with (slightly) different behavior, although using it as a subroutine is equivalent to using it as a method with the second argument as the object.
For starters, using a Bool as the argument will always return a Failure. The form that uses a $test will return the first element that smartmatches it, starting from the end if :end is used.
say (3..33).first; # OUTPUT: «3»say (3..33).first(:end); # OUTPUT: «33»say (⅓,⅔…30).first( 0xF ); # OUTPUT: «15»say first 0xF, (⅓,⅔…30); # OUTPUT: «15»say (3..33).first( /\d\d/ ); # OUTPUT: «10»
The third and fourth examples use the Mu $test forms which smartmatches and returns the first element that does. The last example uses as a test a regex for numbers with two figures, and thus the first that meets that criterion is number 10. This last form uses the Callable multi:
say (⅓,⅔…30).first( * %% 11, :end, :kv ); # OUTPUT: «(65 22)»
Besides, the search for first will start from the :end and returns the set of key/values in a list; the key in this case is simply the position it occupies in the Seq. The :kv argument, which is part of the %a argument in the definitions above, modifies what first returns, providing it as a flattened list of keys and values; for a listy object, the key will always be the index.
From version 6.d, the test can also be a Junction:
say (⅓,⅔…30).first( 3 | 33, :kv ); # OUTPUT: «(8 3)»
class List
From List
(List) routine first
Defined as:
sub first(Mu , *, :, :, :, :)method first(List: Mu ?, :, :, :, :)
Returns the first item of the list which smartmatches against $matcher, returns Nil when no values match. The optional named parameter :end indicates that the search should be from the end of the list, rather than from the start.
Examples:
say (1, 22/7, 42, 300).first: * > 5; # OUTPUT: «42»say (1, 22/7, 42, 300).first: * > 5, :end; # OUTPUT: «300»say ('hello', 1, 22/7, 42, 'world').first: Complex; # OUTPUT: «Nil»
The optional named parameters :k, :kv, :p provide the same functionality as on slices:
k
Return the index value of the matching element. Index is always counted from the beginning of the list, regardless of whether the :end named parameter is specified or not.
kv
Return both the index and matched element.
p
Return the index and the matched element as a Pair.
Examples:
say (1, 22/7, 42, 300).first: * > 5, :k; # OUTPUT: «2»say (1, 22/7, 42, 300).first: * > 5, :p; # OUTPUT: «2 => 42»say (1, 22/7, 42, 300).first: * > 5, :kv, :end; # OUTPUT: «(3 300)»
In method form, the $matcher can be omitted, in which case the first available item (or last if :end is set) will be returned. See also head and tail methods.