In List§

See primary documentation in context for routine first

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.

In Supply§

See primary documentation in context for method first

method first(Supply:D: :$end, |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 :end.

my $rand = supply { emit (rand × 100).floor for ^∞ };
my $first-prime = $rand.first: &is-prime;
# output the first prime from the endless random number supply $rand, 
# then the $first-prime supply reaches its end 
$first-prime.tap: &say;

In Any§

See primary documentation in context for routine first

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        first(Bool:D $t, |)
multi        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)␤»