@@ -666,21 +666,31 @@ reverse :: Text -> Text
666reverse t = S.reverse (stream t)
666reverse t = S.reverse (stream t)
667{-# INLINE reverse #-}
667{-# INLINE reverse #-}
669−-- | /O(m+n)/ Replace every occurrence of @needle@ in @haystack@ with @repl@.
669+-- | /O(m+n)/ Replace every non-overlapping occurrence of @needle@ in
670+-- @haystack@ with @replacement@.
671−-- If @needle@ occurs in @repl@, it won't be replaced twice:
672+-- This function behaves as though it was defined as follows:
675+-- replace needle replacement haystack =
676+-- 'intercalate' replacement ('splitOn' needle haystack)
679+-- As this suggests, each occurrence is replaced exactly once. So if
680+-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
681+-- be replaced recursively:
673-- > replace "oo" "foo" "oo" == "foo"
683-- > replace "oo" "foo" "oo" == "foo"
675−-- If several instances of @needle@ overlap, only the first one will be
685+-- In cases where several instances of @needle@ overlap, only the
676−-- replaced:
686+-- first one will be replaced:
678-- > replace "ofo" "bar" "ofofo" == "barfo"
688-- > replace "ofo" "bar" "ofofo" == "barfo"
680-- In (unlikely) bad cases, this function's time complexity degrades
690-- In (unlikely) bad cases, this function's time complexity degrades
681-- towards /O(n*m)/.
691-- towards /O(n*m)/.
682replace :: Text -- ^ @needle@ to search for
692replace :: Text -- ^ @needle@ to search for
683− -> Text -- ^ @repl@ to replace @needle@ with
693+ -> Text -- ^ @replacement@ to replace @needle@ with
684 -> Text -- ^ @haystack@ in which to search
694 -> Text -- ^ @haystack@ in which to search
686replace needle@(Text _ _ neeLen)
696replace needle@(Text _ _ neeLen)