Merge pull request #1074 from ahalbert/master

Wrote documentation for Str method match

doc/Type/Str.pod6

@@ -166,7 +166,59 @@ Examples:
 
     method match($pat, :continue(:$c), :pos(:$p), :global(:$g), :overlap(:$ov), :exhaustive(:$ex), :st(:$nd), :rd(:$th), :$nth, :$x --> Match)
 
-TODO
+Performs a match of the string against C<$pat> and returns a L<Match> object if there is a successful match,
+and C<(Any)> otherwise. Matches are stored in C<$/>. If C<$pat> is not a L<Regex> object, match will coerce 
+the argument to a Str and then perform a literal match against C<$pat>. 
+
+A number of optional named parameters can be specified, which alter how the match is performed.
+
+=item :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.
+
+=item :pos
+
+Takes a position as an argument. Fails if regex cannot be matched from that position, unlike :continue.
+
+=item :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. 
+
+=item :overlap
+
+Finds all matches including overlapping matches, but only returns one match from each starting position. 
+
+=item :exhaustive
+
+Finds all possible matches of a regex, including overlapping matches and matches that start at the same position.
+
+=item :st, :nd, rd, nth
+
+Takes an integer as an argument and returns the nth match in the string. 
+
+=item :x
+
+Takes as an argument the number of matches to return, stopping once the specified number of matches has been reached.
+
+Examples:
+=begin code
+
+say "properly".match('perl'); # ｢perl｣
+say "properly".match(/p.../); # ｢perl｣
+say "1 2 3".match([1,2,3]); # ｢1 2 3｣
+say "a1xa2".match(/a./, :continue(2)) #｢a2｣
+say "abracadabra".match(/ a .* a /, :exhaustive); #(｢abracadabra｣ ｢abracada｣ ｢abraca｣ ｢abra｣ ｢acadabra｣ ｢acada｣ ｢aca｣ ｢adabra｣ ｢ada｣ ｢abra｣)
+say 'several words here'.match(/\w+/,:global) #(｢several｣ ｢words｣ ｢here｣)
+say 'abcdef'.match(/.*/, :pos(2)) #｢cdef｣
+say "foo[bar][baz]".match(/../, :1st); # ｢fo｣
+say "foo[bar][baz]".match(/../, :2nd); # ｢o[｣
+say "foo[bar][baz]".match(/../, :3rd); # ｢ba｣
+say "foo[bar][baz]".match(/../, :4th); # ｢r]｣
+say "foo[bar][baz]bada".match('ba', :x(2)); # (｢ba｣ ｢ba｣)
+
+=end code
+
 
 =head2 routine parse-base