This is an automatically generated page and cannot be edited directly. Text in Composite pages, (URLs starting with 'routine' or 'syntax') can be edited by clicking on the link labeled 'in context', and editing the text there.

Exit this popup by pressing <Escape>, or clicking on X or on the background.

match
Combined from primary sources listed below.

In Cool§

See primary documentation in context for method match. 

method match(Cool:D: $target, *%adverbs)

Coerces the invocant to Stringy and calls the method match on it.

In Str§

See primary documentation in context for method match. 

method match($pat, :continue(:$c), :pos(:$p), :global(:$g), :overlap(:$ov), :exhaustive(:$ex), :st(:$nd), :rd(:$th), :$nth, :$x --> Match)

Performs a match of the string against $pat and returns a Match object if there is a successful match; it returns (Any) otherwise. Matches are stored in the default match variable $/. If $pat is not a Regex object, match will coerce the argument to a Str and then perform a literal match against $pat.

A number of optional named parameters can be specified, which alter how the match is performed.

  • :continue

The :continue adverb takes as an argument the position where the regex should start to search. If no position is specified for :c it will default to 0 unless $/ is set, in which case it defaults to $/.to.

  • :pos

Takes a position as an argument. Fails if regex cannot be matched from that position, unlike :continue.

  • :global

Instead of searching for just one match and returning a Match object, search for every non-overlapping match and return them in a List.

  • :overlap

Finds all matches including overlapping matches, but only returns one match from each starting position.

  • :exhaustive

Finds all possible matches of a regex, including overlapping matches and matches that start at the same position.

  • :st, :nd, :rd, :nth

Returns the nth match in the string. The argument can be a Numeric or an Iterable producing monotonically increasing numbers (that is, the next produced number must be larger than the previous one). The Iterable will be lazily reified and if non-monotonic sequence is encountered an exception will be thrown.

If Iterable argument is provided the return value and $/ variable will be set to a possibly-empty List of Match objects.

  • :x

Takes as an argument the number of matches to return, stopping once the specified number of matches has been reached. The value must be a Numeric or a Range; other values will cause .match to return a Failure containing an X::Str::Match::x exception.

Examples:

say "properly".match('perl');                     # OUTPUT: «｢perl｣␤»
say "properly".match(/p.../);                     # OUTPUT: «｢prop｣␤»
say "1 2 3".match([1,2,3]);                       # OUTPUT: «｢1 2 3｣␤»
say "a1xa2".match(/a./, :continue(2));            # OUTPUT: «｢a2｣␤»
say "abracadabra".match(/ a .* a /, :exhaustive);
# OUTPUT: «(｢abracadabra｣ ｢abracada｣ ｢abraca｣ ｢abra｣ ｢acadabra｣ ｢acada｣ ｢aca｣ ｢adabra｣ ｢ada｣ ｢abra｣)␤»
say 'several words here'.match(/\w+/,:global);    # OUTPUT: «(｢several｣ ｢words｣ ｢here｣)␤»
say 'abcdef'.match(/.*/, :pos(2));                # OUTPUT: «｢cdef｣␤»
say "foo[bar][baz]".match(/../, :1st);            # OUTPUT: «｢fo｣␤»
say "foo[bar][baz]".match(/../, :2nd);            # OUTPUT: «｢o[｣␤»
say "foo[bar][baz]".match(/../, :3rd);            # OUTPUT: «｢ba｣␤»
say "foo[bar][baz]".match(/../, :4th);            # OUTPUT: «｢r]｣␤»
say "foo[bar][baz]bada".match('ba', :x(2));       # OUTPUT: «(｢ba｣ ｢ba｣)␤»