@@ -49,6 +49,7 @@ module Streamly.String
49 -- * Operations on character strings
49 -- * Operations on character strings
50 , strip -- (dropAround isSpace)
50 , strip -- (dropAround isSpace)
51 , stripEnd-}
51 , stripEnd-}
52 , stripStart
53 , stripStart
53 , foldLines
54 , foldLines
54 , foldWords
55 , foldWords
@@ -153,14 +154,27 @@ stripEnd :: IsStream t => t m Char -> t m Char
153stripEnd = undefined
154stripEnd = undefined
157+-- | Remove leading whitespace from a String.
159+-- > stripStart = S.dropWhile isSpace
156{-# INLINE stripStart #-}
160{-# INLINE stripStart #-}
157stripStart :: (Monad m, IsStream t) => t m Char -> t m Char
161stripStart :: (Monad m, IsStream t) => t m Char -> t m Char
158stripStart = S.dropWhile isSpace
162stripStart = S.dropWhile isSpace
164+-- | Fold each line of the stream using the supplied Fold
165+-- and stream the result.
167+-- >>> foldLines "lines\nthis\nstring\n\n\n" FL.toList
168+-- ["lines", "this", "string"]
160{-# INLINE foldLines #-}
169{-# INLINE foldLines #-}
161foldLines :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
170foldLines :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
162foldLines = flip (FL.splitSuffixBy (== '\n'))
171foldLines = flip (FL.splitSuffixBy (== '\n'))
173+-- | Fold each word of the stream using the supplied Fold
174+-- and stream the result.
176+-- >>> foldWords "fold these words" FL.toList
177+-- ["fold", "these", "words"]
164{-# INLINE foldWords #-}
178{-# INLINE foldWords #-}
165foldWords :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
179foldWords :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
166foldWords = flip (FL.wordsBy isSpace)
180foldWords = flip (FL.wordsBy isSpace)
@@ -168,7 +182,7 @@ foldWords = flip (FL.wordsBy isSpace)
168foreign import ccall unsafe "u_iswspace"
182foreign import ccall unsafe "u_iswspace"
169 iswspace :: Int -> Int
183 iswspace :: Int -> Int
171−-- Code copied from base/Data.Char to INLINE it
185+-- | Code copied from base/Data.Char to INLINE it
172{-# INLINE isSpace #-}
186{-# INLINE isSpace #-}
173isSpace :: Char -> Bool
187isSpace :: Char -> Bool
@@ -177,18 +191,56 @@ isSpace c
178 uc = fromIntegral (ord c) :: Word
192 uc = fromIntegral (ord c) :: Word
194+-- | Break a string up into a list of strings at newline characters.
195+-- The resulting strings do not contain newlines.
197+-- >>> lines "lines\nthis\nstring\n\n\n"
198+-- ["lines","this","string"]
200+-- If you're dealing with lines of massive length, consider using
201+-- 'foldLines' instead.
180{-# INLINE lines #-}
202{-# INLINE lines #-}
181lines :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
203lines :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
182lines = FL.splitSuffixBy (== '\n') toArray
204lines = FL.splitSuffixBy (== '\n') toArray
206+-- | Break a string up into a list of strings, which were delimited
207+-- by characters representing white space.
209+-- >>> words "A newline\nis considered white space?"
210+-- ["A", "newline", "is", "considered", "white", "space?"]
212+-- If you're dealing with words of massive length, consider using
213+-- 'foldWords' instead.
184{-# INLINE words #-}
214{-# INLINE words #-}
185words :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
215words :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
186words = FL.wordsBy isSpace toArray
216words = FL.wordsBy isSpace toArray
218+-- | Flattens the stream of 'Array' 'Char', after appending a terminating
219+-- newline to each string.
221+-- 'unlines' is an inverse operation to 'lines'.
223+-- >>> unlines ["lines", "this", "string"]
224+-- "lines\nthis\nstring\n"
226+-- Note that, in general
228+-- > unlines . lines /= id
188{-# INLINE unlines #-}
229{-# INLINE unlines #-}
189unlines :: (MonadIO m, IsStream t) => t m (Array Char) -> t m Char
230unlines :: (MonadIO m, IsStream t) => t m (Array Char) -> t m Char
190unlines = D.fromStreamD . A.unlines '\n' . D.toStreamD
231unlines = D.fromStreamD . A.unlines '\n' . D.toStreamD
233+-- | Flattens the stream of 'Array' 'Char', after appending a separating
234+-- space to each string.
236+-- 'unwords' is an inverse operation to 'words'.
238+-- >>> unwords ["unwords", "this", "string"]
239+-- "unwords this string"
241+-- Note that, in general
243+-- > unwords . words /= id
192{-# INLINE unwords #-}
244{-# INLINE unwords #-}
193unwords :: (MonadAsync m, IsStream t) => t m (Array Char) -> t m Char
245unwords :: (MonadAsync m, IsStream t) => t m (Array Char) -> t m Char
194unwords = A.flattenArrays . (S.intersperse (A.fromList " "))
246unwords = A.flattenArrays . (S.intersperse (A.fromList " "))