[Python-checkins] r88348 - python/branches/py3k/Doc/howto/pyporting.rst

[antoine.pitrou]

Author: antoine.pitrou
Date: Sat Feb  5 13:13:38 2011
New Revision: 88348

Log:
Everybody hates this one :) (bytes indexing)



Modified:
   python/branches/py3k/Doc/howto/pyporting.rst

Modified: python/branches/py3k/Doc/howto/pyporting.rst
==============================================================================
--- python/branches/py3k/Doc/howto/pyporting.rst	(original)
+++ python/branches/py3k/Doc/howto/pyporting.rst	Sat Feb  5 13:13:38 2011
@@ -367,6 +367,37 @@
    BytesWarning: Comparison between bytes and string
 
 
+Indexing bytes objects
+''''''''''''''''''''''
+
+Another potentially surprising change is the indexing behaviour of bytes
+objects in Python 3::
+
+   >>> b"xyz"[0]
+   120
+
+Indeed, Python 3 bytes objects (as well as :class:`bytearray` objects)
+are sequences of integers.  But code converted from Python 2 will often
+assume that indexing a bytestring produces another bytestring, not an
+integer.  To reconcile both behaviours, use slicing::
+
+   >>> b"xyz"[0:1]
+   b'x'
+   >>> n = 1
+   >>> b"xyz"[n:n+1]
+   b'y'
+
+The only remaining gotcha is that an out-of-bounds slice returns an empty
+bytes object instead of raising ``IndexError``:
+
+   >>> b"xyz"[3]
+   Traceback (most recent call last):
+     File "<stdin>", line 1, in <module>
+   IndexError: index out of range
+   >>> b"xyz"[3:4]
+   b''
+
+
 ``__str__()``/``__unicode__()``
 '''''''''''''''''''''''''''''''
 In Python 2, objects can specify both a string and unicode representation of