Add re.fullmatch() function and regex.fullmatch() method, which anchor the

pattern at both ends of the string to match.

Patch by Matthew Barnett.
Closes #16203.

1 files changed, 28 insertions, 0 deletions

diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index 762ca49..9ea99a9 100644
--- a/Doc/library/re.rst
+++ b/Doc/library/re.rst
@@ -584,6 +584,16 @@ form.
    instead (see also :ref:`search-vs-match`).
 
 
+.. function:: fullmatch(pattern, string, flags=0)
+
+   If the whole *string* matches the regular expression *pattern*, return a
+   corresponding :ref:`match object <match-objects>`.  Return ``None`` if the
+   string does not match the pattern; note that this is different from a
+   zero-length match.
+
+   .. versionadded:: 3.4
+
+
 .. function:: split(pattern, string, maxsplit=0, flags=0)
 
    Split *string* by the occurrences of *pattern*.  If capturing parentheses are
@@ -778,6 +788,24 @@ attributes:
    :meth:`~regex.search` instead (see also :ref:`search-vs-match`).
 
 
+.. method:: regex.fullmatch(string[, pos[, endpos]])
+
+   If the whole *string* matches this regular expression, return a corresponding
+   :ref:`match object <match-objects>`.  Return ``None`` if the string does not
+   match the pattern; note that this is different from a zero-length match.
+
+   The optional *pos* and *endpos* parameters have the same meaning as for the
+   :meth:`~regex.search` method.
+
+   >>> pattern = re.compile("o[gh]")
+   >>> pattern.fullmatch("dog")      # No match as "o" is not at the start of "dog".
+   >>> pattern.fullmatch("ogre")     # No match as not the full string matches.
+   >>> pattern.fullmatch("doggie", 1, 3)   # Matches within given limits.
+   <_sre.SRE_Match object at ...>
+
+   .. versionadded:: 3.4
+
+
 .. method:: regex.split(string, maxsplit=0)
 
    Identical to the :func:`split` function, using the compiled pattern.