[Python-checkins] cpython (2.7): Issue #23406: Clarify documentation on multiplying a sequence

[martin.panter]

https://hg.python.org/cpython/rev/6c222848badd
changeset:   97716:6c222848badd
branch:      2.7
user:        Martin Panter <vadmium>
date:        Mon Sep 07 01:40:33 2015 +0000
summary:
  Issue #23406: Clarify documentation on multiplying a sequence

Patch from Matheus Vieira Portela.

files:
  Doc/faq/programming.rst  |   2 ++
  Doc/library/stdtypes.rst |  15 +++++++++------
  Misc/ACKS                |   1 +
  3 files changed, 12 insertions(+), 6 deletions(-)


diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -1280,6 +1280,8 @@
 usually a lot slower than using Python lists.
 
 
+.. _faq-multidimensional-list:
+
 How do I create a multidimensional list?
 ----------------------------------------
 
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -736,8 +736,8 @@
 | ``s + t``        | the concatenation of *s* and   | \(6)     |
 |                  | *t*                            |          |
 +------------------+--------------------------------+----------+
-| ``s * n, n * s`` | *n* shallow copies of *s*      | \(2)     |
-|                  | concatenated                   |          |
+| ``s * n, n * s`` | equivalent to adding *s* to    | \(2)     |
+|                  | itself *n* times               |          |
 +------------------+--------------------------------+----------+
 | ``s[i]``         | *i*\ th item of *s*, origin 0  | \(3)     |
 +------------------+--------------------------------+----------+
@@ -789,9 +789,9 @@
 
 (2)
    Values of *n* less than ``0`` are treated as ``0`` (which yields an empty
-   sequence of the same type as *s*).  Note also that the copies are shallow;
-   nested structures are not copied.  This often haunts new Python programmers;
-   consider:
+   sequence of the same type as *s*).  Note that items in the sequence *s*
+   are not copied; they are referenced multiple times.  This often haunts
+   new Python programmers; consider:
 
       >>> lists = [[]] * 3
       >>> lists
@@ -801,7 +801,7 @@
       [[3], [3], [3]]
 
    What has happened is that ``[[]]`` is a one-element list containing an empty
-   list, so all three elements of ``[[]] * 3`` are (pointers to) this single empty
+   list, so all three elements of ``[[]] * 3`` are references to this single empty
    list.  Modifying any of the elements of ``lists`` modifies this single list.
    You can create a list of different lists this way:
 
@@ -812,6 +812,9 @@
       >>> lists
       [[3], [5], [7]]
 
+   Further explanation is available in the FAQ entry
+   :ref:`faq-multidimensional-list`.
+
 (3)
    If *i* or *j* is negative, the index is relative to the end of the string:
    ``len(s) + i`` or ``len(s) + j`` is substituted.  But note that ``-0`` is still
diff --git a/Misc/ACKS b/Misc/ACKS
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -1084,6 +1084,7 @@
 Iustin Pop
 Claudiu Popa
 John Popplewell
+Matheus Vieira Portela
 Davin Potts
 Guillaume Pratte
 Florian Preinstorfer

-- 
Repository URL: https://hg.python.org/cpython