[commit: ghc] master: Improve documentation of Data.List.lines: (fa61edd)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/fa61eddebf6f3ad5671c81f8bf0494e81332c4ec/ghc

>---------------------------------------------------------------

commit fa61eddebf6f3ad5671c81f8bf0494e81332c4ec
Author: Eric Mertens <emertens at gmail.com>
Date:   Wed Nov 11 12:31:45 2015 +0100

    Improve documentation of Data.List.lines:
    
    - 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


>---------------------------------------------------------------

fa61eddebf6f3ad5671c81f8bf0494e81332c4ec
 libraries/base/Data/OldList.hs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/libraries/base/Data/OldList.hs b/libraries/base/Data/OldList.hs
index a377b4f..be894c0 100644
--- a/libraries/base/Data/OldList.hs
+++ b/libraries/base/Data/OldList.hs
@@ -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 at .
 lines                   :: String -> [String]
 lines ""                =  []
 -- Somehow GHC doesn't detect the selector thunks in the below code,