Thomas Wouters <thomas@xs4all.net>:

Reference manual docs for augmented assignment.

This closes SourceForge patch #101418.

Doc/ref/ref6.tex

@@ -9,6 +9,7 @@ by semicolons.  The syntax for simple statements is:
 simple_stmt:    expression_stmt
               | assert_stmt
               | assignment_stmt
+              | augmented_assignment_stmt
               | pass_stmt
               | del_stmt
               | print_stmt
@@ -247,6 +248,44 @@ print x
 \end{verbatim}
 
 
+\subsection{Augmented Assignment statements \label{augassign}}
+
+Augmented assignment is the combination, in a single statement, of a binary
+operation and an assignment statement:
+\indexii{augmented}{assignment}
+\index{statement!assignment, augmented}
+
+\begin{verbatim}
+augmented_assignment_stmt: target augop expression_list
+augop:           "+=" | "-=" | "*=" | "/=" | "%=" | "**="
+               | ">>=" | "<<=" | "&=" | "^=" | "|="
+target:          identifier | "(" target_list ")" | "[" target_list "]"
+               | attributeref | subscription | slicing
+\end{verbatim}
+
+(See section \ref{primaries} for the syntax definitions for the last
+three symbols.)
+
+An augmented assignment evaluates the target (which, unlike with normal
+assignment statements, cannot be a tuple) and the expression list, performs
+the binary operation specific to the type of assignment on the two operands,
+and assigns the result to the original target. The target is only evaluated
+once.
+
+An augmented assignment expression like \code{x += 1} can be rewritten as
+\code{x = x + 1} to achieve a similar, but not exactly equal effect. In the
+augmented version, \code{x} is only evaluated once. Also, when possible, the
+actual operation is performed \emph{in-place}, meaning that rather than
+creating a new object and assigning that to the target, the old object is
+modified instead.
+
+With the exception of assigning to tuples and multiple targets in a single
+statement, the assignment done by augmented assignment statements is handled
+the same way as normal assignments. Similarly, with the exception of the
+possible \emph{in-place} behaviour, the binary operation performed by
+augmented assignment is the same as the normal binary operations.
+
+
 \section{The \keyword{pass} statement \label{pass}}
 \stindex{pass}