Documentation for routine first assembled from the following types:

class List

From List

(List) routine first

Defined as:

sub    first(Mu $matcher, *@elems, :$k, :$kv, :$p, :$end)
method first(List:D:  Mu $matcher?, :$k, :$kv, :$p, :$end)

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.

class Any

From Any

(Any) method first

Defined as:

multi method first(Bool:D $t)
multi method first(Regex:D $test, :$end, *%a)
multi method first(Callable:D $test, :$end, *%a is copy)
multi method first(Mu $test, :$end, *%a)
multi method first(:$end, *%a)
multi sub first(Bool:D $t, |)
multi sub first(Mu $test, +values, *%a)

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