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)␤»
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)␤»