@@ -49,6 +49,7 @@ module Streamly.String
4949 -- * Operations on character strings
5050 , strip -- (dropAround isSpace)
5151 , stripEnd-}
52+ -- * Substrings
5253 , stripStart
5354 , foldLines
5455 , foldWords
@@ -153,14 +154,27 @@ stripEnd :: IsStream t => t m Char -> t m Char
153154stripEnd = undefined
154155-}
155156
157+-- | Remove leading whitespace from a String.
158+--
159+-- > stripStart = S.dropWhile isSpace
156160{-# INLINE stripStart #-}
157161stripStart :: (Monad m, IsStream t) => t m Char -> t m Char
158162stripStart = S.dropWhile isSpace
159163
164+-- | Fold each line of the stream using the supplied Fold
165+-- and stream the result.
166+--
167+-- >>> foldLines "lines\nthis\nstring\n\n\n" FL.toList
168+-- ["lines", "this", "string"]
160169{-# INLINE foldLines #-}
161170foldLines :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
162171foldLines = flip (FL.splitSuffixBy (== '\n'))
163172
173+-- | Fold each word of the stream using the supplied Fold
174+-- and stream the result.
175+--
176+-- >>> foldWords "fold these words" FL.toList
177+-- ["fold", "these", "words"]
164178{-# INLINE foldWords #-}
165179foldWords :: (Monad m, IsStream t) => t m Char -> Fold m Char b -> t m b
166180foldWords = flip (FL.wordsBy isSpace)
@@ -168,7 +182,7 @@ foldWords = flip (FL.wordsBy isSpace)
168182foreign import ccall unsafe "u_iswspace"
169183 iswspace :: Int -> Int
170184
171−-- Code copied from base/Data.Char to INLINE it
185+-- | Code copied from base/Data.Char to INLINE it
172186{-# INLINE isSpace #-}
173187isSpace :: Char -> Bool
174188isSpace c
@@ -177,18 +191,56 @@ isSpace c
177191 where
178192 uc = fromIntegral (ord c) :: Word
179193
194+-- | Break a string up into a list of strings at newline characters.
195+-- The resulting strings do not contain newlines.
196+--
197+-- >>> lines "lines\nthis\nstring\n\n\n"
198+-- ["lines","this","string"]
199+--
200+-- If you're dealing with lines of massive length, consider using
201+-- 'foldLines' instead.
180202{-# INLINE lines #-}
181203lines :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
182204lines = FL.splitSuffixBy (== '\n') toArray
183205
206+-- | Break a string up into a list of strings, which were delimited
207+-- by characters representing white space.
208+--
209+-- >>> words "A newline\nis considered white space?"
210+-- ["A", "newline", "is", "considered", "white", "space?"]
211+--
212+-- If you're dealing with words of massive length, consider using
213+-- 'foldWords' instead.
184214{-# INLINE words #-}
185215words :: (MonadIO m, IsStream t) => t m Char -> t m (Array Char)
186216words = FL.wordsBy isSpace toArray
187217
218+-- | Flattens the stream of 'Array' 'Char', after appending a terminating
219+-- newline to each string.
220+--
221+-- 'unlines' is an inverse operation to 'lines'.
222+--
223+-- >>> unlines ["lines", "this", "string"]
224+-- "lines\nthis\nstring\n"
225+--
226+-- Note that, in general
227+--
228+-- > unlines . lines /= id
188229{-# INLINE unlines #-}
189230unlines :: (MonadIO m, IsStream t) => t m (Array Char) -> t m Char
190231unlines = D.fromStreamD . A.unlines '\n' . D.toStreamD
191232
233+-- | Flattens the stream of 'Array' 'Char', after appending a separating
234+-- space to each string.
235+--
236+-- 'unwords' is an inverse operation to 'words'.
237+--
238+-- >>> unwords ["unwords", "this", "string"]
239+-- "unwords this string"
240+--
241+-- Note that, in general
242+--
243+-- > unwords . words /= id
192244{-# INLINE unwords #-}
193245unwords :: (MonadAsync m, IsStream t) => t m (Array Char) -> t m Char
194246unwords = A.flattenArrays . (S.intersperse (A.fromList " "))