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