diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/api/concrete.tex | 25 | ||||
| -rw-r--r-- | Doc/lib/libcodecs.tex | 27 |
2 files changed, 41 insertions, 11 deletions
diff --git a/Doc/api/concrete.tex b/Doc/api/concrete.tex index a77a584..96b4faf 100644 --- a/Doc/api/concrete.tex +++ b/Doc/api/concrete.tex @@ -1076,6 +1076,17 @@ These are the UTF-8 codec APIs: by the codec. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8Stateful}{const char *s, + int size, + const char *errors, + int *consumed} + If \var{consumed} is \NULL{}, behaves like \cfunction{PyUnicode_DecodeUTF8()}. + If \var{consumed} is not \NULL{}, trailing incomplete UTF-8 byte sequences + will not be treated as an error. Those bytes will not be decoded and the + number of bytes that have been decoded will be stored in \var{consumed}. + \versionadded{2.4} +\end{cfuncdesc} + \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, int size, const char *errors} @@ -1121,6 +1132,20 @@ These are the UTF-16 codec APIs: Returns \NULL{} if an exception was raised by the codec. \end{cfuncdesc} +\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16Stateful}{const char *s, + int size, + const char *errors, + int *byteorder, + int *consumed} + If \var{consumed} is \NULL{}, behaves like + \cfunction{PyUnicode_DecodeUTF16()}. If \var{consumed} is not \NULL{}, + \cfunction{PyUnicode_DecodeUTF16Stateful()} will not treat trailing incomplete + UTF-16 byte sequences (i.e. an odd number of bytes or a split surrogate pair) + as an error. Those bytes will not be decoded and the number of bytes that + have been decoded will be stored in \var{consumed}. + \versionadded{2.4} +\end{cfuncdesc} + \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s, int size, const char *errors, diff --git a/Doc/lib/libcodecs.tex b/Doc/lib/libcodecs.tex index a6c434a..125463b 100644 --- a/Doc/lib/libcodecs.tex +++ b/Doc/lib/libcodecs.tex @@ -394,9 +394,14 @@ order to be compatible to the Python codec registry. be extended with \function{register_error()}. \end{classdesc} -\begin{methoddesc}{read}{\optional{size}} +\begin{methoddesc}{read}{\optional{size\optional{, chars}}} Decodes data from the stream and returns the resulting object. + \var{chars} indicates the number of characters to read from the + stream. \function{read()} will never return more than \vars{chars} + characters, but it might return less, if there are not enough + characters available. + \var{size} indicates the approximate maximum number of bytes to read from the stream for decoding purposes. The decoder can modify this setting as appropriate. The default value -1 indicates to read and @@ -407,29 +412,29 @@ order to be compatible to the Python codec registry. read as much data as is allowed within the definition of the encoding and the given size, e.g. if optional encoding endings or state markers are available on the stream, these should be read too. + + \versionchanged[\var{chars} argument added]{2.4} \end{methoddesc} -\begin{methoddesc}{readline}{[size]} +\begin{methoddesc}{readline}{\optional{size\optional{, keepends}}} Read one line from the input stream and return the decoded data. - Unlike the \method{readlines()} method, this method inherits - the line breaking knowledge from the underlying stream's - \method{readline()} method -- there is currently no support for line - breaking using the codec decoder due to lack of line buffering. - Sublcasses should however, if possible, try to implement this method - using their own knowledge of line breaking. - \var{size}, if given, is passed as size argument to the stream's \method{readline()} method. + + If \var{keepends} is false lineends will be stripped from the + lines returned. + + \versionchanged[\var{keepends} argument added]{2.4} \end{methoddesc} -\begin{methoddesc}{readlines}{[sizehint]} +\begin{methoddesc}{readlines}{\optional{sizehint\optional{, keepends}}} Read all lines available on the input stream and return them as list of lines. Line breaks are implemented using the codec's decoder method and are - included in the list entries. + included in the list entries if \var{keepends} is true. \var{sizehint}, if given, is passed as \var{size} argument to the stream's \method{read()} method. |