@@ -666,11 +666,23 @@ reverse :: Text -> Text
666666reverse t = S.reverse (stream t)
667667{-# INLINE reverse #-}
668668
669−-- | /O(m+n)/ Replace every occurrence of one substring with another.
669+-- | /O(m+n)/ Replace every occurrence of @needle@ in @haystack@ with @repl@.
670+--
671+-- If @needle@ occurs in @repl@, it won't be replaced twice:
672+--
673+-- > replace "oo" "foo" "oo" == "foo"
674+--
675+-- If several instances of @needle@ overlap, only the first one will be
676+-- replaced:
677+--
678+-- > replace "ofo" "bar" "ofofo" == "barfo"
670679--
671680-- In (unlikely) bad cases, this function's time complexity degrades
672681-- towards /O(n*m)/.
673−replace :: Text -> Text -> Text -> Text
682+replace :: Text -- ^ @needle@ to search for
683+ -> Text -- ^ @repl@ to replace @needle@ with
684+ -> Text -- ^ @haystack@ in which to search
685+ -> Text
674686replace needle@(Text _ _ neeLen)
675687 (Text repArr repOff repLen)
676688 haystack@(Text hayArr hayOff hayLen)