Further improve docs for replace
authorBryan O'Sullivan <bos@serpentine.com>
Wed, 3 Dec 2014 17:33:20 +0000 (09:33 -0800)
committerBryan O'Sullivan <bos@serpentine.com>
Wed, 3 Dec 2014 17:33:20 +0000 (09:33 -0800)
Data/Text.hs
Data/Text/Lazy.hs

index ffe303b..6dac5c2 100644 (file)
@@ -666,21 +666,31 @@ reverse :: Text -> Text
 reverse t = S.reverse (stream t)
 {-# INLINE reverse #-}
 
 reverse t = S.reverse (stream t)
 {-# INLINE reverse #-}
 
--- | /O(m+n)/ Replace every occurrence of @needle@ in @haystack@ with @repl@.
+-- | /O(m+n)/ Replace every non-overlapping occurrence of @needle@ in
+-- @haystack@ with @replacement@.
 --
 --
--- If @needle@ occurs in @repl@, it won't be replaced twice:
+-- This function behaves as though it was defined as follows:
+--
+--@
+-- replace needle replacement haystack =
+--   'intercalate' replacement ('splitOn' needle haystack)
+--@
+--
+-- As this suggests, each occurrence is replaced exactly once.  So if
+-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
+-- be replaced recursively:
 --
 -- > replace "oo" "foo" "oo" == "foo"
 --
 --
 -- > replace "oo" "foo" "oo" == "foo"
 --
--- If several instances of @needle@ overlap, only the first one will be
--- replaced:
+-- In cases where several instances of @needle@ overlap, only the
+-- first one will be replaced:
 --
 -- > replace "ofo" "bar" "ofofo" == "barfo"
 --
 -- In (unlikely) bad cases, this function's time complexity degrades
 -- towards /O(n*m)/.
 replace :: Text        -- ^ @needle@ to search for
 --
 -- > replace "ofo" "bar" "ofofo" == "barfo"
 --
 -- In (unlikely) bad cases, this function's time complexity degrades
 -- towards /O(n*m)/.
 replace :: Text        -- ^ @needle@ to search for
-        -> Text        -- ^ @repl@ to replace @needle@ with
+        -> Text        -- ^ @replacement@ to replace @needle@ with
         -> Text        -- ^ @haystack@ in which to search
         -> Text
 replace needle@(Text _      _      neeLen)
         -> Text        -- ^ @haystack@ in which to search
         -> Text
 replace needle@(Text _      _      neeLen)
index eaecb42..51dff78 100644 (file)
@@ -663,7 +663,26 @@ reverse = rev Empty
   where rev a Empty        = a
         rev a (Chunk t ts) = rev (Chunk (T.reverse t) a) ts
 
   where rev a Empty        = a
         rev a (Chunk t ts) = rev (Chunk (T.reverse t) a) ts
 
--- | /O(m+n)/ Replace every occurrence of one substring with another.
+-- | /O(m+n)/ Replace every non-overlapping occurrence of @needle@ in
+-- @haystack@ with @replacement@.
+--
+-- This function behaves as though it was defined as follows:
+--
+--@
+-- replace needle replacement haystack =
+--   'intercalate' replacement ('splitOn' needle haystack)
+--@
+--
+-- As this suggests, each occurrence is replaced exactly once.  So if
+-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
+-- be replaced recursively:
+--
+-- > replace "oo" "foo" "oo" == "foo"
+--
+-- In cases where several instances of @needle@ overlap, only the
+-- first one will be replaced:
+--
+-- > replace "ofo" "bar" "ofofo" == "barfo"
 --
 -- In (unlikely) bad cases, this function's time complexity degrades
 -- towards /O(n*m)/.
 --
 -- In (unlikely) bad cases, this function's time complexity degrades
 -- towards /O(n*m)/.