Improve documentation of Data.List.lines:
authorEric Mertens <emertens@gmail.com>
Wed, 11 Nov 2015 11:31:45 +0000 (12:31 +0100)
committerBen Gamari <ben@smart-cactus.org>
Wed, 11 Nov 2015 11:31:52 +0000 (12:31 +0100)
- Document behavior on some inputs.
- Add some examples.

Reviewers: bgamari, osa1, hvr, dolio, #core_libraries_committee,
nomeata, austin

Reviewed By: bgamari, dolio, #core_libraries_committee, nomeata, austin

Subscribers: dolio, glguy, nomeata, thomie

Differential Revision: https://phabricator.haskell.org/D1450

libraries/base/Data/OldList.hs

index a377b4f..be894c0 100644 (file)
@@ -1044,6 +1044,20 @@ unfoldr f b0 = build (\c n ->
 
 -- | 'lines' breaks a string up into a list of strings at newline
 -- characters.  The resulting strings do not contain newlines.
+--
+-- Note that after splitting the string at newline characters, the
+-- last part of the string is considered a line even if it doesn't end
+-- with a newline. For example,
+--
+-- > lines "" == []
+-- > lines "\n" == [""]
+-- > lines "one" == ["one"]
+-- > lines "one\n" == ["one"]
+-- > lines "one\n\n" == ["one",""]
+-- > lines "one\ntwo" == ["one","two"]
+-- > lines "one\ntwo\n" == ["one","two"]
+--
+-- Thus @'lines' s@ contains at least as many elements as newlines in @s@.
 lines                   :: String -> [String]
 lines ""                =  []
 -- Somehow GHC doesn't detect the selector thunks in the below code,