txt: ## first.md
  first
  
  Combined from primary sources listed below.
  
  # [In List](#___top "go to top of document")[§](#(List)_routine_first "direct link")
  
  See primary documentation
  [in context](/type/List#routine_first)
  for **routine first**.
  
  ```raku
  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`](/type/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:
  
  ```raku
  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`](/type/Pair).
  
  Examples:
  
  ```raku
  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`](/routine/head) and [`tail`](/routine/tail) methods.
  
  # [In Any](#___top "go to top of document")[§](#(Any)_routine_first "direct link")
  
  See primary documentation
  [in context](/type/Any#routine_first)
  for **routine first**.
  
  ```raku
  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`](/routine/list) method and uses [`List.first`](/type/List#routine_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`](/type/Bool) as the argument will always return a [`Failure`](/type/Failure). The form that uses a `$test` will return the first element that smartmatches it, starting from the end if `:end` is used.
  
  ```raku
  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`](/type/Callable) multi:
  
  ```raku
  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`](/type/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`](/type/Junction):
  
  ```raku
  say (⅓,⅔…30).first( 3 | 33, :kv ); # OUTPUT: «(8 3)␤»
  ```
  
  # [In Supply](#___top "go to top of document")[§](#(Supply)_method_first "direct link")
  
  See primary documentation
  [in context](/type/Supply#method_first)
  for **method first**.
  
  ```raku
  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`.
  
  ```raku
  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;
  ```
  