Added information on the use of Unicode with the StringIO and cStringIO

modules, otherwise the behavior is just plain confusing.

1 files changed, 14 insertions, 2 deletions

diff --git a/Doc/lib/libstringio.tex b/Doc/lib/libstringio.tex
index 332bdf1..3b92ba1 100644
--- a/Doc/lib/libstringio.tex
+++ b/Doc/lib/libstringio.tex
@@ -7,13 +7,19 @@
 
 This module implements a file-like class, \class{StringIO},
 that reads and writes a string buffer (also known as \emph{memory
-files}). See the description on file objects for operations (section
+files}).  See the description of file objects for operations (section
 \ref{bltin-file-objects}).
 
 \begin{classdesc}{StringIO}{\optional{buffer}}
 When a \class{StringIO} object is created, it can be initialized
 to an existing string by passing the string to the constructor.
 If no string is given, the \class{StringIO} will start empty.
+
+The \class{StringIO} object can accept either Unicode or 8-bit
+strings, but mixing the two may take some care.  If both are used,
+8-bit strings that cannot be interpreted as 7-bit \ASCII{} (i.e., that
+use the 8th bit) will cause a \exception{UnicodeError} to be raised
+when \method{getvalue()} is called.
 \end{classdesc}
 
 The following methods of \class{StringIO} objects require special
@@ -21,7 +27,9 @@ mention:
 
 \begin{methoddesc}{getvalue}{}
 Retrieve the entire contents of the ``file'' at any time before the
-\class{StringIO} object's \method{close()} method is called.
+\class{StringIO} object's \method{close()} method is called.  See the
+note above for information about mixing Unicode and 8-bit strings;
+such mixing can cause this method to raise \exception{UnicodeError}.
 \end{methoddesc}
 
 \begin{methoddesc}{close}{}
@@ -47,6 +55,10 @@ Since this module provides a factory function which returns objects of
 built-in types, there's no way to build your own version using
 subclassing.  Use the original \refmodule{StringIO} module in that case.
 
+Unlike the memory files implemented by the \refmodule{StringIO}
+module, those provided by this module are not able to accept Unicode
+strings that cannot be encoded as plain \ASCII{} strings.
+
 The following data objects are provided as well: