@@ -16,6 +16,9 @@
1616-- stream fusion. If strings are to be stored or buffered in memory, they can
1717-- be encoded to 'Word8' arrays using the encoding routines provided in the
1818-- module. Therefore, a separate type for text representation is not required.
19+-- A @Stream Identity Char@ can be used almost as a drop-in replacement for the
20+-- standard Haskell @String@, especially when used with @OverloadedStrings@
21+-- extension, with little differences.
1922
2023-- The 'String' type in this module is just a synonym for the type @List Char@.
2124-- It provides better performance compared to the standard Haskell @String@
@@ -164,8 +167,8 @@ stripStart = S.dropWhile isSpace
164167-- | Fold each line of the stream using the supplied Fold
165168-- and stream the result.
166169--
167−-- >>> foldLines "lines\nthis\nstring\n\n\n" FL.toList
168−-- ["lines", "this", "string"]
170+-- >>> S.toList $ foldLines (S.fromList "lines\nthis\nstring\n\n\n") FL.toList
171+-- ["lines", "this", "string", "", ""]
169172{-# INLINE foldLines #-}
170173foldLines :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
171174foldLines = flip (FL.splitSuffixBy (== '\n'))
@@ -173,7 +176,7 @@ foldLines = flip (FL.splitSuffixBy (== '\n'))
173176-- | Fold each word of the stream using the supplied Fold
174177-- and stream the result.
175178--
176−-- >>> foldWords "fold these words" FL.toList
179+-- >>> S.toList $ foldWords (S.fromList "fold these words") FL.toList
177180-- ["fold", "these", "words"]
178181{-# INLINE foldWords #-}
179182foldWords :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
@@ -194,8 +197,8 @@ isSpace c
194197-- | Break a string up into a list of strings at newline characters.
195198-- The resulting strings do not contain newlines.
196199--
197−-- >>> lines "lines\nthis\nstring\n\n\n"
198−-- ["lines","this","string"]
200+-- >>> S.toList $ lines $ S.fromList "lines\nthis\nstring\n\n\n"
201+-- ["lines","this","string","",""]
199202--
200203-- If you're dealing with lines of massive length, consider using
201204-- 'foldLines' instead.
@@ -206,7 +209,7 @@ lines = FL.splitSuffixBy (== '\n') toArray
206209-- | Break a string up into a list of strings, which were delimited
207210-- by characters representing white space.
208211--
209−-- >>> words "A newline\nis considered white space?"
212+-- >>> S.toList $ words $ S.fromList "A newline\nis considered white space?"
210213-- ["A", "newline", "is", "considered", "white", "space?"]
211214--
212215-- If you're dealing with words of massive length, consider using
@@ -215,12 +218,12 @@ lines = FL.splitSuffixBy (== '\n') toArray
215218words :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
216219words = FL.wordsBy isSpace toArray
217220
218−-- | Flattens the stream of 'Array' 'Char', after appending a terminating
221+-- | Flattens the stream of @Array Char@, after appending a terminating
219222-- newline to each string.
220223--
221224-- 'unlines' is an inverse operation to 'lines'.
222225--
223−-- >>> unlines ["lines", "this", "string"]
226+-- >>> S.toList $ unlines $ S.fromList ["lines", "this", "string"]
224227-- "lines\nthis\nstring\n"
225228--
226229-- Note that, in general
@@ -230,12 +233,12 @@ words = FL.wordsBy isSpace toArray
230233unlines :: (MonadIO m, IsStream t) => t m (Array Char) -> t m Char
231234unlines = D.fromStreamD . A.unlines '\n' . D.toStreamD
232235
233−-- | Flattens the stream of 'Array' 'Char', after appending a separating
236+-- | Flattens the stream of @Array Char@, after appending a separating
234237-- space to each string.
235238--
236239-- 'unwords' is an inverse operation to 'words'.
237240--
238−-- >>> unwords ["unwords", "this", "string"]
241+-- >>> S.toList $ unwords $ S.fromList ["unwords", "this", "string"]
239242-- "unwords this string"
240243--
241244-- Note that, in general