From cfad54344f570c1e833d92289ac571da7315b164 Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sat, 10 Oct 2015 03:01:20 +0000 Subject: Issue #22413: Document newline effect on StringIO initializer and getvalue Also add to comment in the C code. --- Doc/library/io.rst | 16 ++++++++++++---- Modules/_io/_iomodule.h | 7 ++++++- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/Doc/library/io.rst b/Doc/library/io.rst index 9b12045..592bc48 100644 --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -864,10 +864,16 @@ Text I/O An in-memory stream for text I/O. The text buffer is discarded when the :meth:`~IOBase.close` method is called. - The initial value of the buffer (an empty string by default) can be set by - providing *initial_value*. The *newline* argument works like that of - :class:`TextIOWrapper`. The default is to consider only ``\n`` characters - as end of lines and to do no newline translation. + The initial value of the buffer can be set by providing *initial_value*. + If newline translation is enabled, newlines will be encoded as if by + :meth:`~TextIOBase.write`. The stream is positioned at the start of + the buffer. + + The *newline* argument works like that of :class:`TextIOWrapper`. + The default is to consider only ``\n`` characters as ends of lines and + to do no newline translation. If *newline* is set to ``None``, + newlines are written as ``\n`` on all platforms, but universal + newline decoding is still performed when reading. :class:`StringIO` provides this method in addition to those from :class:`TextIOBase` and its parents: @@ -875,6 +881,8 @@ Text I/O .. method:: getvalue() Return a ``str`` containing the entire contents of the buffer. + Newlines are decoded as if by :meth:`~TextIOBase.read`, although + the stream position is not changed. Example usage:: diff --git a/Modules/_io/_iomodule.h b/Modules/_io/_iomodule.h index 8927864..140f260 100644 --- a/Modules/_io/_iomodule.h +++ b/Modules/_io/_iomodule.h @@ -52,7 +52,12 @@ extern PyObject *_PyIncrementalNewlineDecoder_decode( which can be safely put aside until another search. NOTE: for performance reasons, `end` must point to a NUL character ('\0'). - Otherwise, the function will scan further and return garbage. */ + Otherwise, the function will scan further and return garbage. + + There are three modes, in order of priority: + * translated: Only find \n (assume newlines already translated) + * universal: Use universal newlines algorithm + * Otherwise, the line ending is specified by readnl, a str object */ extern Py_ssize_t _PyIO_find_line_ending( int translated, int universal, PyObject *readnl, int kind, char *start, char *end, Py_ssize_t *consumed); -- cgit v0.12