From 18c69609648a13f4ff8ddc01fb4db63c3d537e42 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Mon, 6 Sep 2004 00:12:04 +0000 Subject: [PATCH] SF bug #901654: split method documentation can be improved * Discuss the algorithmic distinctions between s.split() and s.split(sep). * Document the split behavior for empty strings. * Note the behavior when maxsplit is zero. * Include short examples. --- Doc/lib/libstdtypes.tex | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/Doc/lib/libstdtypes.tex b/Doc/lib/libstdtypes.tex index e97009e5269..2f54cae1a57 100644 --- a/Doc/lib/libstdtypes.tex +++ b/Doc/lib/libstdtypes.tex @@ -750,8 +750,22 @@ string this method is called on. \begin{methoddesc}[string]{split}{\optional{sep \optional{,maxsplit}}} Return a list of the words in the string, using \var{sep} as the delimiter string. If \var{maxsplit} is given, at most \var{maxsplit} -splits are done. If \var{sep} is not specified or \code{None}, any -whitespace string is a separator. +splits are done. (thus, the list will have at most \code{\var{maxsplit}+1} +elements). If \var{maxsplit} is not specified or is zero, then there +is no limit on the number of splits (all possible splits are made). +Consecutive delimiters are not grouped together and are +deemed to delimit empty strings (for example, \samp{'1,,2'.split(',')} +returns \samp{['1', '', '2']}. The \var{sep} argument may consist of +multiple characters (for example, \samp{'1, 2, 3'.split(', ')} returns +\samp{['1', '2', '3']}. Splitting an empty string with a specified +separator returns an empty list. + +If \var{sep} is not specified or is \code{None}, a different splitting +algorithm is applied. Words are separated by arbitrary length strings of +whitespace characters (spaces, tabs, newlines, returns, and formfeeds). +Consecutive whitespace delimiters are treated as a single delimiter +(\samp{'1 2 3'.split()} returns \samp{['1', '2', '3']}. Splitting an +empty string returns \samp{['']}. \end{methoddesc} \begin{methoddesc}[string]{splitlines}{\optional{keepends}}