Document the finditer() function and method.

This closes SF bug #520904.

Explain that many of the escapes supported by string literals are also
supported by the RE compiler, and list which ones.
This closes SF bug #529923.

1 files changed, 26 insertions, 2 deletions

diff --git a/Doc/lib/libre.tex b/Doc/lib/libre.tex
index 26fbb5e..ac2fc74 100644
--- a/Doc/lib/libre.tex
+++ b/Doc/lib/libre.tex
@@ -371,10 +371,23 @@ character properties database.
 
 \item[\code{\e Z}]Matches only at the end of the string.
 
-\item[\code{\e \e}] Matches a literal backslash.
-
 \end{list}
 
+Most of the standard escapes supported by Python string literals are
+also accepted by the regular expression parser:
+
+\begin{verbatim}
+\a      \b      \f      \n
+\r      \t      \v      \x
+\\
+\end{verbatim}
+
+Note that octal escapes are not included.  While the parser can
+attempt to determine whether a character is being specified by it's
+ordinal value expressed in octal, doing so yields an expression which
+is relatively difficult to maintain, as the same syntax is used to
+refer to numbered groups.
+
 
 \subsection{Matching vs. Searching \label{matching-searching}}
 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
@@ -544,6 +557,13 @@ ignored.
   \versionadded{1.5.2}
 \end{funcdesc}
 
+\begin{funcdesc}{finditer}{pattern, string}
+  Return an iterator over all non-overlapping matches for the RE
+  \var{pattern} in \var{string}.  For each match, the iterator returns
+  a match object.  Empty matches are included in the result.
+  \versionadded{2.2}
+\end{funcdesc}
+
 \begin{funcdesc}{sub}{pattern, repl, string\optional{, count}}
   Return the string obtained by replacing the leftmost non-overlapping
   occurrences of \var{pattern} in \var{string} by the replacement
@@ -670,6 +690,10 @@ Identical to the \function{split()} function, using the compiled pattern.
 Identical to the \function{findall()} function, using the compiled pattern.
 \end{methoddesc}
 
+\begin{methoddesc}[RegexObject]{finditer}{string}
+Identical to the \function{finditer()} function, using the compiled pattern.
+\end{methoddesc}
+
 \begin{methoddesc}[RegexObject]{sub}{repl, string\optional{, count\code{ = 0}}}
 Identical to the \function{sub()} function, using the compiled pattern.
 \end{methoddesc}