@@ -22,12 +22,12 @@
2222-- requiring that the entire content be resident in memory.
2323--
2424-- Some operations, such as 'concat', 'append', 'reverse' and 'cons',
25−-- have better complexity than their "Data.Text" equivalents, due to
26−-- optimisations resulting from the list spine structure. And for
27−-- other operations lazy 'Text's are usually within a few percent of
28−-- strict ones, but with better heap usage. For data larger than
29−-- available memory, or if you have tight memory constraints, this
30−-- module will be the only option.
25+-- have better time complexity than their "Data.Text" equivalents, due
26+-- to the underlying representation being a list of chunks. For other
27+-- operations, lazy 'Text's are usually within a few percent of strict
28+-- ones, but often with better heap usage if used in a streaming
29+-- fashion. For data larger than available memory, or if you have
30+-- tight memory constraints, this module will be the only option.
3131--
3232-- This module is intended to be imported @qualified@, to avoid name
3333-- clashes with "Prelude" functions. eg.
@@ -345,7 +345,7 @@ pack = unstream . S.streamList . L.map safe
345345{-# INLINE [1] pack #-}
346346
347347-- | /O(n)/ Convert a 'Text' into a 'String'.
348−-- Subject to array fusion.
348+-- Subject to fusion.
349349unpack :: Text -> String
350350unpack t = S.unstreamList (stream t)
351351{-# INLINE [1] unpack #-}
@@ -411,8 +411,7 @@ snoc t c = foldrChunks Chunk (singleton c) t
411411 unstream (S.snoc (stream t) c) = snoc t c
412412 #-}
413413
414−-- | /O(n\/c)/ Appends one 'Text' to another. Subject to array
415−-- fusion.
414+-- | /O(n\/c)/ Appends one 'Text' to another. Subject to fusion.
416415append :: Text -> Text -> Text
417416append xs ys = foldrChunks Chunk ys xs
418417{-# INLINE [1] append #-}
@@ -425,7 +424,7 @@ append xs ys = foldrChunks Chunk ys xs
425424 #-}
426425
427426-- | /O(1)/ Returns the first character and rest of a 'Text', or
428−-- 'Nothing' if empty. Subject to array fusion.
427+-- 'Nothing' if empty. Subject to fusion.
429428uncons :: Text -> Maybe (Char, Text)
430429uncons Empty = Nothing
431430uncons (Chunk t ts) = Just (T.unsafeHead t, ts')
@@ -434,13 +433,13 @@ uncons (Chunk t ts) = Just (T.unsafeHead t, ts')
434433{-# INLINE uncons #-}
435434
436435-- | /O(1)/ Returns the first character of a 'Text', which must be
437−-- non-empty. Subject to array fusion.
436+-- non-empty. Subject to fusion.
438437head :: Text -> Char
439438head t = S.head (stream t)
440439{-# INLINE head #-}
441440
442441-- | /O(1)/ Returns all characters after the head of a 'Text', which
443−-- must be non-empty. Subject to array fusion.
442+-- must be non-empty. Subject to fusion.
444443tail :: Text -> Text
445444tail (Chunk t ts) = chunk (T.tail t) ts
446445tail Empty = emptyError "tail"
@@ -454,7 +453,7 @@ tail Empty = emptyError "tail"
454453 #-}
455454
456455-- | /O(1)/ Returns all but the last character of a 'Text', which must
457−-- be non-empty. Subject to array fusion.
456+-- be non-empty. Subject to fusion.
458457init :: Text -> Text
459458init (Chunk t0 ts0) = go t0 ts0
460459 where go t (Chunk t' ts) = Chunk t (go t' ts)
@@ -469,7 +468,7 @@ init Empty = emptyError "init"
469468 unstream (S.init (stream t)) = init t
470469 #-}
471470
472−-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to array
471+-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to
473472-- fusion.
474473null :: Text -> Bool
475474null Empty = True
@@ -490,7 +489,7 @@ isSingleton = S.isSingleton . stream
490489{-# INLINE isSingleton #-}
491490
492491-- | /O(1)/ Returns the last character of a 'Text', which must be
493−-- non-empty. Subject to array fusion.
492+-- non-empty. Subject to fusion.
494493last :: Text -> Char
495494last Empty = emptyError "last"
496495last (Chunk t ts) = go t ts
@@ -548,9 +547,10 @@ intercalate t = concat . (U.intersperse t)
548547{-# INLINE intercalate #-}
549548
550549-- | /O(n)/ The 'intersperse' function takes a character and places it
551−-- between the characters of a 'Text'. Subject to array fusion.
552−intersperse :: Char -> Text -> Text
553−intersperse c t = unstream (S.intersperse c (stream t))
550+-- between the characters of a 'Text'. Subject to fusion. Performs
551+-- replacement on invalid scalar values.
552+intersperse :: Char -> Text -> Text
553+intersperse c t = unstream (S.intersperse (safe c) (stream t))
554554{-# INLINE intersperse #-}
555555
556556-- | /O(n)/ Left-justify a string to the given length, using the
@@ -683,26 +683,24 @@ toUpper t = unstream (S.toUpper (stream t))
683683-- | /O(n)/ 'foldl', applied to a binary operator, a starting value
684684-- (typically the left-identity of the operator), and a 'Text',
685685-- reduces the 'Text' using the binary operator, from left to right.
686−-- Subject to array fusion.
686+-- Subject to fusion.
687687foldl :: (a -> Char -> a) -> a -> Text -> a
688688foldl f z t = S.foldl f z (stream t)
689689{-# INLINE foldl #-}
690690
691691-- | /O(n)/ A strict version of 'foldl'.
692−-- Subject to array fusion.
692+-- Subject to fusion.
693693foldl' :: (a -> Char -> a) -> a -> Text -> a
694694foldl' f z t = S.foldl' f z (stream t)
695695{-# INLINE foldl' #-}
696696
697697-- | /O(n)/ A variant of 'foldl' that has no starting value argument,
698−-- and thus must be applied to a non-empty 'Text'. Subject to array
699−-- fusion.
698+-- and thus must be applied to a non-empty 'Text'. Subject to fusion.
700699foldl1 :: (Char -> Char -> Char) -> Text -> Char
701700foldl1 f t = S.foldl1 f (stream t)
702701{-# INLINE foldl1 #-}
703702
704−-- | /O(n)/ A strict version of 'foldl1'.
705−-- Subject to array fusion.
703+-- | /O(n)/ A strict version of 'foldl1'. Subject to fusion.
706704foldl1' :: (Char -> Char -> Char) -> Text -> Char
707705foldl1' f t = S.foldl1' f (stream t)
708706{-# INLINE foldl1' #-}
@@ -710,13 +708,13 @@ foldl1' f t = S.foldl1' f (stream t)
710708-- | /O(n)/ 'foldr', applied to a binary operator, a starting value
711709-- (typically the right-identity of the operator), and a 'Text',
712710-- reduces the 'Text' using the binary operator, from right to left.
713−-- Subject to array fusion.
711+-- Subject to fusion.
714712foldr :: (Char -> a -> a) -> a -> Text -> a
715713foldr f z t = S.foldr f z (stream t)
716714{-# INLINE foldr #-}
717715
718−-- | /O(n)/ A variant of 'foldr' that has no starting value argument, and
719−-- thust must be applied to a non-empty 'Text'. Subject to array
716+-- | /O(n)/ A variant of 'foldr' that has no starting value argument,
717+-- and thust must be applied to a non-empty 'Text'. Subject to
720718-- fusion.
721719foldr1 :: (Char -> Char -> Char) -> Text -> Char
722720foldr1 f t = S.foldr1 f (stream t)
@@ -739,25 +737,25 @@ concatMap f = concat . foldr ((:) . f) []
739737{-# INLINE concatMap #-}
740738
741739-- | /O(n)/ 'any' @p@ @t@ determines whether any character in the
742−-- 'Text' @t@ satisifes the predicate @p@. Subject to array fusion.
740+-- 'Text' @t@ satisifes the predicate @p@. Subject to fusion.
743741any :: (Char -> Bool) -> Text -> Bool
744742any p t = S.any p (stream t)
745743{-# INLINE any #-}
746744
747745-- | /O(n)/ 'all' @p@ @t@ determines whether all characters in the
748−-- 'Text' @t@ satisify the predicate @p@. Subject to array fusion.
746+-- 'Text' @t@ satisify the predicate @p@. Subject to fusion.
749747all :: (Char -> Bool) -> Text -> Bool
750748all p t = S.all p (stream t)
751749{-# INLINE all #-}
752750
753751-- | /O(n)/ 'maximum' returns the maximum value from a 'Text', which
754−-- must be non-empty. Subject to array fusion.
752+-- must be non-empty. Subject to fusion.
755753maximum :: Text -> Char
756754maximum t = S.maximum (stream t)
757755{-# INLINE maximum #-}
758756
759757-- | /O(n)/ 'minimum' returns the minimum value from a 'Text', which
760−-- must be non-empty. Subject to array fusion.
758+-- must be non-empty. Subject to fusion.
761759minimum :: Text -> Char
762760minimum t = S.minimum (stream t)
763761{-# INLINE minimum #-}
@@ -929,9 +927,9 @@ dropWords i t0
929927 where len' = fromIntegral len
930928 n' = fromIntegral n
931929
932−-- | /O(n)/ 'takeWhile', applied to a predicate @p@ and a 'Text', returns
933−-- the longest prefix (possibly empty) of elements that satisfy @p@.
934−-- This function is subject to array fusion.
930+-- | /O(n)/ 'takeWhile', applied to a predicate @p@ and a 'Text',
931+-- returns the longest prefix (possibly empty) of elements that
932+-- satisfy @p@. Subject to fusion.
935933takeWhile :: (Char -> Bool) -> Text -> Text
936934takeWhile p t0 = takeWhile' t0
937935 where takeWhile' Empty = Empty
@@ -950,7 +948,7 @@ takeWhile p t0 = takeWhile' t0
950948 #-}
951949
952950-- | /O(n)/ 'dropWhile' @p@ @t@ returns the suffix remaining after
953−-- 'takeWhile' @p@ @t@. This function is subject to array fusion.
951+-- 'takeWhile' @p@ @t@. Subject to fusion.
954952dropWhile :: (Char -> Bool) -> Text -> Text
955953dropWhile p t0 = dropWhile' t0
956954 where dropWhile' Empty = Empty
@@ -1275,8 +1273,7 @@ unwords = intercalate (singleton ' ')
12751273{-# INLINE unwords #-}
12761274
12771275-- | /O(n)/ The 'isPrefixOf' function takes two 'Text's and returns
1278−-- 'True' iff the first is a prefix of the second. This function is
1279−-- subject to fusion.
1276+-- 'True' iff the first is a prefix of the second. Subject to fusion.
12801277isPrefixOf :: Text -> Text -> Bool
12811278isPrefixOf Empty _ = True
12821279isPrefixOf _ Empty = False
@@ -1422,8 +1419,7 @@ count pat src
14221419 #-}
14231420
14241421-- | /O(n)/ The 'countChar' function returns the number of times the
1425−-- query element appears in the given 'Text'. This function is subject
1426−-- to fusion.
1422+-- query element appears in the given 'Text'. Subject to fusion.
14271423countChar :: Char -> Text -> Int64
14281424countChar c t = S.countChar c (stream t)
14291425