[pypy-svn] r18745 - pypy/dist/pypy/doc

[arigo at codespeak.net]

Author: arigo
Date: Tue Oct 18 23:03:16 2005
New Revision: 18745

Modified:
   pypy/dist/pypy/doc/coding-guide.txt
Log:
Precised the RPython rules for the usage of indices in lists.  Half of these
rules could be lifted for clarity at the expense of a very small slow-down to
check them at run-time.  The other half are limitations of the RTyper, which
could also be removed.  The risk in the latter case is that user code would
silently start using the slower version instead of failing to translate, even
when a small effort from the programmer would be enough to convince the
Annotator/RTyper that the fast version works as well.



Modified: pypy/dist/pypy/doc/coding-guide.txt
==============================================================================
--- pypy/dist/pypy/doc/coding-guide.txt	(original)
+++ pypy/dist/pypy/doc/coding-guide.txt	Tue Oct 18 23:03:16 2005
@@ -149,22 +149,26 @@
 
 **lists**
 
-  lists are used as an allocated array; list.append() does naive resizing, so as
-  far as possible use list comprehensions (see below).  list.extend() or the +=
-  operator are allowed and efficient.  
-  Repetition via `*` or `*=` is fully supported as well.
+  lists are used as an allocated array.  Lists are over-allocated, so list.append()
+  is reasonably fast.  Negative or out-of-bound indexes are only allowed for the
+  most common operations, as follows:
 
-  - *indexing*
-    negative indexes are disallowed. Indexes are checked when requested
+  - *indexing*:
+    positive and negative indexes are allowed. Indexes are checked when requested
     by an IndexError exception clause.
   
-  - *slicing*
-    the slice start must be within bounds. The stop doesn't need to.
-    Negative indexes are disallowed, except for the [:-1] special case.
-
-  - *insert*
-    the index must be withing bounds (not checked) and must not be negative
-    (checked at compile-time).
+  - *slicing*:
+    the slice start must be within bounds. The stop doesn't need to, but it must
+    not be smaller than the start.  All negative indexes are disallowed, except for
+    the [:-1] special case.  No step.
+
+  - *other operators*:
+    ``+``, ``+=``, ``in``, ``*``, ``*=``, ``==``, ``!=`` work as expected.
+
+  - *methods*:
+    append, index, insert, extend, reverse, pop.  The index used in pop() follows
+    the same rules as for *indexing* above.  The index used in insert() must be within
+    bounds and not negative.
 
 **dicts**