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