@@ -16,6 +16,9 @@
16-- stream fusion. If strings are to be stored or buffered in memory, they can
16-- stream fusion. If strings are to be stored or buffered in memory, they can
17-- be encoded to 'Word8' arrays using the encoding routines provided in the
17-- be encoded to 'Word8' arrays using the encoding routines provided in the
18-- module. Therefore, a separate type for text representation is not required.
18-- 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.
20-- The 'String' type in this module is just a synonym for the type @List Char@.
23-- The 'String' type in this module is just a synonym for the type @List Char@.
21-- It provides better performance compared to the standard Haskell @String@
24-- It provides better performance compared to the standard Haskell @String@
@@ -164,8 +167,8 @@ stripStart = S.dropWhile isSpace
164-- | Fold each line of the stream using the supplied Fold
167-- | Fold each line of the stream using the supplied Fold
165-- and stream the result.
168-- and stream the result.
167−-- >>> foldLines "lines\nthis\nstring\n\n\n" FL.toList
170+-- >>> S.toList $ foldLines (S.fromList "lines\nthis\nstring\n\n\n") FL.toList
168−-- ["lines", "this", "string"]
171+-- ["lines", "this", "string", "", ""]
169{-# INLINE foldLines #-}
172{-# INLINE foldLines #-}
170foldLines :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
173foldLines :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
171foldLines = flip (FL.splitSuffixBy (== '\n'))
174foldLines = flip (FL.splitSuffixBy (== '\n'))
@@ -173,7 +176,7 @@ foldLines = flip (FL.splitSuffixBy (== '\n'))
173-- | Fold each word of the stream using the supplied Fold
176-- | Fold each word of the stream using the supplied Fold
174-- and stream the result.
177-- and stream the result.
176−-- >>> foldWords "fold these words" FL.toList
179+-- >>> S.toList $ foldWords (S.fromList "fold these words") FL.toList
177-- ["fold", "these", "words"]
180-- ["fold", "these", "words"]
178{-# INLINE foldWords #-}
181{-# INLINE foldWords #-}
179foldWords :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
182foldWords :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
@@ -194,8 +197,8 @@ isSpace c
194-- | Break a string up into a list of strings at newline characters.
197-- | Break a string up into a list of strings at newline characters.
195-- The resulting strings do not contain newlines.
198-- The resulting strings do not contain newlines.
197−-- >>> lines "lines\nthis\nstring\n\n\n"
200+-- >>> S.toList $ lines $ S.fromList "lines\nthis\nstring\n\n\n"
198−-- ["lines","this","string"]
201+-- ["lines","this","string","",""]
200-- If you're dealing with lines of massive length, consider using
203-- If you're dealing with lines of massive length, consider using
201-- 'foldLines' instead.
204-- 'foldLines' instead.
@@ -206,7 +209,7 @@ lines = FL.splitSuffixBy (== '\n') toArray
206-- | Break a string up into a list of strings, which were delimited
209-- | Break a string up into a list of strings, which were delimited
207-- by characters representing white space.
210-- by characters representing white space.
209−-- >>> words "A newline\nis considered white space?"
212+-- >>> S.toList $ words $ S.fromList "A newline\nis considered white space?"
210-- ["A", "newline", "is", "considered", "white", "space?"]
213-- ["A", "newline", "is", "considered", "white", "space?"]
212-- If you're dealing with words of massive length, consider using
215-- If you're dealing with words of massive length, consider using
@@ -215,12 +218,12 @@ lines = FL.splitSuffixBy (== '\n') toArray
215words :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
218words :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
216words = FL.wordsBy isSpace toArray
219words = FL.wordsBy isSpace toArray
218−-- | Flattens the stream of 'Array' 'Char', after appending a terminating
221+-- | Flattens the stream of @Array Char@, after appending a terminating
219-- newline to each string.
222-- newline to each string.
221-- 'unlines' is an inverse operation to 'lines'.
224-- 'unlines' is an inverse operation to 'lines'.
223−-- >>> unlines ["lines", "this", "string"]
226+-- >>> S.toList $ unlines $ S.fromList ["lines", "this", "string"]
224-- "lines\nthis\nstring\n"
227-- "lines\nthis\nstring\n"
226-- Note that, in general
229-- Note that, in general
@@ -230,12 +233,12 @@ words = FL.wordsBy isSpace toArray
230unlines :: (MonadIO m, IsStream t) => t m (Array Char) -> t m Char
233unlines :: (MonadIO m, IsStream t) => t m (Array Char) -> t m Char
231unlines = D.fromStreamD . A.unlines '\n' . D.toStreamD
234unlines = D.fromStreamD . A.unlines '\n' . D.toStreamD
233−-- | Flattens the stream of 'Array' 'Char', after appending a separating
236+-- | Flattens the stream of @Array Char@, after appending a separating
234-- space to each string.
237-- space to each string.
236-- 'unwords' is an inverse operation to 'words'.
239-- 'unwords' is an inverse operation to 'words'.
238−-- >>> unwords ["unwords", "this", "string"]
241+-- >>> S.toList $ unwords $ S.fromList ["unwords", "this", "string"]
239-- "unwords this string"
242-- "unwords this string"
241-- Note that, in general
244-- Note that, in general