Add foldr' and document the laziness of foldr

Author: Lysxia

src/Data/Text.hs

@@ -98,6 +98,7 @@ module Data.Text
     , foldl1
     , foldl1'
     , foldr
+    , foldr'
     , foldr1
 
     -- ** Special folds
@@ -988,6 +989,22 @@ foldl1' f t = S.foldl1' f (stream t)
 -- | /O(n)/ 'foldr', applied to a binary operator, a starting value
 -- (typically the right-identity of the operator), and a 'Text',
 -- reduces the 'Text' using the binary operator, from right to left.
+--
+-- If the binary operator is strict in its second argument, use 'foldr''
+-- instead.
+--
+-- 'foldr' is lazy like 'Data.List.foldr' for lists: evaluation actually
+-- traverses the 'Text' from left to right, only as far as it needs to.
+--
+-- For example, 'head' can be defined with /O(1)/ complexity using 'foldr':
+--
+-- @
+-- head :: Text -> Char
+-- head = foldr const (error "head empty")
+-- @
+--
+-- Searches from left to right with short-circuiting behavior can
+-- also be defined using 'foldr' (/e.g./, 'any', 'all', 'find', 'elem').
 foldr :: (Char -> a -> a) -> a -> Text -> a
 foldr f z t = S.foldr f z (stream t)
 {-# INLINE foldr #-}
@@ -998,6 +1015,13 @@ foldr1 :: HasCallStack => (Char -> Char -> Char) -> Text -> Char
 foldr1 f t = S.foldr1 f (stream t)
 {-# INLINE foldr1 #-}
 
+-- | /O(n)/ A strict version of 'foldr'.
+--
+-- 'foldr'' evaluates as a right-to-left traversal using constant stack space.
+foldr' :: (Char -> a -> a) -> a -> Text -> a
+foldr' f z t = S.foldl' (P.flip f) z (reverseStream t)
+{-# INLINE foldr' #-}
+
 -- -----------------------------------------------------------------------------
 -- ** Special folds
 

src/Data/Text/Lazy.hs

@@ -780,6 +780,16 @@ foldl1' f t = S.foldl1' f (stream t)
 -- | /O(n)/ 'foldr', applied to a binary operator, a starting value
 -- (typically the right-identity of the operator), and a 'Text',
 -- reduces the 'Text' using the binary operator, from right to left.
+--
+-- 'foldr' is lazy like 'Data.List.foldr' for lists: evaluation actually
+-- traverses the 'Text' from left to right, only as far as it needs to.
+--
+-- For example, 'head' can be defined with /O(1)/ complexity using 'foldr':
+--
+-- @
+-- head :: Text -> Char
+-- head = foldr const (error "head empty")
+-- @
 foldr :: (Char -> a -> a) -> a -> Text -> a
 foldr f z t = S.foldr f z (stream t)
 {-# INLINE foldr #-}

tests/Tests/Properties/Folds.hs

@@ -47,6 +47,8 @@ sf_foldr (applyFun -> p) (applyFun2 -> f) z =
     where _types  = f :: Char -> Char -> Char
 t_foldr (applyFun2 -> f) z       = L.foldr f z  `eqP` T.foldr f z
     where _types  = f :: Char -> Char -> Char
+t_foldr' (applyFun2 -> f) z       = L.foldr f z  `eqP` T.foldr' f z
+    where _types  = f :: Char -> Char -> Char
 tl_foldr (applyFun2 -> f) z      = L.foldr f z  `eqPSqrt` TL.foldr f z
     where _types  = f :: Char -> Char -> Char
 sf_foldr1 (applyFun -> p) (applyFun2 -> f) =
@@ -187,6 +189,7 @@ testFolds =
       testProperty "tl_foldl1'" tl_foldl1',
       testProperty "sf_foldr" sf_foldr,
       testProperty "t_foldr" t_foldr,
+      testProperty "t_foldr'" t_foldr',
       testProperty "tl_foldr" tl_foldr,
       testProperty "sf_foldr1" sf_foldr1,
       testProperty "t_foldr1" t_foldr1,