Documentation for routine
first assembled from the following types:
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, *)
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
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
: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
say (⅓,⅔…30).first( 3 | 33, :kv ); # OUTPUT: «(8 3)␤»
method first(Supply: :, |c)
This method creates a supply of the first element, or the last element if the optional named parameter
:end is truthy, from a supply created by calling the
grep method on the invocant, with any remaining arguments as parameters. If there is no remaining argument, this method is equivalent to calling on the invocant, without parameter, the
head or the
tail method, according to named parameter
my = supply ;my = .first: ;# output the first prime from the endless random number supply $rand,# then the $first-prime supply reaches its end.tap: ;
sub first(Mu , *, :, :, :, :)method first(List: Mu ?, :, :, :, :)
Returns the first item of the list which smartmatches against
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.
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
:p provide the same functionality as on slices:
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.
Return both the index and matched element.
Return the index and the matched element as a
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)␤»