1{-# LANGUAGE CPP #-} 2{-# LANGUAGE Rank2Types #-} 3{-# LANGUAGE FlexibleContexts #-} 4{-# LANGUAGE FlexibleInstances #-} 5{-# LANGUAGE MultiParamTypeClasses #-} 6{-# LANGUAGE ConstraintKinds #-} 7{-# LANGUAGE Trustworthy #-} 8 9#include "lens-common.h" 10{-# OPTIONS_GHC -fno-warn-orphans #-} 11---------------------------------------------------------------------------- 12-- | 13-- Module : Control.Lens.Fold 14-- Copyright : (C) 2012-16 Edward Kmett 15-- License : BSD-style (see the file LICENSE) 16-- Maintainer : Edward Kmett <ekmett@gmail.com> 17-- Stability : provisional 18-- Portability : Rank2Types 19-- 20-- A @'Fold' s a@ is a generalization of something 'Foldable'. It allows 21-- you to extract multiple results from a container. A 'Foldable' container 22-- can be characterized by the behavior of 23-- @'Data.Foldable.foldMap' :: ('Foldable' t, 'Monoid' m) => (a -> m) -> t a -> m@. 24-- Since we want to be able to work with monomorphic containers, we could 25-- generalize this signature to @forall m. 'Monoid' m => (a -> m) -> s -> m@, 26-- and then decorate it with 'Const' to obtain 27-- 28-- @type 'Fold' s a = forall m. 'Monoid' m => 'Getting' m s a@ 29-- 30-- Every 'Getter' is a valid 'Fold' that simply doesn't use the 'Monoid' 31-- it is passed. 32-- 33-- In practice the type we use is slightly more complicated to allow for 34-- better error messages and for it to be transformed by certain 35-- 'Applicative' transformers. 36-- 37-- Everything you can do with a 'Foldable' container, you can with with a 'Fold' and there are 38-- combinators that generalize the usual 'Foldable' operations here. 39---------------------------------------------------------------------------- 40module Control.Lens.Fold 41 ( 42 -- * Folds 43 Fold 44 , IndexedFold 45 46 -- * Getting Started 47 , (^..) 48 , (^?) 49 , (^?!) 50 , pre, ipre 51 , preview, previews, ipreview, ipreviews 52 , preuse, preuses, ipreuse, ipreuses 53 54 , has, hasn't 55 56 -- ** Building Folds 57 , folding, ifolding 58 , foldring, ifoldring 59 , folded 60 , folded64 61 , unfolded 62 , iterated 63 , filtered 64 , filteredBy 65 , backwards 66 , repeated 67 , replicated 68 , cycled 69 , takingWhile 70 , droppingWhile 71 , worded, lined 72 73 -- ** Folding 74 , foldMapOf, foldOf 75 , foldrOf, foldlOf 76 , toListOf, toNonEmptyOf 77 , anyOf, allOf, noneOf 78 , andOf, orOf 79 , productOf, sumOf 80 , traverseOf_, forOf_, sequenceAOf_ 81 , traverse1Of_, for1Of_, sequence1Of_ 82 , mapMOf_, forMOf_, sequenceOf_ 83 , asumOf, msumOf 84 , concatMapOf, concatOf 85 , elemOf, notElemOf 86 , lengthOf 87 , nullOf, notNullOf 88 , firstOf, first1Of, lastOf, last1Of 89 , maximumOf, maximum1Of, minimumOf, minimum1Of 90 , maximumByOf, minimumByOf 91 , findOf 92 , findMOf 93 , foldrOf', foldlOf' 94 , foldr1Of, foldl1Of 95 , foldr1Of', foldl1Of' 96 , foldrMOf, foldlMOf 97 , lookupOf 98 99 -- * Indexed Folds 100 , (^@..) 101 , (^@?) 102 , (^@?!) 103 104 -- ** Indexed Folding 105 , ifoldMapOf 106 , ifoldrOf 107 , ifoldlOf 108 , ianyOf 109 , iallOf 110 , inoneOf 111 , itraverseOf_ 112 , iforOf_ 113 , imapMOf_ 114 , iforMOf_ 115 , iconcatMapOf 116 , ifindOf 117 , ifindMOf 118 , ifoldrOf' 119 , ifoldlOf' 120 , ifoldrMOf 121 , ifoldlMOf 122 , itoListOf 123 , elemIndexOf 124 , elemIndicesOf 125 , findIndexOf 126 , findIndicesOf 127 128 -- ** Building Indexed Folds 129 , ifiltered 130 , itakingWhile 131 , idroppingWhile 132 133 -- * Internal types 134 , Leftmost 135 , Rightmost 136 , Traversed 137 , Sequenced 138 139 -- * Fold with Reified Monoid 140 , foldBy 141 , foldByOf 142 , foldMapBy 143 , foldMapByOf 144 ) where 145 146import Prelude () 147 148import Control.Applicative.Backwards 149import Control.Comonad 150import Control.Lens.Getter 151import Control.Lens.Internal.Fold 152import Control.Lens.Internal.Getter 153import Control.Lens.Internal.Indexed 154import Control.Lens.Internal.Magma 155import Control.Lens.Internal.Prelude 156import Control.Lens.Type 157import Control.Monad as Monad 158import Control.Monad.Reader 159import Control.Monad.State 160import Data.CallStack 161import Data.Functor.Apply hiding ((<.)) 162import Data.Int (Int64) 163import Data.List (intercalate) 164import Data.Maybe (fromMaybe) 165import Data.Monoid (First (..), All (..), Any (..)) 166#if MIN_VERSION_reflection(2,1,0) 167import Data.Reflection 168#endif 169 170import qualified Data.Semigroup as Semi 171 172-- $setup 173-- >>> :set -XNoOverloadedStrings 174-- >>> import Control.Lens 175-- >>> import Control.Lens.Extras (is) 176-- >>> import Data.Function 177-- >>> import Data.List.Lens 178-- >>> import Data.List.NonEmpty (NonEmpty (..)) 179-- >>> import Debug.SimpleReflect.Expr 180-- >>> import Debug.SimpleReflect.Vars as Vars hiding (f,g) 181-- >>> import Control.DeepSeq (NFData (..), force) 182-- >>> import Control.Exception (evaluate) 183-- >>> import Data.Maybe (fromMaybe) 184-- >>> import Data.Monoid (Sum (..)) 185-- >>> import System.Timeout (timeout) 186-- >>> import qualified Data.Map as Map 187-- >>> let f :: Expr -> Expr; f = Debug.SimpleReflect.Vars.f 188-- >>> let g :: Expr -> Expr; g = Debug.SimpleReflect.Vars.g 189-- >>> let timingOut :: NFData a => a -> IO a; timingOut = fmap (fromMaybe (error "timeout")) . timeout (5*10^6) . evaluate . force 190 191infixl 8 ^.., ^?, ^?!, ^@.., ^@?, ^@?! 192 193-------------------------- 194-- Folds 195-------------------------- 196 197-- | Obtain a 'Fold' by lifting an operation that returns a 'Foldable' result. 198-- 199-- This can be useful to lift operations from @Data.List@ and elsewhere into a 'Fold'. 200-- 201-- >>> [1,2,3,4]^..folding tail 202-- [2,3,4] 203folding :: Foldable f => (s -> f a) -> Fold s a 204folding sfa agb = phantom . traverse_ agb . sfa 205{-# INLINE folding #-} 206 207ifolding :: (Foldable f, Indexable i p, Contravariant g, Applicative g) => (s -> f (i, a)) -> Over p g s t a b 208ifolding sfa f = phantom . traverse_ (phantom . uncurry (indexed f)) . sfa 209{-# INLINE ifolding #-} 210 211-- | Obtain a 'Fold' by lifting 'foldr' like function. 212-- 213-- >>> [1,2,3,4]^..foldring foldr 214-- [1,2,3,4] 215foldring :: (Contravariant f, Applicative f) => ((a -> f a -> f a) -> f a -> s -> f a) -> LensLike f s t a b 216foldring fr f = phantom . fr (\a fa -> f a *> fa) noEffect 217{-# INLINE foldring #-} 218 219-- | Obtain 'FoldWithIndex' by lifting 'ifoldr' like function. 220ifoldring :: (Indexable i p, Contravariant f, Applicative f) => ((i -> a -> f a -> f a) -> f a -> s -> f a) -> Over p f s t a b 221ifoldring ifr f = phantom . ifr (\i a fa -> indexed f i a *> fa) noEffect 222{-# INLINE ifoldring #-} 223 224-- | Obtain a 'Fold' from any 'Foldable' indexed by ordinal position. 225-- 226-- >>> Just 3^..folded 227-- [3] 228-- 229-- >>> Nothing^..folded 230-- [] 231-- 232-- >>> [(1,2),(3,4)]^..folded.both 233-- [1,2,3,4] 234folded :: Foldable f => IndexedFold Int (f a) a 235folded = conjoined (foldring foldr) (ifoldring ifoldr) 236{-# INLINE folded #-} 237 238ifoldr :: Foldable f => (Int -> a -> b -> b) -> b -> f a -> b 239ifoldr f z xs = foldr (\ x g i -> i `seq` f i x (g (i+1))) (const z) xs 0 240{-# INLINE ifoldr #-} 241 242-- | Obtain a 'Fold' from any 'Foldable' indexed by ordinal position. 243folded64 :: Foldable f => IndexedFold Int64 (f a) a 244folded64 = conjoined (foldring foldr) (ifoldring ifoldr64) 245{-# INLINE folded64 #-} 246 247ifoldr64 :: Foldable f => (Int64 -> a -> b -> b) -> b -> f a -> b 248ifoldr64 f z xs = foldr (\ x g i -> i `seq` f i x (g (i+1))) (const z) xs 0 249{-# INLINE ifoldr64 #-} 250 251-- | Form a 'Fold1' by repeating the input forever. 252-- 253-- @ 254-- 'repeat' ≡ 'toListOf' 'repeated' 255-- @ 256-- 257-- >>> timingOut $ 5^..taking 20 repeated 258-- [5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5] 259-- 260-- @ 261-- 'repeated' :: 'Fold1' a a 262-- @ 263repeated :: Apply f => LensLike' f a a 264repeated f a = as where as = f a .> as 265{-# INLINE repeated #-} 266 267-- | A 'Fold' that replicates its input @n@ times. 268-- 269-- @ 270-- 'replicate' n ≡ 'toListOf' ('replicated' n) 271-- @ 272-- 273-- >>> 5^..replicated 20 274-- [5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5,5] 275replicated :: Int -> Fold a a 276replicated n0 f a = go n0 where 277 m = f a 278 go 0 = noEffect 279 go n = m *> go (n - 1) 280{-# INLINE replicated #-} 281 282-- | Transform a non-empty 'Fold' into a 'Fold1' that loops over its elements over and over. 283-- 284-- >>> timingOut $ [1,2,3]^..taking 7 (cycled traverse) 285-- [1,2,3,1,2,3,1] 286-- 287-- @ 288-- 'cycled' :: 'Fold1' s a -> 'Fold1' s a 289-- @ 290cycled :: Apply f => LensLike f s t a b -> LensLike f s t a b 291cycled l f a = as where as = l f a .> as 292{-# INLINE cycled #-} 293 294-- | Build a 'Fold' that unfolds its values from a seed. 295-- 296-- @ 297-- 'Prelude.unfoldr' ≡ 'toListOf' '.' 'unfolded' 298-- @ 299-- 300-- >>> 10^..unfolded (\b -> if b == 0 then Nothing else Just (b, b-1)) 301-- [10,9,8,7,6,5,4,3,2,1] 302unfolded :: (b -> Maybe (a, b)) -> Fold b a 303unfolded f g = go where 304 go b = case f b of 305 Just (a, b') -> g a *> go b' 306 Nothing -> noEffect 307{-# INLINE unfolded #-} 308 309-- | @x '^.' 'iterated' f@ returns an infinite 'Fold1' of repeated applications of @f@ to @x@. 310-- 311-- @ 312-- 'toListOf' ('iterated' f) a ≡ 'iterate' f a 313-- @ 314-- 315-- @ 316-- 'iterated' :: (a -> a) -> 'Fold1' a a 317-- @ 318iterated :: Apply f => (a -> a) -> LensLike' f a a 319iterated f g = go where 320 go a = g a .> go (f a) 321{-# INLINE iterated #-} 322 323-- | Obtain a 'Fold' that can be composed with to filter another 'Lens', 'Iso', 'Getter', 'Fold' (or 'Traversal'). 324-- 325-- Note: This is /not/ a legal 'Traversal', unless you are very careful not to invalidate the predicate on the target. 326-- 327-- Note: This is also /not/ a legal 'Prism', unless you are very careful not to inject a value that fails the predicate. 328-- 329-- As a counter example, consider that given @evens = 'filtered' 'even'@ the second 'Traversal' law is violated: 330-- 331-- @ 332-- 'Control.Lens.Setter.over' evens 'succ' '.' 'Control.Lens.Setter.over' evens 'succ' '/=' 'Control.Lens.Setter.over' evens ('succ' '.' 'succ') 333-- @ 334-- 335-- So, in order for this to qualify as a legal 'Traversal' you can only use it for actions that preserve the result of the predicate! 336-- 337-- >>> [1..10]^..folded.filtered even 338-- [2,4,6,8,10] 339-- 340-- This will preserve an index if it is present. 341filtered :: (Choice p, Applicative f) => (a -> Bool) -> Optic' p f a a 342filtered p = dimap (\x -> if p x then Right x else Left x) (either pure id) . right' 343{-# INLINE filtered #-} 344 345-- | Obtain a potentially empty 'IndexedTraversal' by taking the first element from another, 346-- potentially empty `Fold` and using it as an index. 347-- 348-- The resulting optic can be composed with to filter another 'Lens', 'Iso', 'Getter', 'Fold' (or 'Traversal'). 349-- 350-- >>> [(Just 2, 3), (Nothing, 4)] & mapped . filteredBy (_1 . _Just) <. _2 %@~ (*) :: [(Maybe Int, Int)] 351-- [(Just 2,6),(Nothing,4)] 352-- 353-- @ 354-- 'filteredBy' :: 'Fold' a i -> 'IndexedTraversal'' i a a 355-- @ 356-- 357-- Note: As with 'filtered', this is /not/ a legal 'IndexedTraversal', unless you are very careful not to invalidate the predicate on the target! 358filteredBy :: (Indexable i p, Applicative f) => Getting (First i) a i -> p a (f a) -> a -> f a 359filteredBy p f val = case val ^? p of 360 Nothing -> pure val 361 Just witness -> indexed f witness val 362 363-- | Obtain a 'Fold' by taking elements from another 'Fold', 'Lens', 'Iso', 'Getter' or 'Traversal' while a predicate holds. 364-- 365-- @ 366-- 'takeWhile' p ≡ 'toListOf' ('takingWhile' p 'folded') 367-- @ 368-- 369-- >>> timingOut $ toListOf (takingWhile (<=3) folded) [1..] 370-- [1,2,3] 371-- 372-- @ 373-- 'takingWhile' :: (a -> 'Bool') -> 'Fold' s a -> 'Fold' s a 374-- 'takingWhile' :: (a -> 'Bool') -> 'Getter' s a -> 'Fold' s a 375-- 'takingWhile' :: (a -> 'Bool') -> 'Traversal'' s a -> 'Fold' s a -- * See note below 376-- 'takingWhile' :: (a -> 'Bool') -> 'Lens'' s a -> 'Fold' s a -- * See note below 377-- 'takingWhile' :: (a -> 'Bool') -> 'Prism'' s a -> 'Fold' s a -- * See note below 378-- 'takingWhile' :: (a -> 'Bool') -> 'Iso'' s a -> 'Fold' s a -- * See note below 379-- 'takingWhile' :: (a -> 'Bool') -> 'IndexedTraversal'' i s a -> 'IndexedFold' i s a -- * See note below 380-- 'takingWhile' :: (a -> 'Bool') -> 'IndexedLens'' i s a -> 'IndexedFold' i s a -- * See note below 381-- 'takingWhile' :: (a -> 'Bool') -> 'IndexedFold' i s a -> 'IndexedFold' i s a 382-- 'takingWhile' :: (a -> 'Bool') -> 'IndexedGetter' i s a -> 'IndexedFold' i s a 383-- @ 384-- 385-- /Note:/ When applied to a 'Traversal', 'takingWhile' yields something that can be used as if it were a 'Traversal', but 386-- which is not a 'Traversal' per the laws, unless you are careful to ensure that you do not invalidate the predicate when 387-- writing back through it. 388takingWhile :: (Conjoined p, Applicative f) => (a -> Bool) -> Over p (TakingWhile p f a a) s t a a -> Over p f s t a a 389takingWhile p l pafb = fmap runMagma . traverse (cosieve pafb) . runTakingWhile . l flag where 390 flag = cotabulate $ \wa -> let a = extract wa; r = p a in TakingWhile r a $ \pr -> 391 if pr && r then Magma () wa else MagmaPure a 392{-# INLINE takingWhile #-} 393 394-- | Obtain a 'Fold' by dropping elements from another 'Fold', 'Lens', 'Iso', 'Getter' or 'Traversal' while a predicate holds. 395-- 396-- @ 397-- 'dropWhile' p ≡ 'toListOf' ('droppingWhile' p 'folded') 398-- @ 399-- 400-- >>> toListOf (droppingWhile (<=3) folded) [1..6] 401-- [4,5,6] 402-- 403-- >>> toListOf (droppingWhile (<=3) folded) [1,6,1] 404-- [6,1] 405-- 406-- @ 407-- 'droppingWhile' :: (a -> 'Bool') -> 'Fold' s a -> 'Fold' s a 408-- 'droppingWhile' :: (a -> 'Bool') -> 'Getter' s a -> 'Fold' s a 409-- 'droppingWhile' :: (a -> 'Bool') -> 'Traversal'' s a -> 'Fold' s a -- see notes 410-- 'droppingWhile' :: (a -> 'Bool') -> 'Lens'' s a -> 'Fold' s a -- see notes 411-- 'droppingWhile' :: (a -> 'Bool') -> 'Prism'' s a -> 'Fold' s a -- see notes 412-- 'droppingWhile' :: (a -> 'Bool') -> 'Iso'' s a -> 'Fold' s a -- see notes 413-- @ 414-- 415-- @ 416-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexPreservingTraversal'' s a -> 'IndexPreservingFold' s a -- see notes 417-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexPreservingLens'' s a -> 'IndexPreservingFold' s a -- see notes 418-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexPreservingGetter' s a -> 'IndexPreservingFold' s a 419-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexPreservingFold' s a -> 'IndexPreservingFold' s a 420-- @ 421-- 422-- @ 423-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexedTraversal'' i s a -> 'IndexedFold' i s a -- see notes 424-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexedLens'' i s a -> 'IndexedFold' i s a -- see notes 425-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexedGetter' i s a -> 'IndexedFold' i s a 426-- 'droppingWhile' :: (a -> 'Bool') -> 'IndexedFold' i s a -> 'IndexedFold' i s a 427-- @ 428-- 429-- Note: Many uses of this combinator will yield something that meets the types, but not the laws of a valid 430-- 'Traversal' or 'IndexedTraversal'. The 'Traversal' and 'IndexedTraversal' laws are only satisfied if the 431-- new values you assign to the first target also does not pass the predicate! Otherwise subsequent traversals 432-- will visit fewer elements and 'Traversal' fusion is not sound. 433-- 434-- So for any traversal @t@ and predicate @p@, @`droppingWhile` p t@ may not be lawful, but 435-- @(`Control.Lens.Traversal.dropping` 1 . `droppingWhile` p) t@ is. For example: 436-- 437-- >>> let l :: Traversal' [Int] Int; l = droppingWhile (<= 1) traverse 438-- >>> let l' :: Traversal' [Int] Int; l' = dropping 1 l 439-- 440-- @l@ is not a lawful setter because @`Control.Lens.Setter.over` l f . 441-- `Control.Lens.Setter.over` l g ≢ `Control.Lens.Setter.over` l (f . g)@: 442-- 443-- >>> [1,2,3] & l .~ 0 & l .~ 4 444-- [1,0,0] 445-- >>> [1,2,3] & l .~ 4 446-- [1,4,4] 447-- 448-- @l'@ on the other hand behaves lawfully: 449-- 450-- >>> [1,2,3] & l' .~ 0 & l' .~ 4 451-- [1,2,4] 452-- >>> [1,2,3] & l' .~ 4 453-- [1,2,4] 454droppingWhile :: (Conjoined p, Profunctor q, Applicative f) 455 => (a -> Bool) 456 -> Optical p q (Compose (State Bool) f) s t a a 457 -> Optical p q f s t a a 458droppingWhile p l f = (flip evalState True .# getCompose) `rmap` l g where 459 g = cotabulate $ \wa -> Compose $ state $ \b -> let 460 a = extract wa 461 b' = b && p a 462 in (if b' then pure a else cosieve f wa, b') 463{-# INLINE droppingWhile #-} 464 465-- | A 'Fold' over the individual 'words' of a 'String'. 466-- 467-- @ 468-- 'worded' :: 'Fold' 'String' 'String' 469-- 'worded' :: 'Traversal'' 'String' 'String' 470-- @ 471-- 472-- @ 473-- 'worded' :: 'IndexedFold' 'Int' 'String' 'String' 474-- 'worded' :: 'IndexedTraversal'' 'Int' 'String' 'String' 475-- @ 476-- 477-- Note: This function type-checks as a 'Traversal' but it doesn't satisfy the laws. It's only valid to use it 478-- when you don't insert any whitespace characters while traversing, and if your original 'String' contains only 479-- isolated space characters (and no other characters that count as space, such as non-breaking spaces). 480worded :: Applicative f => IndexedLensLike' Int f String String 481worded f = fmap unwords . conjoined traverse (indexing traverse) f . words 482{-# INLINE worded #-} 483 484-- | A 'Fold' over the individual 'lines' of a 'String'. 485-- 486-- @ 487-- 'lined' :: 'Fold' 'String' 'String' 488-- 'lined' :: 'Traversal'' 'String' 'String' 489-- @ 490-- 491-- @ 492-- 'lined' :: 'IndexedFold' 'Int' 'String' 'String' 493-- 'lined' :: 'IndexedTraversal'' 'Int' 'String' 'String' 494-- @ 495-- 496-- Note: This function type-checks as a 'Traversal' but it doesn't satisfy the laws. It's only valid to use it 497-- when you don't insert any newline characters while traversing, and if your original 'String' contains only 498-- isolated newline characters. 499lined :: Applicative f => IndexedLensLike' Int f String String 500lined f = fmap (intercalate "\n") . conjoined traverse (indexing traverse) f . lines 501{-# INLINE lined #-} 502 503-------------------------- 504-- Fold/Getter combinators 505-------------------------- 506 507-- | Map each part of a structure viewed through a 'Lens', 'Getter', 508-- 'Fold' or 'Traversal' to a monoid and combine the results. 509-- 510-- >>> foldMapOf (folded . both . _Just) Sum [(Just 21, Just 21)] 511-- Sum {getSum = 42} 512-- 513-- @ 514-- 'Data.Foldable.foldMap' = 'foldMapOf' 'folded' 515-- @ 516-- 517-- @ 518-- 'foldMapOf' ≡ 'views' 519-- 'ifoldMapOf' l = 'foldMapOf' l '.' 'Indexed' 520-- @ 521-- 522-- @ 523-- 'foldMapOf' :: 'Getter' s a -> (a -> r) -> s -> r 524-- 'foldMapOf' :: 'Monoid' r => 'Fold' s a -> (a -> r) -> s -> r 525-- 'foldMapOf' :: 'Semigroup' r => 'Fold1' s a -> (a -> r) -> s -> r 526-- 'foldMapOf' :: 'Lens'' s a -> (a -> r) -> s -> r 527-- 'foldMapOf' :: 'Iso'' s a -> (a -> r) -> s -> r 528-- 'foldMapOf' :: 'Monoid' r => 'Traversal'' s a -> (a -> r) -> s -> r 529-- 'foldMapOf' :: 'Semigroup' r => 'Traversal1'' s a -> (a -> r) -> s -> r 530-- 'foldMapOf' :: 'Monoid' r => 'Prism'' s a -> (a -> r) -> s -> r 531-- @ 532-- 533-- @ 534-- 'foldMapOf' :: 'Getting' r s a -> (a -> r) -> s -> r 535-- @ 536foldMapOf :: Getting r s a -> (a -> r) -> s -> r 537foldMapOf l f = getConst #. l (Const #. f) 538{-# INLINE foldMapOf #-} 539 540-- | Combine the elements of a structure viewed through a 'Lens', 'Getter', 541-- 'Fold' or 'Traversal' using a monoid. 542-- 543-- >>> foldOf (folded.folded) [[Sum 1,Sum 4],[Sum 8, Sum 8],[Sum 21]] 544-- Sum {getSum = 42} 545-- 546-- @ 547-- 'Data.Foldable.fold' = 'foldOf' 'folded' 548-- @ 549-- 550-- @ 551-- 'foldOf' ≡ 'view' 552-- @ 553-- 554-- @ 555-- 'foldOf' :: 'Getter' s m -> s -> m 556-- 'foldOf' :: 'Monoid' m => 'Fold' s m -> s -> m 557-- 'foldOf' :: 'Lens'' s m -> s -> m 558-- 'foldOf' :: 'Iso'' s m -> s -> m 559-- 'foldOf' :: 'Monoid' m => 'Traversal'' s m -> s -> m 560-- 'foldOf' :: 'Monoid' m => 'Prism'' s m -> s -> m 561-- @ 562foldOf :: Getting a s a -> s -> a 563foldOf l = getConst #. l Const 564{-# INLINE foldOf #-} 565 566-- | Right-associative fold of parts of a structure that are viewed through a 'Lens', 'Getter', 'Fold' or 'Traversal'. 567-- 568-- @ 569-- 'Data.Foldable.foldr' ≡ 'foldrOf' 'folded' 570-- @ 571-- 572-- @ 573-- 'foldrOf' :: 'Getter' s a -> (a -> r -> r) -> r -> s -> r 574-- 'foldrOf' :: 'Fold' s a -> (a -> r -> r) -> r -> s -> r 575-- 'foldrOf' :: 'Lens'' s a -> (a -> r -> r) -> r -> s -> r 576-- 'foldrOf' :: 'Iso'' s a -> (a -> r -> r) -> r -> s -> r 577-- 'foldrOf' :: 'Traversal'' s a -> (a -> r -> r) -> r -> s -> r 578-- 'foldrOf' :: 'Prism'' s a -> (a -> r -> r) -> r -> s -> r 579-- @ 580-- 581-- @ 582-- 'ifoldrOf' l ≡ 'foldrOf' l '.' 'Indexed' 583-- @ 584-- 585-- @ 586-- 'foldrOf' :: 'Getting' ('Endo' r) s a -> (a -> r -> r) -> r -> s -> r 587-- @ 588foldrOf :: Getting (Endo r) s a -> (a -> r -> r) -> r -> s -> r 589foldrOf l f z = flip appEndo z . foldMapOf l (Endo #. f) 590{-# INLINE foldrOf #-} 591 592-- | Left-associative fold of the parts of a structure that are viewed through a 'Lens', 'Getter', 'Fold' or 'Traversal'. 593-- 594-- @ 595-- 'Data.Foldable.foldl' ≡ 'foldlOf' 'folded' 596-- @ 597-- 598-- @ 599-- 'foldlOf' :: 'Getter' s a -> (r -> a -> r) -> r -> s -> r 600-- 'foldlOf' :: 'Fold' s a -> (r -> a -> r) -> r -> s -> r 601-- 'foldlOf' :: 'Lens'' s a -> (r -> a -> r) -> r -> s -> r 602-- 'foldlOf' :: 'Iso'' s a -> (r -> a -> r) -> r -> s -> r 603-- 'foldlOf' :: 'Traversal'' s a -> (r -> a -> r) -> r -> s -> r 604-- 'foldlOf' :: 'Prism'' s a -> (r -> a -> r) -> r -> s -> r 605-- @ 606foldlOf :: Getting (Dual (Endo r)) s a -> (r -> a -> r) -> r -> s -> r 607foldlOf l f z = (flip appEndo z .# getDual) `rmap` foldMapOf l (Dual #. Endo #. flip f) 608{-# INLINE foldlOf #-} 609 610-- | Extract a list of the targets of a 'Fold'. See also ('^..'). 611-- 612-- @ 613-- 'Data.Foldable.toList' ≡ 'toListOf' 'folded' 614-- ('^..') ≡ 'flip' 'toListOf' 615-- @ 616 617-- >>> toListOf both ("hello","world") 618-- ["hello","world"] 619-- 620-- @ 621-- 'toListOf' :: 'Getter' s a -> s -> [a] 622-- 'toListOf' :: 'Fold' s a -> s -> [a] 623-- 'toListOf' :: 'Lens'' s a -> s -> [a] 624-- 'toListOf' :: 'Iso'' s a -> s -> [a] 625-- 'toListOf' :: 'Traversal'' s a -> s -> [a] 626-- 'toListOf' :: 'Prism'' s a -> s -> [a] 627-- @ 628toListOf :: Getting (Endo [a]) s a -> s -> [a] 629toListOf l = foldrOf l (:) [] 630{-# INLINE toListOf #-} 631 632-- | Extract a 'NonEmpty' of the targets of 'Fold1'. 633-- 634-- >>> toNonEmptyOf both1 ("hello", "world") 635-- "hello" :| ["world"] 636-- 637-- @ 638-- 'toNonEmptyOf' :: 'Getter' s a -> s -> NonEmpty a 639-- 'toNonEmptyOf' :: 'Fold1' s a -> s -> NonEmpty a 640-- 'toNonEmptyOf' :: 'Lens'' s a -> s -> NonEmpty a 641-- 'toNonEmptyOf' :: 'Iso'' s a -> s -> NonEmpty a 642-- 'toNonEmptyOf' :: 'Traversal1'' s a -> s -> NonEmpty a 643-- 'toNonEmptyOf' :: 'Prism'' s a -> s -> NonEmpty a 644-- @ 645toNonEmptyOf :: Getting (NonEmptyDList a) s a -> s -> NonEmpty a 646toNonEmptyOf l = flip getNonEmptyDList [] . foldMapOf l (NonEmptyDList #. (:|)) 647 648-- | A convenient infix (flipped) version of 'toListOf'. 649-- 650-- >>> [[1,2],[3]]^..id 651-- [[[1,2],[3]]] 652-- >>> [[1,2],[3]]^..traverse 653-- [[1,2],[3]] 654-- >>> [[1,2],[3]]^..traverse.traverse 655-- [1,2,3] 656-- 657-- >>> (1,2)^..both 658-- [1,2] 659-- 660-- @ 661-- 'Data.Foldable.toList' xs ≡ xs '^..' 'folded' 662-- ('^..') ≡ 'flip' 'toListOf' 663-- @ 664-- 665-- @ 666-- ('^..') :: s -> 'Getter' s a -> [a] 667-- ('^..') :: s -> 'Fold' s a -> [a] 668-- ('^..') :: s -> 'Lens'' s a -> [a] 669-- ('^..') :: s -> 'Iso'' s a -> [a] 670-- ('^..') :: s -> 'Traversal'' s a -> [a] 671-- ('^..') :: s -> 'Prism'' s a -> [a] 672-- @ 673(^..) :: s -> Getting (Endo [a]) s a -> [a] 674s ^.. l = toListOf l s 675{-# INLINE (^..) #-} 676 677-- | Returns 'True' if every target of a 'Fold' is 'True'. 678-- 679-- >>> andOf both (True,False) 680-- False 681-- >>> andOf both (True,True) 682-- True 683-- 684-- @ 685-- 'Data.Foldable.and' ≡ 'andOf' 'folded' 686-- @ 687-- 688-- @ 689-- 'andOf' :: 'Getter' s 'Bool' -> s -> 'Bool' 690-- 'andOf' :: 'Fold' s 'Bool' -> s -> 'Bool' 691-- 'andOf' :: 'Lens'' s 'Bool' -> s -> 'Bool' 692-- 'andOf' :: 'Iso'' s 'Bool' -> s -> 'Bool' 693-- 'andOf' :: 'Traversal'' s 'Bool' -> s -> 'Bool' 694-- 'andOf' :: 'Prism'' s 'Bool' -> s -> 'Bool' 695-- @ 696andOf :: Getting All s Bool -> s -> Bool 697andOf l = getAll #. foldMapOf l All 698{-# INLINE andOf #-} 699 700-- | Returns 'True' if any target of a 'Fold' is 'True'. 701-- 702-- >>> orOf both (True,False) 703-- True 704-- >>> orOf both (False,False) 705-- False 706-- 707-- @ 708-- 'Data.Foldable.or' ≡ 'orOf' 'folded' 709-- @ 710-- 711-- @ 712-- 'orOf' :: 'Getter' s 'Bool' -> s -> 'Bool' 713-- 'orOf' :: 'Fold' s 'Bool' -> s -> 'Bool' 714-- 'orOf' :: 'Lens'' s 'Bool' -> s -> 'Bool' 715-- 'orOf' :: 'Iso'' s 'Bool' -> s -> 'Bool' 716-- 'orOf' :: 'Traversal'' s 'Bool' -> s -> 'Bool' 717-- 'orOf' :: 'Prism'' s 'Bool' -> s -> 'Bool' 718-- @ 719orOf :: Getting Any s Bool -> s -> Bool 720orOf l = getAny #. foldMapOf l Any 721{-# INLINE orOf #-} 722 723-- | Returns 'True' if any target of a 'Fold' satisfies a predicate. 724-- 725-- >>> anyOf both (=='x') ('x','y') 726-- True 727-- >>> import Data.Data.Lens 728-- >>> anyOf biplate (== "world") (((),2::Int),"hello",("world",11::Int)) 729-- True 730-- 731-- @ 732-- 'Data.Foldable.any' ≡ 'anyOf' 'folded' 733-- @ 734-- 735-- @ 736-- 'ianyOf' l ≡ 'anyOf' l '.' 'Indexed' 737-- @ 738-- 739-- @ 740-- 'anyOf' :: 'Getter' s a -> (a -> 'Bool') -> s -> 'Bool' 741-- 'anyOf' :: 'Fold' s a -> (a -> 'Bool') -> s -> 'Bool' 742-- 'anyOf' :: 'Lens'' s a -> (a -> 'Bool') -> s -> 'Bool' 743-- 'anyOf' :: 'Iso'' s a -> (a -> 'Bool') -> s -> 'Bool' 744-- 'anyOf' :: 'Traversal'' s a -> (a -> 'Bool') -> s -> 'Bool' 745-- 'anyOf' :: 'Prism'' s a -> (a -> 'Bool') -> s -> 'Bool' 746-- @ 747anyOf :: Getting Any s a -> (a -> Bool) -> s -> Bool 748anyOf l f = getAny #. foldMapOf l (Any #. f) 749{-# INLINE anyOf #-} 750 751-- | Returns 'True' if every target of a 'Fold' satisfies a predicate. 752-- 753-- >>> allOf both (>=3) (4,5) 754-- True 755-- >>> allOf folded (>=2) [1..10] 756-- False 757-- 758-- @ 759-- 'Data.Foldable.all' ≡ 'allOf' 'folded' 760-- @ 761-- 762-- @ 763-- 'iallOf' l = 'allOf' l '.' 'Indexed' 764-- @ 765-- 766-- @ 767-- 'allOf' :: 'Getter' s a -> (a -> 'Bool') -> s -> 'Bool' 768-- 'allOf' :: 'Fold' s a -> (a -> 'Bool') -> s -> 'Bool' 769-- 'allOf' :: 'Lens'' s a -> (a -> 'Bool') -> s -> 'Bool' 770-- 'allOf' :: 'Iso'' s a -> (a -> 'Bool') -> s -> 'Bool' 771-- 'allOf' :: 'Traversal'' s a -> (a -> 'Bool') -> s -> 'Bool' 772-- 'allOf' :: 'Prism'' s a -> (a -> 'Bool') -> s -> 'Bool' 773-- @ 774allOf :: Getting All s a -> (a -> Bool) -> s -> Bool 775allOf l f = getAll #. foldMapOf l (All #. f) 776{-# INLINE allOf #-} 777 778-- | Returns 'True' only if no targets of a 'Fold' satisfy a predicate. 779-- 780-- >>> noneOf each (is _Nothing) (Just 3, Just 4, Just 5) 781-- True 782-- >>> noneOf (folded.folded) (<10) [[13,99,20],[3,71,42]] 783-- False 784-- 785-- @ 786-- 'inoneOf' l = 'noneOf' l '.' 'Indexed' 787-- @ 788-- 789-- @ 790-- 'noneOf' :: 'Getter' s a -> (a -> 'Bool') -> s -> 'Bool' 791-- 'noneOf' :: 'Fold' s a -> (a -> 'Bool') -> s -> 'Bool' 792-- 'noneOf' :: 'Lens'' s a -> (a -> 'Bool') -> s -> 'Bool' 793-- 'noneOf' :: 'Iso'' s a -> (a -> 'Bool') -> s -> 'Bool' 794-- 'noneOf' :: 'Traversal'' s a -> (a -> 'Bool') -> s -> 'Bool' 795-- 'noneOf' :: 'Prism'' s a -> (a -> 'Bool') -> s -> 'Bool' 796-- @ 797noneOf :: Getting Any s a -> (a -> Bool) -> s -> Bool 798noneOf l f = not . anyOf l f 799{-# INLINE noneOf #-} 800 801-- | Calculate the 'Product' of every number targeted by a 'Fold'. 802-- 803-- >>> productOf both (4,5) 804-- 20 805-- >>> productOf folded [1,2,3,4,5] 806-- 120 807-- 808-- @ 809-- 'Data.Foldable.product' ≡ 'productOf' 'folded' 810-- @ 811-- 812-- This operation may be more strict than you would expect. If you 813-- want a lazier version use @'ala' 'Product' '.' 'foldMapOf'@ 814-- 815-- @ 816-- 'productOf' :: 'Num' a => 'Getter' s a -> s -> a 817-- 'productOf' :: 'Num' a => 'Fold' s a -> s -> a 818-- 'productOf' :: 'Num' a => 'Lens'' s a -> s -> a 819-- 'productOf' :: 'Num' a => 'Iso'' s a -> s -> a 820-- 'productOf' :: 'Num' a => 'Traversal'' s a -> s -> a 821-- 'productOf' :: 'Num' a => 'Prism'' s a -> s -> a 822-- @ 823productOf :: Num a => Getting (Endo (Endo a)) s a -> s -> a 824productOf l = foldlOf' l (*) 1 825{-# INLINE productOf #-} 826 827-- | Calculate the 'Sum' of every number targeted by a 'Fold'. 828-- 829-- >>> sumOf both (5,6) 830-- 11 831-- >>> sumOf folded [1,2,3,4] 832-- 10 833-- >>> sumOf (folded.both) [(1,2),(3,4)] 834-- 10 835-- >>> import Data.Data.Lens 836-- >>> sumOf biplate [(1::Int,[]),(2,[(3::Int,4::Int)])] :: Int 837-- 10 838-- 839-- @ 840-- 'Data.Foldable.sum' ≡ 'sumOf' 'folded' 841-- @ 842-- 843-- This operation may be more strict than you would expect. If you 844-- want a lazier version use @'ala' 'Sum' '.' 'foldMapOf'@ 845-- 846-- @ 847-- 'sumOf' '_1' :: 'Num' a => (a, b) -> a 848-- 'sumOf' ('folded' '.' 'Control.Lens.Tuple._1') :: ('Foldable' f, 'Num' a) => f (a, b) -> a 849-- @ 850-- 851-- @ 852-- 'sumOf' :: 'Num' a => 'Getter' s a -> s -> a 853-- 'sumOf' :: 'Num' a => 'Fold' s a -> s -> a 854-- 'sumOf' :: 'Num' a => 'Lens'' s a -> s -> a 855-- 'sumOf' :: 'Num' a => 'Iso'' s a -> s -> a 856-- 'sumOf' :: 'Num' a => 'Traversal'' s a -> s -> a 857-- 'sumOf' :: 'Num' a => 'Prism'' s a -> s -> a 858-- @ 859sumOf :: Num a => Getting (Endo (Endo a)) s a -> s -> a 860sumOf l = foldlOf' l (+) 0 861{-# INLINE sumOf #-} 862 863-- | Traverse over all of the targets of a 'Fold' (or 'Getter'), computing an 'Applicative' (or 'Functor')-based answer, 864-- but unlike 'Control.Lens.Traversal.traverseOf' do not construct a new structure. 'traverseOf_' generalizes 865-- 'Data.Foldable.traverse_' to work over any 'Fold'. 866-- 867-- When passed a 'Getter', 'traverseOf_' can work over any 'Functor', but when passed a 'Fold', 'traverseOf_' requires 868-- an 'Applicative'. 869-- 870-- >>> traverseOf_ both putStrLn ("hello","world") 871-- hello 872-- world 873-- 874-- @ 875-- 'Data.Foldable.traverse_' ≡ 'traverseOf_' 'folded' 876-- @ 877-- 878-- @ 879-- 'traverseOf_' '_2' :: 'Functor' f => (c -> f r) -> (d, c) -> f () 880-- 'traverseOf_' 'Control.Lens.Prism._Left' :: 'Applicative' f => (a -> f b) -> 'Either' a c -> f () 881-- @ 882-- 883-- @ 884-- 'itraverseOf_' l ≡ 'traverseOf_' l '.' 'Indexed' 885-- @ 886-- 887-- The rather specific signature of 'traverseOf_' allows it to be used as if the signature was any of: 888-- 889-- @ 890-- 'traverseOf_' :: 'Functor' f => 'Getter' s a -> (a -> f r) -> s -> f () 891-- 'traverseOf_' :: 'Applicative' f => 'Fold' s a -> (a -> f r) -> s -> f () 892-- 'traverseOf_' :: 'Functor' f => 'Lens'' s a -> (a -> f r) -> s -> f () 893-- 'traverseOf_' :: 'Functor' f => 'Iso'' s a -> (a -> f r) -> s -> f () 894-- 'traverseOf_' :: 'Applicative' f => 'Traversal'' s a -> (a -> f r) -> s -> f () 895-- 'traverseOf_' :: 'Applicative' f => 'Prism'' s a -> (a -> f r) -> s -> f () 896-- @ 897traverseOf_ :: Functor f => Getting (Traversed r f) s a -> (a -> f r) -> s -> f () 898traverseOf_ l f = void . getTraversed #. foldMapOf l (Traversed #. f) 899{-# INLINE traverseOf_ #-} 900 901-- | Traverse over all of the targets of a 'Fold' (or 'Getter'), computing an 'Applicative' (or 'Functor')-based answer, 902-- but unlike 'Control.Lens.Traversal.forOf' do not construct a new structure. 'forOf_' generalizes 903-- 'Data.Foldable.for_' to work over any 'Fold'. 904-- 905-- When passed a 'Getter', 'forOf_' can work over any 'Functor', but when passed a 'Fold', 'forOf_' requires 906-- an 'Applicative'. 907-- 908-- @ 909-- 'for_' ≡ 'forOf_' 'folded' 910-- @ 911-- 912-- >>> forOf_ both ("hello","world") putStrLn 913-- hello 914-- world 915-- 916-- The rather specific signature of 'forOf_' allows it to be used as if the signature was any of: 917-- 918-- @ 919-- 'iforOf_' l s ≡ 'forOf_' l s '.' 'Indexed' 920-- @ 921-- 922-- @ 923-- 'forOf_' :: 'Functor' f => 'Getter' s a -> s -> (a -> f r) -> f () 924-- 'forOf_' :: 'Applicative' f => 'Fold' s a -> s -> (a -> f r) -> f () 925-- 'forOf_' :: 'Functor' f => 'Lens'' s a -> s -> (a -> f r) -> f () 926-- 'forOf_' :: 'Functor' f => 'Iso'' s a -> s -> (a -> f r) -> f () 927-- 'forOf_' :: 'Applicative' f => 'Traversal'' s a -> s -> (a -> f r) -> f () 928-- 'forOf_' :: 'Applicative' f => 'Prism'' s a -> s -> (a -> f r) -> f () 929-- @ 930forOf_ :: Functor f => Getting (Traversed r f) s a -> s -> (a -> f r) -> f () 931forOf_ = flip . traverseOf_ 932{-# INLINE forOf_ #-} 933 934-- | Evaluate each action in observed by a 'Fold' on a structure from left to right, ignoring the results. 935-- 936-- @ 937-- 'sequenceA_' ≡ 'sequenceAOf_' 'folded' 938-- @ 939-- 940-- >>> sequenceAOf_ both (putStrLn "hello",putStrLn "world") 941-- hello 942-- world 943-- 944-- @ 945-- 'sequenceAOf_' :: 'Functor' f => 'Getter' s (f a) -> s -> f () 946-- 'sequenceAOf_' :: 'Applicative' f => 'Fold' s (f a) -> s -> f () 947-- 'sequenceAOf_' :: 'Functor' f => 'Lens'' s (f a) -> s -> f () 948-- 'sequenceAOf_' :: 'Functor' f => 'Iso'' s (f a) -> s -> f () 949-- 'sequenceAOf_' :: 'Applicative' f => 'Traversal'' s (f a) -> s -> f () 950-- 'sequenceAOf_' :: 'Applicative' f => 'Prism'' s (f a) -> s -> f () 951-- @ 952sequenceAOf_ :: Functor f => Getting (Traversed a f) s (f a) -> s -> f () 953sequenceAOf_ l = void . getTraversed #. foldMapOf l Traversed 954{-# INLINE sequenceAOf_ #-} 955 956-- | Traverse over all of the targets of a 'Fold1', computing an 'Apply' based answer. 957-- 958-- As long as you have 'Applicative' or 'Functor' effect you are better using 'traverseOf_'. 959-- The 'traverse1Of_' is useful only when you have genuine 'Apply' effect. 960-- 961-- >>> traverse1Of_ both1 (\ks -> Map.fromList [ (k, ()) | k <- ks ]) ("abc", "bcd") 962-- fromList [('b',()),('c',())] 963-- 964-- @ 965-- 'traverse1Of_' :: 'Apply' f => 'Fold1' s a -> (a -> f r) -> s -> f () 966-- @ 967-- 968-- @since 4.16 969traverse1Of_ :: Functor f => Getting (TraversedF r f) s a -> (a -> f r) -> s -> f () 970traverse1Of_ l f = void . getTraversedF #. foldMapOf l (TraversedF #. f) 971{-# INLINE traverse1Of_ #-} 972 973-- | See 'forOf_' and 'traverse1Of_'. 974-- 975-- >>> for1Of_ both1 ("abc", "bcd") (\ks -> Map.fromList [ (k, ()) | k <- ks ]) 976-- fromList [('b',()),('c',())] 977-- 978-- @ 979-- 'for1Of_' :: 'Apply' f => 'Fold1' s a -> s -> (a -> f r) -> f () 980-- @ 981-- 982-- @since 4.16 983for1Of_ :: Functor f => Getting (TraversedF r f) s a -> s -> (a -> f r) -> f () 984for1Of_ = flip . traverse1Of_ 985{-# INLINE for1Of_ #-} 986 987-- | See 'sequenceAOf_' and 'traverse1Of_'. 988-- 989-- @ 990-- 'sequence1Of_' :: 'Apply' f => 'Fold1' s (f a) -> s -> f () 991-- @ 992-- 993-- @since 4.16 994sequence1Of_ :: Functor f => Getting (TraversedF a f) s (f a) -> s -> f () 995sequence1Of_ l = void . getTraversedF #. foldMapOf l TraversedF 996{-# INLINE sequence1Of_ #-} 997 998-- | Map each target of a 'Fold' on a structure to a monadic action, evaluate these actions from left to right, and ignore the results. 999-- 1000-- >>> mapMOf_ both putStrLn ("hello","world") 1001-- hello 1002-- world 1003-- 1004-- @ 1005-- 'Data.Foldable.mapM_' ≡ 'mapMOf_' 'folded' 1006-- @ 1007-- 1008-- @ 1009-- 'mapMOf_' :: 'Monad' m => 'Getter' s a -> (a -> m r) -> s -> m () 1010-- 'mapMOf_' :: 'Monad' m => 'Fold' s a -> (a -> m r) -> s -> m () 1011-- 'mapMOf_' :: 'Monad' m => 'Lens'' s a -> (a -> m r) -> s -> m () 1012-- 'mapMOf_' :: 'Monad' m => 'Iso'' s a -> (a -> m r) -> s -> m () 1013-- 'mapMOf_' :: 'Monad' m => 'Traversal'' s a -> (a -> m r) -> s -> m () 1014-- 'mapMOf_' :: 'Monad' m => 'Prism'' s a -> (a -> m r) -> s -> m () 1015-- @ 1016mapMOf_ :: Monad m => Getting (Sequenced r m) s a -> (a -> m r) -> s -> m () 1017mapMOf_ l f = liftM skip . getSequenced #. foldMapOf l (Sequenced #. f) 1018{-# INLINE mapMOf_ #-} 1019 1020-- | 'forMOf_' is 'mapMOf_' with two of its arguments flipped. 1021-- 1022-- >>> forMOf_ both ("hello","world") putStrLn 1023-- hello 1024-- world 1025-- 1026-- @ 1027-- 'Data.Foldable.forM_' ≡ 'forMOf_' 'folded' 1028-- @ 1029-- 1030-- @ 1031-- 'forMOf_' :: 'Monad' m => 'Getter' s a -> s -> (a -> m r) -> m () 1032-- 'forMOf_' :: 'Monad' m => 'Fold' s a -> s -> (a -> m r) -> m () 1033-- 'forMOf_' :: 'Monad' m => 'Lens'' s a -> s -> (a -> m r) -> m () 1034-- 'forMOf_' :: 'Monad' m => 'Iso'' s a -> s -> (a -> m r) -> m () 1035-- 'forMOf_' :: 'Monad' m => 'Traversal'' s a -> s -> (a -> m r) -> m () 1036-- 'forMOf_' :: 'Monad' m => 'Prism'' s a -> s -> (a -> m r) -> m () 1037-- @ 1038forMOf_ :: Monad m => Getting (Sequenced r m) s a -> s -> (a -> m r) -> m () 1039forMOf_ = flip . mapMOf_ 1040{-# INLINE forMOf_ #-} 1041 1042-- | Evaluate each monadic action referenced by a 'Fold' on the structure from left to right, and ignore the results. 1043-- 1044-- >>> sequenceOf_ both (putStrLn "hello",putStrLn "world") 1045-- hello 1046-- world 1047-- 1048-- @ 1049-- 'Data.Foldable.sequence_' ≡ 'sequenceOf_' 'folded' 1050-- @ 1051-- 1052-- @ 1053-- 'sequenceOf_' :: 'Monad' m => 'Getter' s (m a) -> s -> m () 1054-- 'sequenceOf_' :: 'Monad' m => 'Fold' s (m a) -> s -> m () 1055-- 'sequenceOf_' :: 'Monad' m => 'Lens'' s (m a) -> s -> m () 1056-- 'sequenceOf_' :: 'Monad' m => 'Iso'' s (m a) -> s -> m () 1057-- 'sequenceOf_' :: 'Monad' m => 'Traversal'' s (m a) -> s -> m () 1058-- 'sequenceOf_' :: 'Monad' m => 'Prism'' s (m a) -> s -> m () 1059-- @ 1060sequenceOf_ :: Monad m => Getting (Sequenced a m) s (m a) -> s -> m () 1061sequenceOf_ l = liftM skip . getSequenced #. foldMapOf l Sequenced 1062{-# INLINE sequenceOf_ #-} 1063 1064-- | The sum of a collection of actions, generalizing 'concatOf'. 1065-- 1066-- >>> asumOf both ("hello","world") 1067-- "helloworld" 1068-- 1069-- >>> asumOf each (Nothing, Just "hello", Nothing) 1070-- Just "hello" 1071-- 1072-- @ 1073-- 'asum' ≡ 'asumOf' 'folded' 1074-- @ 1075-- 1076-- @ 1077-- 'asumOf' :: 'Alternative' f => 'Getter' s (f a) -> s -> f a 1078-- 'asumOf' :: 'Alternative' f => 'Fold' s (f a) -> s -> f a 1079-- 'asumOf' :: 'Alternative' f => 'Lens'' s (f a) -> s -> f a 1080-- 'asumOf' :: 'Alternative' f => 'Iso'' s (f a) -> s -> f a 1081-- 'asumOf' :: 'Alternative' f => 'Traversal'' s (f a) -> s -> f a 1082-- 'asumOf' :: 'Alternative' f => 'Prism'' s (f a) -> s -> f a 1083-- @ 1084asumOf :: Alternative f => Getting (Endo (f a)) s (f a) -> s -> f a 1085asumOf l = foldrOf l (<|>) empty 1086{-# INLINE asumOf #-} 1087 1088-- | The sum of a collection of actions, generalizing 'concatOf'. 1089-- 1090-- >>> msumOf both ("hello","world") 1091-- "helloworld" 1092-- 1093-- >>> msumOf each (Nothing, Just "hello", Nothing) 1094-- Just "hello" 1095-- 1096-- @ 1097-- 'msum' ≡ 'msumOf' 'folded' 1098-- @ 1099-- 1100-- @ 1101-- 'msumOf' :: 'MonadPlus' m => 'Getter' s (m a) -> s -> m a 1102-- 'msumOf' :: 'MonadPlus' m => 'Fold' s (m a) -> s -> m a 1103-- 'msumOf' :: 'MonadPlus' m => 'Lens'' s (m a) -> s -> m a 1104-- 'msumOf' :: 'MonadPlus' m => 'Iso'' s (m a) -> s -> m a 1105-- 'msumOf' :: 'MonadPlus' m => 'Traversal'' s (m a) -> s -> m a 1106-- 'msumOf' :: 'MonadPlus' m => 'Prism'' s (m a) -> s -> m a 1107-- @ 1108msumOf :: MonadPlus m => Getting (Endo (m a)) s (m a) -> s -> m a 1109msumOf l = foldrOf l mplus mzero 1110{-# INLINE msumOf #-} 1111 1112-- | Does the element occur anywhere within a given 'Fold' of the structure? 1113-- 1114-- >>> elemOf both "hello" ("hello","world") 1115-- True 1116-- 1117-- @ 1118-- 'elem' ≡ 'elemOf' 'folded' 1119-- @ 1120-- 1121-- @ 1122-- 'elemOf' :: 'Eq' a => 'Getter' s a -> a -> s -> 'Bool' 1123-- 'elemOf' :: 'Eq' a => 'Fold' s a -> a -> s -> 'Bool' 1124-- 'elemOf' :: 'Eq' a => 'Lens'' s a -> a -> s -> 'Bool' 1125-- 'elemOf' :: 'Eq' a => 'Iso'' s a -> a -> s -> 'Bool' 1126-- 'elemOf' :: 'Eq' a => 'Traversal'' s a -> a -> s -> 'Bool' 1127-- 'elemOf' :: 'Eq' a => 'Prism'' s a -> a -> s -> 'Bool' 1128-- @ 1129elemOf :: Eq a => Getting Any s a -> a -> s -> Bool 1130elemOf l = anyOf l . (==) 1131{-# INLINE elemOf #-} 1132 1133-- | Does the element not occur anywhere within a given 'Fold' of the structure? 1134-- 1135-- >>> notElemOf each 'd' ('a','b','c') 1136-- True 1137-- 1138-- >>> notElemOf each 'a' ('a','b','c') 1139-- False 1140-- 1141-- @ 1142-- 'notElem' ≡ 'notElemOf' 'folded' 1143-- @ 1144-- 1145-- @ 1146-- 'notElemOf' :: 'Eq' a => 'Getter' s a -> a -> s -> 'Bool' 1147-- 'notElemOf' :: 'Eq' a => 'Fold' s a -> a -> s -> 'Bool' 1148-- 'notElemOf' :: 'Eq' a => 'Iso'' s a -> a -> s -> 'Bool' 1149-- 'notElemOf' :: 'Eq' a => 'Lens'' s a -> a -> s -> 'Bool' 1150-- 'notElemOf' :: 'Eq' a => 'Traversal'' s a -> a -> s -> 'Bool' 1151-- 'notElemOf' :: 'Eq' a => 'Prism'' s a -> a -> s -> 'Bool' 1152-- @ 1153notElemOf :: Eq a => Getting All s a -> a -> s -> Bool 1154notElemOf l = allOf l . (/=) 1155{-# INLINE notElemOf #-} 1156 1157-- | Map a function over all the targets of a 'Fold' of a container and concatenate the resulting lists. 1158-- 1159-- >>> concatMapOf both (\x -> [x, x + 1]) (1,3) 1160-- [1,2,3,4] 1161-- 1162-- @ 1163-- 'concatMap' ≡ 'concatMapOf' 'folded' 1164-- @ 1165-- 1166-- @ 1167-- 'concatMapOf' :: 'Getter' s a -> (a -> [r]) -> s -> [r] 1168-- 'concatMapOf' :: 'Fold' s a -> (a -> [r]) -> s -> [r] 1169-- 'concatMapOf' :: 'Lens'' s a -> (a -> [r]) -> s -> [r] 1170-- 'concatMapOf' :: 'Iso'' s a -> (a -> [r]) -> s -> [r] 1171-- 'concatMapOf' :: 'Traversal'' s a -> (a -> [r]) -> s -> [r] 1172-- @ 1173concatMapOf :: Getting [r] s a -> (a -> [r]) -> s -> [r] 1174concatMapOf l ces = getConst #. l (Const #. ces) 1175{-# INLINE concatMapOf #-} 1176 1177-- | Concatenate all of the lists targeted by a 'Fold' into a longer list. 1178-- 1179-- >>> concatOf both ("pan","ama") 1180-- "panama" 1181-- 1182-- @ 1183-- 'concat' ≡ 'concatOf' 'folded' 1184-- 'concatOf' ≡ 'view' 1185-- @ 1186-- 1187-- @ 1188-- 'concatOf' :: 'Getter' s [r] -> s -> [r] 1189-- 'concatOf' :: 'Fold' s [r] -> s -> [r] 1190-- 'concatOf' :: 'Iso'' s [r] -> s -> [r] 1191-- 'concatOf' :: 'Lens'' s [r] -> s -> [r] 1192-- 'concatOf' :: 'Traversal'' s [r] -> s -> [r] 1193-- @ 1194concatOf :: Getting [r] s [r] -> s -> [r] 1195concatOf l = getConst #. l Const 1196{-# INLINE concatOf #-} 1197 1198 1199-- | Calculate the number of targets there are for a 'Fold' in a given container. 1200-- 1201-- /Note:/ This can be rather inefficient for large containers and just like 'length', 1202-- this will not terminate for infinite folds. 1203-- 1204-- @ 1205-- 'length' ≡ 'lengthOf' 'folded' 1206-- @ 1207-- 1208-- >>> lengthOf _1 ("hello",()) 1209-- 1 1210-- 1211-- >>> lengthOf traverse [1..10] 1212-- 10 1213-- 1214-- >>> lengthOf (traverse.traverse) [[1,2],[3,4],[5,6]] 1215-- 6 1216-- 1217-- @ 1218-- 'lengthOf' ('folded' '.' 'folded') :: ('Foldable' f, 'Foldable' g) => f (g a) -> 'Int' 1219-- @ 1220-- 1221-- @ 1222-- 'lengthOf' :: 'Getter' s a -> s -> 'Int' 1223-- 'lengthOf' :: 'Fold' s a -> s -> 'Int' 1224-- 'lengthOf' :: 'Lens'' s a -> s -> 'Int' 1225-- 'lengthOf' :: 'Iso'' s a -> s -> 'Int' 1226-- 'lengthOf' :: 'Traversal'' s a -> s -> 'Int' 1227-- @ 1228lengthOf :: Getting (Endo (Endo Int)) s a -> s -> Int 1229lengthOf l = foldlOf' l (\a _ -> a + 1) 0 1230{-# INLINE lengthOf #-} 1231 1232-- | Perform a safe 'head' of a 'Fold' or 'Traversal' or retrieve 'Just' the result 1233-- from a 'Getter' or 'Lens'. 1234-- 1235-- When using a 'Traversal' as a partial 'Lens', or a 'Fold' as a partial 'Getter' this can be a convenient 1236-- way to extract the optional value. 1237-- 1238-- Note: if you get stack overflows due to this, you may want to use 'firstOf' instead, which can deal 1239-- more gracefully with heavily left-biased trees. This is because '^?' works by using the 1240-- 'Data.Monoid.First' monoid, which can occasionally cause space leaks. 1241-- 1242-- >>> Left 4 ^?_Left 1243-- Just 4 1244-- 1245-- >>> Right 4 ^?_Left 1246-- Nothing 1247-- 1248-- >>> "world" ^? ix 3 1249-- Just 'l' 1250-- 1251-- >>> "world" ^? ix 20 1252-- Nothing 1253-- 1254-- This operator works as an infix version of 'preview'. 1255-- 1256-- @ 1257-- ('^?') ≡ 'flip' 'preview' 1258-- @ 1259-- 1260-- It may be helpful to think of '^?' as having one of the following 1261-- more specialized types: 1262-- 1263-- @ 1264-- ('^?') :: s -> 'Getter' s a -> 'Maybe' a 1265-- ('^?') :: s -> 'Fold' s a -> 'Maybe' a 1266-- ('^?') :: s -> 'Lens'' s a -> 'Maybe' a 1267-- ('^?') :: s -> 'Iso'' s a -> 'Maybe' a 1268-- ('^?') :: s -> 'Traversal'' s a -> 'Maybe' a 1269-- @ 1270(^?) :: s -> Getting (First a) s a -> Maybe a 1271s ^? l = getFirst (foldMapOf l (First #. Just) s) 1272{-# INLINE (^?) #-} 1273 1274-- | Perform an *UNSAFE* 'head' of a 'Fold' or 'Traversal' assuming that it is there. 1275-- 1276-- >>> Left 4 ^?! _Left 1277-- 4 1278-- 1279-- >>> "world" ^?! ix 3 1280-- 'l' 1281-- 1282-- @ 1283-- ('^?!') :: s -> 'Getter' s a -> a 1284-- ('^?!') :: s -> 'Fold' s a -> a 1285-- ('^?!') :: s -> 'Lens'' s a -> a 1286-- ('^?!') :: s -> 'Iso'' s a -> a 1287-- ('^?!') :: s -> 'Traversal'' s a -> a 1288-- @ 1289(^?!) :: HasCallStack => s -> Getting (Endo a) s a -> a 1290s ^?! l = foldrOf l const (error "(^?!): empty Fold") s 1291{-# INLINE (^?!) #-} 1292 1293-- | Retrieve the 'First' entry of a 'Fold' or 'Traversal' or retrieve 'Just' the result 1294-- from a 'Getter' or 'Lens'. 1295-- 1296-- The answer is computed in a manner that leaks space less than @'preview'@ or @^?'@ 1297-- and gives you back access to the outermost 'Just' constructor more quickly, but does so 1298-- in a way that builds an intermediate structure, and thus may have worse 1299-- constant factors. This also means that it can not be used in any 'Control.Monad.Reader.MonadReader', 1300-- but must instead have 's' passed as its last argument, unlike 'preview'. 1301-- 1302-- Note: this could been named `headOf`. 1303-- 1304-- >>> firstOf traverse [1..10] 1305-- Just 1 1306-- 1307-- >>> firstOf both (1,2) 1308-- Just 1 1309-- 1310-- >>> firstOf ignored () 1311-- Nothing 1312-- 1313-- @ 1314-- 'firstOf' :: 'Getter' s a -> s -> 'Maybe' a 1315-- 'firstOf' :: 'Fold' s a -> s -> 'Maybe' a 1316-- 'firstOf' :: 'Lens'' s a -> s -> 'Maybe' a 1317-- 'firstOf' :: 'Iso'' s a -> s -> 'Maybe' a 1318-- 'firstOf' :: 'Traversal'' s a -> s -> 'Maybe' a 1319-- @ 1320firstOf :: Getting (Leftmost a) s a -> s -> Maybe a 1321firstOf l = getLeftmost . foldMapOf l LLeaf 1322{-# INLINE firstOf #-} 1323 1324-- | Retrieve the 'Data.Semigroup.First' entry of a 'Fold1' or 'Traversal1' or the result from a 'Getter' or 'Lens'. 1325-- 1326-- >>> first1Of traverse1 (1 :| [2..10]) 1327-- 1 1328-- 1329-- >>> first1Of both1 (1,2) 1330-- 1 1331-- 1332-- /Note:/ this is different from '^.'. 1333-- 1334-- >>> first1Of traverse1 ([1,2] :| [[3,4],[5,6]]) 1335-- [1,2] 1336-- 1337-- >>> ([1,2] :| [[3,4],[5,6]]) ^. traverse1 1338-- [1,2,3,4,5,6] 1339-- 1340-- @ 1341-- 'first1Of' :: 'Getter' s a -> s -> a 1342-- 'first1Of' :: 'Fold1' s a -> s -> a 1343-- 'first1Of' :: 'Lens'' s a -> s -> a 1344-- 'first1Of' :: 'Iso'' s a -> s -> a 1345-- 'first1Of' :: 'Traversal1'' s a -> s -> a 1346-- @ 1347first1Of :: Getting (Semi.First a) s a -> s -> a 1348first1Of l = Semi.getFirst . foldMapOf l Semi.First 1349 1350-- | Retrieve the 'Last' entry of a 'Fold' or 'Traversal' or retrieve 'Just' the result 1351-- from a 'Getter' or 'Lens'. 1352-- 1353-- The answer is computed in a manner that leaks space less than @'ala' 'Last' '.' 'foldMapOf'@ 1354-- and gives you back access to the outermost 'Just' constructor more quickly, but may have worse 1355-- constant factors. 1356-- 1357-- >>> lastOf traverse [1..10] 1358-- Just 10 1359-- 1360-- >>> lastOf both (1,2) 1361-- Just 2 1362-- 1363-- >>> lastOf ignored () 1364-- Nothing 1365-- 1366-- @ 1367-- 'lastOf' :: 'Getter' s a -> s -> 'Maybe' a 1368-- 'lastOf' :: 'Fold' s a -> s -> 'Maybe' a 1369-- 'lastOf' :: 'Lens'' s a -> s -> 'Maybe' a 1370-- 'lastOf' :: 'Iso'' s a -> s -> 'Maybe' a 1371-- 'lastOf' :: 'Traversal'' s a -> s -> 'Maybe' a 1372-- @ 1373lastOf :: Getting (Rightmost a) s a -> s -> Maybe a 1374lastOf l = getRightmost . foldMapOf l RLeaf 1375{-# INLINE lastOf #-} 1376 1377-- | Retrieve the 'Data.Semigroup.Last' entry of a 'Fold1' or 'Traversal1' or retrieve the result 1378-- from a 'Getter' or 'Lens'.o 1379-- 1380-- >>> last1Of traverse1 (1 :| [2..10]) 1381-- 10 1382-- 1383-- >>> last1Of both1 (1,2) 1384-- 2 1385-- 1386-- @ 1387-- 'last1Of' :: 'Getter' s a -> s -> 'Maybe' a 1388-- 'last1Of' :: 'Fold1' s a -> s -> 'Maybe' a 1389-- 'last1Of' :: 'Lens'' s a -> s -> 'Maybe' a 1390-- 'last1Of' :: 'Iso'' s a -> s -> 'Maybe' a 1391-- 'last1Of' :: 'Traversal1'' s a -> s -> 'Maybe' a 1392-- @ 1393last1Of :: Getting (Semi.Last a) s a -> s -> a 1394last1Of l = Semi.getLast . foldMapOf l Semi.Last 1395 1396-- | Returns 'True' if this 'Fold' or 'Traversal' has no targets in the given container. 1397-- 1398-- Note: 'nullOf' on a valid 'Iso', 'Lens' or 'Getter' should always return 'False'. 1399-- 1400-- @ 1401-- 'null' ≡ 'nullOf' 'folded' 1402-- @ 1403-- 1404-- This may be rather inefficient compared to the 'null' check of many containers. 1405-- 1406-- >>> nullOf _1 (1,2) 1407-- False 1408-- 1409-- >>> nullOf ignored () 1410-- True 1411-- 1412-- >>> nullOf traverse [] 1413-- True 1414-- 1415-- >>> nullOf (element 20) [1..10] 1416-- True 1417-- 1418-- @ 1419-- 'nullOf' ('folded' '.' '_1' '.' 'folded') :: ('Foldable' f, 'Foldable' g) => f (g a, b) -> 'Bool' 1420-- @ 1421-- 1422-- @ 1423-- 'nullOf' :: 'Getter' s a -> s -> 'Bool' 1424-- 'nullOf' :: 'Fold' s a -> s -> 'Bool' 1425-- 'nullOf' :: 'Iso'' s a -> s -> 'Bool' 1426-- 'nullOf' :: 'Lens'' s a -> s -> 'Bool' 1427-- 'nullOf' :: 'Traversal'' s a -> s -> 'Bool' 1428-- @ 1429nullOf :: Getting All s a -> s -> Bool 1430nullOf = hasn't 1431{-# INLINE nullOf #-} 1432 1433-- | Returns 'True' if this 'Fold' or 'Traversal' has any targets in the given container. 1434-- 1435-- A more \"conversational\" alias for this combinator is 'has'. 1436-- 1437-- Note: 'notNullOf' on a valid 'Iso', 'Lens' or 'Getter' should always return 'True'. 1438-- 1439-- @ 1440-- 'not' '.' 'null' ≡ 'notNullOf' 'folded' 1441-- @ 1442-- 1443-- This may be rather inefficient compared to the @'not' '.' 'null'@ check of many containers. 1444-- 1445-- >>> notNullOf _1 (1,2) 1446-- True 1447-- 1448-- >>> notNullOf traverse [1..10] 1449-- True 1450-- 1451-- >>> notNullOf folded [] 1452-- False 1453-- 1454-- >>> notNullOf (element 20) [1..10] 1455-- False 1456-- 1457-- @ 1458-- 'notNullOf' ('folded' '.' '_1' '.' 'folded') :: ('Foldable' f, 'Foldable' g) => f (g a, b) -> 'Bool' 1459-- @ 1460-- 1461-- @ 1462-- 'notNullOf' :: 'Getter' s a -> s -> 'Bool' 1463-- 'notNullOf' :: 'Fold' s a -> s -> 'Bool' 1464-- 'notNullOf' :: 'Iso'' s a -> s -> 'Bool' 1465-- 'notNullOf' :: 'Lens'' s a -> s -> 'Bool' 1466-- 'notNullOf' :: 'Traversal'' s a -> s -> 'Bool' 1467-- @ 1468notNullOf :: Getting Any s a -> s -> Bool 1469notNullOf = has 1470{-# INLINE notNullOf #-} 1471 1472-- | Obtain the maximum element (if any) targeted by a 'Fold' or 'Traversal' safely. 1473-- 1474-- Note: 'maximumOf' on a valid 'Iso', 'Lens' or 'Getter' will always return 'Just' a value. 1475-- 1476-- >>> maximumOf traverse [1..10] 1477-- Just 10 1478-- 1479-- >>> maximumOf traverse [] 1480-- Nothing 1481-- 1482-- >>> maximumOf (folded.filtered even) [1,4,3,6,7,9,2] 1483-- Just 6 1484-- 1485-- @ 1486-- 'maximum' ≡ 'fromMaybe' ('error' \"empty\") '.' 'maximumOf' 'folded' 1487-- @ 1488-- 1489-- In the interest of efficiency, This operation has semantics more strict than strictly necessary. 1490-- @'rmap' 'getMax' ('foldMapOf' l 'Max')@ has lazier semantics but could leak memory. 1491-- 1492-- @ 1493-- 'maximumOf' :: 'Ord' a => 'Getter' s a -> s -> 'Maybe' a 1494-- 'maximumOf' :: 'Ord' a => 'Fold' s a -> s -> 'Maybe' a 1495-- 'maximumOf' :: 'Ord' a => 'Iso'' s a -> s -> 'Maybe' a 1496-- 'maximumOf' :: 'Ord' a => 'Lens'' s a -> s -> 'Maybe' a 1497-- 'maximumOf' :: 'Ord' a => 'Traversal'' s a -> s -> 'Maybe' a 1498-- @ 1499maximumOf :: Ord a => Getting (Endo (Endo (Maybe a))) s a -> s -> Maybe a 1500maximumOf l = foldlOf' l mf Nothing where 1501 mf Nothing y = Just $! y 1502 mf (Just x) y = Just $! max x y 1503{-# INLINE maximumOf #-} 1504 1505-- | Obtain the maximum element targeted by a 'Fold1' or 'Traversal1'. 1506-- 1507-- >>> maximum1Of traverse1 (1 :| [2..10]) 1508-- 10 1509-- 1510-- @ 1511-- 'maximum1Of' :: 'Ord' a => 'Getter' s a -> s -> a 1512-- 'maximum1Of' :: 'Ord' a => 'Fold1' s a -> s -> a 1513-- 'maximum1Of' :: 'Ord' a => 'Iso'' s a -> s -> a 1514-- 'maximum1Of' :: 'Ord' a => 'Lens'' s a -> s -> a 1515-- 'maximum1Of' :: 'Ord' a => 'Traversal1'' s a -> s -> a 1516-- @ 1517maximum1Of :: Ord a => Getting (Semi.Max a) s a -> s -> a 1518maximum1Of l = Semi.getMax . foldMapOf l Semi.Max 1519{-# INLINE maximum1Of #-} 1520 1521-- | Obtain the minimum element (if any) targeted by a 'Fold' or 'Traversal' safely. 1522-- 1523-- Note: 'minimumOf' on a valid 'Iso', 'Lens' or 'Getter' will always return 'Just' a value. 1524-- 1525-- >>> minimumOf traverse [1..10] 1526-- Just 1 1527-- 1528-- >>> minimumOf traverse [] 1529-- Nothing 1530-- 1531-- >>> minimumOf (folded.filtered even) [1,4,3,6,7,9,2] 1532-- Just 2 1533-- 1534-- @ 1535-- 'minimum' ≡ 'Data.Maybe.fromMaybe' ('error' \"empty\") '.' 'minimumOf' 'folded' 1536-- @ 1537-- 1538-- In the interest of efficiency, This operation has semantics more strict than strictly necessary. 1539-- @'rmap' 'getMin' ('foldMapOf' l 'Min')@ has lazier semantics but could leak memory. 1540-- 1541-- 1542-- @ 1543-- 'minimumOf' :: 'Ord' a => 'Getter' s a -> s -> 'Maybe' a 1544-- 'minimumOf' :: 'Ord' a => 'Fold' s a -> s -> 'Maybe' a 1545-- 'minimumOf' :: 'Ord' a => 'Iso'' s a -> s -> 'Maybe' a 1546-- 'minimumOf' :: 'Ord' a => 'Lens'' s a -> s -> 'Maybe' a 1547-- 'minimumOf' :: 'Ord' a => 'Traversal'' s a -> s -> 'Maybe' a 1548-- @ 1549minimumOf :: Ord a => Getting (Endo (Endo (Maybe a))) s a -> s -> Maybe a 1550minimumOf l = foldlOf' l mf Nothing where 1551 mf Nothing y = Just $! y 1552 mf (Just x) y = Just $! min x y 1553{-# INLINE minimumOf #-} 1554 1555-- | Obtain the minimum element targeted by a 'Fold1' or 'Traversal1'. 1556-- 1557-- >>> minimum1Of traverse1 (1 :| [2..10]) 1558-- 1 1559-- 1560-- @ 1561-- 'minimum1Of' :: 'Ord' a => 'Getter' s a -> s -> a 1562-- 'minimum1Of' :: 'Ord' a => 'Fold1' s a -> s -> a 1563-- 'minimum1Of' :: 'Ord' a => 'Iso'' s a -> s -> a 1564-- 'minimum1Of' :: 'Ord' a => 'Lens'' s a -> s -> a 1565-- 'minimum1Of' :: 'Ord' a => 'Traversal1'' s a -> s -> a 1566-- @ 1567minimum1Of :: Ord a => Getting (Semi.Min a) s a -> s -> a 1568minimum1Of l = Semi.getMin . foldMapOf l Semi.Min 1569{-# INLINE minimum1Of #-} 1570 1571-- | Obtain the maximum element (if any) targeted by a 'Fold', 'Traversal', 'Lens', 'Iso', 1572-- or 'Getter' according to a user supplied 'Ordering'. 1573-- 1574-- >>> maximumByOf traverse (compare `on` length) ["mustard","relish","ham"] 1575-- Just "mustard" 1576-- 1577-- In the interest of efficiency, This operation has semantics more strict than strictly necessary. 1578-- 1579-- @ 1580-- 'Data.Foldable.maximumBy' cmp ≡ 'Data.Maybe.fromMaybe' ('error' \"empty\") '.' 'maximumByOf' 'folded' cmp 1581-- @ 1582-- 1583-- @ 1584-- 'maximumByOf' :: 'Getter' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1585-- 'maximumByOf' :: 'Fold' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1586-- 'maximumByOf' :: 'Iso'' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1587-- 'maximumByOf' :: 'Lens'' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1588-- 'maximumByOf' :: 'Traversal'' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1589-- @ 1590maximumByOf :: Getting (Endo (Endo (Maybe a))) s a -> (a -> a -> Ordering) -> s -> Maybe a 1591maximumByOf l cmp = foldlOf' l mf Nothing where 1592 mf Nothing y = Just $! y 1593 mf (Just x) y = Just $! if cmp x y == GT then x else y 1594{-# INLINE maximumByOf #-} 1595 1596-- | Obtain the minimum element (if any) targeted by a 'Fold', 'Traversal', 'Lens', 'Iso' 1597-- or 'Getter' according to a user supplied 'Ordering'. 1598-- 1599-- In the interest of efficiency, This operation has semantics more strict than strictly necessary. 1600-- 1601-- >>> minimumByOf traverse (compare `on` length) ["mustard","relish","ham"] 1602-- Just "ham" 1603-- 1604-- @ 1605-- 'minimumBy' cmp ≡ 'Data.Maybe.fromMaybe' ('error' \"empty\") '.' 'minimumByOf' 'folded' cmp 1606-- @ 1607-- 1608-- @ 1609-- 'minimumByOf' :: 'Getter' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1610-- 'minimumByOf' :: 'Fold' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1611-- 'minimumByOf' :: 'Iso'' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1612-- 'minimumByOf' :: 'Lens'' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1613-- 'minimumByOf' :: 'Traversal'' s a -> (a -> a -> 'Ordering') -> s -> 'Maybe' a 1614-- @ 1615minimumByOf :: Getting (Endo (Endo (Maybe a))) s a -> (a -> a -> Ordering) -> s -> Maybe a 1616minimumByOf l cmp = foldlOf' l mf Nothing where 1617 mf Nothing y = Just $! y 1618 mf (Just x) y = Just $! if cmp x y == GT then y else x 1619{-# INLINE minimumByOf #-} 1620 1621-- | The 'findOf' function takes a 'Lens' (or 'Getter', 'Iso', 'Fold', or 'Traversal'), 1622-- a predicate and a structure and returns the leftmost element of the structure 1623-- matching the predicate, or 'Nothing' if there is no such element. 1624-- 1625-- >>> findOf each even (1,3,4,6) 1626-- Just 4 1627-- 1628-- >>> findOf folded even [1,3,5,7] 1629-- Nothing 1630-- 1631-- @ 1632-- 'findOf' :: 'Getter' s a -> (a -> 'Bool') -> s -> 'Maybe' a 1633-- 'findOf' :: 'Fold' s a -> (a -> 'Bool') -> s -> 'Maybe' a 1634-- 'findOf' :: 'Iso'' s a -> (a -> 'Bool') -> s -> 'Maybe' a 1635-- 'findOf' :: 'Lens'' s a -> (a -> 'Bool') -> s -> 'Maybe' a 1636-- 'findOf' :: 'Traversal'' s a -> (a -> 'Bool') -> s -> 'Maybe' a 1637-- @ 1638-- 1639-- @ 1640-- 'Data.Foldable.find' ≡ 'findOf' 'folded' 1641-- 'ifindOf' l ≡ 'findOf' l '.' 'Indexed' 1642-- @ 1643-- 1644-- A simpler version that didn't permit indexing, would be: 1645-- 1646-- @ 1647-- 'findOf' :: 'Getting' ('Endo' ('Maybe' a)) s a -> (a -> 'Bool') -> s -> 'Maybe' a 1648-- 'findOf' l p = 'foldrOf' l (\a y -> if p a then 'Just' a else y) 'Nothing' 1649-- @ 1650findOf :: Getting (Endo (Maybe a)) s a -> (a -> Bool) -> s -> Maybe a 1651findOf l f = foldrOf l (\a y -> if f a then Just a else y) Nothing 1652{-# INLINE findOf #-} 1653 1654-- | The 'findMOf' function takes a 'Lens' (or 'Getter', 'Iso', 'Fold', or 'Traversal'), 1655-- a monadic predicate and a structure and returns in the monad the leftmost element of the structure 1656-- matching the predicate, or 'Nothing' if there is no such element. 1657-- 1658-- >>> findMOf each ( \x -> print ("Checking " ++ show x) >> return (even x)) (1,3,4,6) 1659-- "Checking 1" 1660-- "Checking 3" 1661-- "Checking 4" 1662-- Just 4 1663-- 1664-- >>> findMOf each ( \x -> print ("Checking " ++ show x) >> return (even x)) (1,3,5,7) 1665-- "Checking 1" 1666-- "Checking 3" 1667-- "Checking 5" 1668-- "Checking 7" 1669-- Nothing 1670-- 1671-- @ 1672-- 'findMOf' :: ('Monad' m, 'Getter' s a) -> (a -> m 'Bool') -> s -> m ('Maybe' a) 1673-- 'findMOf' :: ('Monad' m, 'Fold' s a) -> (a -> m 'Bool') -> s -> m ('Maybe' a) 1674-- 'findMOf' :: ('Monad' m, 'Iso'' s a) -> (a -> m 'Bool') -> s -> m ('Maybe' a) 1675-- 'findMOf' :: ('Monad' m, 'Lens'' s a) -> (a -> m 'Bool') -> s -> m ('Maybe' a) 1676-- 'findMOf' :: ('Monad' m, 'Traversal'' s a) -> (a -> m 'Bool') -> s -> m ('Maybe' a) 1677-- @ 1678-- 1679-- @ 1680-- 'findMOf' 'folded' :: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m (Maybe a) 1681-- 'ifindMOf' l ≡ 'findMOf' l '.' 'Indexed' 1682-- @ 1683-- 1684-- A simpler version that didn't permit indexing, would be: 1685-- 1686-- @ 1687-- 'findMOf' :: Monad m => 'Getting' ('Endo' (m ('Maybe' a))) s a -> (a -> m 'Bool') -> s -> m ('Maybe' a) 1688-- 'findMOf' l p = 'foldrOf' l (\a y -> p a >>= \x -> if x then return ('Just' a) else y) $ return 'Nothing' 1689-- @ 1690findMOf :: Monad m => Getting (Endo (m (Maybe a))) s a -> (a -> m Bool) -> s -> m (Maybe a) 1691findMOf l f = foldrOf l (\a y -> f a >>= \r -> if r then return (Just a) else y) $ return Nothing 1692{-# INLINE findMOf #-} 1693 1694-- | The 'lookupOf' function takes a 'Fold' (or 'Getter', 'Traversal', 1695-- 'Lens', 'Iso', etc.), a key, and a structure containing key/value pairs. 1696-- It returns the first value corresponding to the given key. This function 1697-- generalizes 'lookup' to work on an arbitrary 'Fold' instead of lists. 1698-- 1699-- >>> lookupOf folded 4 [(2, 'a'), (4, 'b'), (4, 'c')] 1700-- Just 'b' 1701-- 1702-- >>> lookupOf each 2 [(2, 'a'), (4, 'b'), (4, 'c')] 1703-- Just 'a' 1704-- 1705-- @ 1706-- 'lookupOf' :: 'Eq' k => 'Fold' s (k,v) -> k -> s -> 'Maybe' v 1707-- @ 1708lookupOf :: Eq k => Getting (Endo (Maybe v)) s (k,v) -> k -> s -> Maybe v 1709lookupOf l k = foldrOf l (\(k',v) next -> if k == k' then Just v else next) Nothing 1710{-# INLINE lookupOf #-} 1711 1712-- | A variant of 'foldrOf' that has no base case and thus may only be applied 1713-- to lenses and structures such that the 'Lens' views at least one element of 1714-- the structure. 1715-- 1716-- >>> foldr1Of each (+) (1,2,3,4) 1717-- 10 1718-- 1719-- @ 1720-- 'foldr1Of' l f ≡ 'Prelude.foldr1' f '.' 'toListOf' l 1721-- 'Data.Foldable.foldr1' ≡ 'foldr1Of' 'folded' 1722-- @ 1723-- 1724-- @ 1725-- 'foldr1Of' :: 'Getter' s a -> (a -> a -> a) -> s -> a 1726-- 'foldr1Of' :: 'Fold' s a -> (a -> a -> a) -> s -> a 1727-- 'foldr1Of' :: 'Iso'' s a -> (a -> a -> a) -> s -> a 1728-- 'foldr1Of' :: 'Lens'' s a -> (a -> a -> a) -> s -> a 1729-- 'foldr1Of' :: 'Traversal'' s a -> (a -> a -> a) -> s -> a 1730-- @ 1731foldr1Of :: HasCallStack => Getting (Endo (Maybe a)) s a -> (a -> a -> a) -> s -> a 1732foldr1Of l f xs = fromMaybe (error "foldr1Of: empty structure") 1733 (foldrOf l mf Nothing xs) where 1734 mf x my = Just $ case my of 1735 Nothing -> x 1736 Just y -> f x y 1737{-# INLINE foldr1Of #-} 1738 1739-- | A variant of 'foldlOf' that has no base case and thus may only be applied to lenses and structures such 1740-- that the 'Lens' views at least one element of the structure. 1741-- 1742-- >>> foldl1Of each (+) (1,2,3,4) 1743-- 10 1744-- 1745-- @ 1746-- 'foldl1Of' l f ≡ 'Prelude.foldl1' f '.' 'toListOf' l 1747-- 'Data.Foldable.foldl1' ≡ 'foldl1Of' 'folded' 1748-- @ 1749-- 1750-- @ 1751-- 'foldl1Of' :: 'Getter' s a -> (a -> a -> a) -> s -> a 1752-- 'foldl1Of' :: 'Fold' s a -> (a -> a -> a) -> s -> a 1753-- 'foldl1Of' :: 'Iso'' s a -> (a -> a -> a) -> s -> a 1754-- 'foldl1Of' :: 'Lens'' s a -> (a -> a -> a) -> s -> a 1755-- 'foldl1Of' :: 'Traversal'' s a -> (a -> a -> a) -> s -> a 1756-- @ 1757foldl1Of :: HasCallStack => Getting (Dual (Endo (Maybe a))) s a -> (a -> a -> a) -> s -> a 1758foldl1Of l f xs = fromMaybe (error "foldl1Of: empty structure") (foldlOf l mf Nothing xs) where 1759 mf mx y = Just $ case mx of 1760 Nothing -> y 1761 Just x -> f x y 1762{-# INLINE foldl1Of #-} 1763 1764-- | Strictly fold right over the elements of a structure. 1765-- 1766-- @ 1767-- 'Data.Foldable.foldr'' ≡ 'foldrOf'' 'folded' 1768-- @ 1769-- 1770-- @ 1771-- 'foldrOf'' :: 'Getter' s a -> (a -> r -> r) -> r -> s -> r 1772-- 'foldrOf'' :: 'Fold' s a -> (a -> r -> r) -> r -> s -> r 1773-- 'foldrOf'' :: 'Iso'' s a -> (a -> r -> r) -> r -> s -> r 1774-- 'foldrOf'' :: 'Lens'' s a -> (a -> r -> r) -> r -> s -> r 1775-- 'foldrOf'' :: 'Traversal'' s a -> (a -> r -> r) -> r -> s -> r 1776-- @ 1777foldrOf' :: Getting (Dual (Endo (Endo r))) s a -> (a -> r -> r) -> r -> s -> r 1778foldrOf' l f z0 xs = foldlOf l f' (Endo id) xs `appEndo` z0 1779 where f' (Endo k) x = Endo $ \ z -> k $! f x z 1780{-# INLINE foldrOf' #-} 1781 1782-- | Fold over the elements of a structure, associating to the left, but strictly. 1783-- 1784-- @ 1785-- 'Data.Foldable.foldl'' ≡ 'foldlOf'' 'folded' 1786-- @ 1787-- 1788-- @ 1789-- 'foldlOf'' :: 'Getter' s a -> (r -> a -> r) -> r -> s -> r 1790-- 'foldlOf'' :: 'Fold' s a -> (r -> a -> r) -> r -> s -> r 1791-- 'foldlOf'' :: 'Iso'' s a -> (r -> a -> r) -> r -> s -> r 1792-- 'foldlOf'' :: 'Lens'' s a -> (r -> a -> r) -> r -> s -> r 1793-- 'foldlOf'' :: 'Traversal'' s a -> (r -> a -> r) -> r -> s -> r 1794-- @ 1795foldlOf' :: Getting (Endo (Endo r)) s a -> (r -> a -> r) -> r -> s -> r 1796foldlOf' l f z0 xs = foldrOf l f' (Endo id) xs `appEndo` z0 1797 where f' x (Endo k) = Endo $ \z -> k $! f z x 1798{-# INLINE foldlOf' #-} 1799 1800-- | A variant of 'foldrOf'' that has no base case and thus may only be applied 1801-- to folds and structures such that the fold views at least one element of the 1802-- structure. 1803-- 1804-- @ 1805-- 'foldr1Of' l f ≡ 'Prelude.foldr1' f '.' 'toListOf' l 1806-- @ 1807-- 1808-- @ 1809-- 'foldr1Of'' :: 'Getter' s a -> (a -> a -> a) -> s -> a 1810-- 'foldr1Of'' :: 'Fold' s a -> (a -> a -> a) -> s -> a 1811-- 'foldr1Of'' :: 'Iso'' s a -> (a -> a -> a) -> s -> a 1812-- 'foldr1Of'' :: 'Lens'' s a -> (a -> a -> a) -> s -> a 1813-- 'foldr1Of'' :: 'Traversal'' s a -> (a -> a -> a) -> s -> a 1814-- @ 1815foldr1Of' :: HasCallStack => Getting (Dual (Endo (Endo (Maybe a)))) s a -> (a -> a -> a) -> s -> a 1816foldr1Of' l f xs = fromMaybe (error "foldr1Of': empty structure") (foldrOf' l mf Nothing xs) where 1817 mf x Nothing = Just $! x 1818 mf x (Just y) = Just $! f x y 1819{-# INLINE foldr1Of' #-} 1820 1821-- | A variant of 'foldlOf'' that has no base case and thus may only be applied 1822-- to folds and structures such that the fold views at least one element of 1823-- the structure. 1824-- 1825-- @ 1826-- 'foldl1Of'' l f ≡ 'Data.List.foldl1'' f '.' 'toListOf' l 1827-- @ 1828-- 1829-- @ 1830-- 'foldl1Of'' :: 'Getter' s a -> (a -> a -> a) -> s -> a 1831-- 'foldl1Of'' :: 'Fold' s a -> (a -> a -> a) -> s -> a 1832-- 'foldl1Of'' :: 'Iso'' s a -> (a -> a -> a) -> s -> a 1833-- 'foldl1Of'' :: 'Lens'' s a -> (a -> a -> a) -> s -> a 1834-- 'foldl1Of'' :: 'Traversal'' s a -> (a -> a -> a) -> s -> a 1835-- @ 1836foldl1Of' :: HasCallStack => Getting (Endo (Endo (Maybe a))) s a -> (a -> a -> a) -> s -> a 1837foldl1Of' l f xs = fromMaybe (error "foldl1Of': empty structure") (foldlOf' l mf Nothing xs) where 1838 mf Nothing y = Just $! y 1839 mf (Just x) y = Just $! f x y 1840{-# INLINE foldl1Of' #-} 1841 1842-- | Monadic fold over the elements of a structure, associating to the right, 1843-- i.e. from right to left. 1844-- 1845-- @ 1846-- 'Data.Foldable.foldrM' ≡ 'foldrMOf' 'folded' 1847-- @ 1848-- 1849-- @ 1850-- 'foldrMOf' :: 'Monad' m => 'Getter' s a -> (a -> r -> m r) -> r -> s -> m r 1851-- 'foldrMOf' :: 'Monad' m => 'Fold' s a -> (a -> r -> m r) -> r -> s -> m r 1852-- 'foldrMOf' :: 'Monad' m => 'Iso'' s a -> (a -> r -> m r) -> r -> s -> m r 1853-- 'foldrMOf' :: 'Monad' m => 'Lens'' s a -> (a -> r -> m r) -> r -> s -> m r 1854-- 'foldrMOf' :: 'Monad' m => 'Traversal'' s a -> (a -> r -> m r) -> r -> s -> m r 1855-- @ 1856foldrMOf :: Monad m 1857 => Getting (Dual (Endo (r -> m r))) s a 1858 -> (a -> r -> m r) -> r -> s -> m r 1859foldrMOf l f z0 xs = foldlOf l f' return xs z0 1860 where f' k x z = f x z >>= k 1861{-# INLINE foldrMOf #-} 1862 1863-- | Monadic fold over the elements of a structure, associating to the left, 1864-- i.e. from left to right. 1865-- 1866-- @ 1867-- 'Data.Foldable.foldlM' ≡ 'foldlMOf' 'folded' 1868-- @ 1869-- 1870-- @ 1871-- 'foldlMOf' :: 'Monad' m => 'Getter' s a -> (r -> a -> m r) -> r -> s -> m r 1872-- 'foldlMOf' :: 'Monad' m => 'Fold' s a -> (r -> a -> m r) -> r -> s -> m r 1873-- 'foldlMOf' :: 'Monad' m => 'Iso'' s a -> (r -> a -> m r) -> r -> s -> m r 1874-- 'foldlMOf' :: 'Monad' m => 'Lens'' s a -> (r -> a -> m r) -> r -> s -> m r 1875-- 'foldlMOf' :: 'Monad' m => 'Traversal'' s a -> (r -> a -> m r) -> r -> s -> m r 1876-- @ 1877foldlMOf :: Monad m 1878 => Getting (Endo (r -> m r)) s a 1879 -> (r -> a -> m r) -> r -> s -> m r 1880foldlMOf l f z0 xs = foldrOf l f' return xs z0 1881 where f' x k z = f z x >>= k 1882{-# INLINE foldlMOf #-} 1883 1884-- | Check to see if this 'Fold' or 'Traversal' matches 1 or more entries. 1885-- 1886-- >>> has (element 0) [] 1887-- False 1888-- 1889-- >>> has _Left (Left 12) 1890-- True 1891-- 1892-- >>> has _Right (Left 12) 1893-- False 1894-- 1895-- This will always return 'True' for a 'Lens' or 'Getter'. 1896-- 1897-- >>> has _1 ("hello","world") 1898-- True 1899-- 1900-- @ 1901-- 'has' :: 'Getter' s a -> s -> 'Bool' 1902-- 'has' :: 'Fold' s a -> s -> 'Bool' 1903-- 'has' :: 'Iso'' s a -> s -> 'Bool' 1904-- 'has' :: 'Lens'' s a -> s -> 'Bool' 1905-- 'has' :: 'Traversal'' s a -> s -> 'Bool' 1906-- @ 1907has :: Getting Any s a -> s -> Bool 1908has l = getAny #. foldMapOf l (\_ -> Any True) 1909{-# INLINE has #-} 1910 1911 1912 1913-- | Check to see if this 'Fold' or 'Traversal' has no matches. 1914-- 1915-- >>> hasn't _Left (Right 12) 1916-- True 1917-- 1918-- >>> hasn't _Left (Left 12) 1919-- False 1920hasn't :: Getting All s a -> s -> Bool 1921hasn't l = getAll #. foldMapOf l (\_ -> All False) 1922{-# INLINE hasn't #-} 1923 1924------------------------------------------------------------------------------ 1925-- Pre 1926------------------------------------------------------------------------------ 1927 1928-- | This converts a 'Fold' to a 'IndexPreservingGetter' that returns the first element, if it 1929-- exists, as a 'Maybe'. 1930-- 1931-- @ 1932-- 'pre' :: 'Getter' s a -> 'IndexPreservingGetter' s ('Maybe' a) 1933-- 'pre' :: 'Fold' s a -> 'IndexPreservingGetter' s ('Maybe' a) 1934-- 'pre' :: 'Traversal'' s a -> 'IndexPreservingGetter' s ('Maybe' a) 1935-- 'pre' :: 'Lens'' s a -> 'IndexPreservingGetter' s ('Maybe' a) 1936-- 'pre' :: 'Iso'' s a -> 'IndexPreservingGetter' s ('Maybe' a) 1937-- 'pre' :: 'Prism'' s a -> 'IndexPreservingGetter' s ('Maybe' a) 1938-- @ 1939pre :: Getting (First a) s a -> IndexPreservingGetter s (Maybe a) 1940pre l = dimap (getFirst . getConst #. l (Const #. First #. Just)) phantom 1941{-# INLINE pre #-} 1942 1943-- | This converts an 'IndexedFold' to an 'IndexPreservingGetter' that returns the first index 1944-- and element, if they exist, as a 'Maybe'. 1945-- 1946-- @ 1947-- 'ipre' :: 'IndexedGetter' i s a -> 'IndexPreservingGetter' s ('Maybe' (i, a)) 1948-- 'ipre' :: 'IndexedFold' i s a -> 'IndexPreservingGetter' s ('Maybe' (i, a)) 1949-- 'ipre' :: 'IndexedTraversal'' i s a -> 'IndexPreservingGetter' s ('Maybe' (i, a)) 1950-- 'ipre' :: 'IndexedLens'' i s a -> 'IndexPreservingGetter' s ('Maybe' (i, a)) 1951-- @ 1952ipre :: IndexedGetting i (First (i, a)) s a -> IndexPreservingGetter s (Maybe (i, a)) 1953ipre l = dimap (getFirst . getConst #. l (Indexed $ \i a -> Const (First (Just (i, a))))) phantom 1954{-# INLINE ipre #-} 1955 1956------------------------------------------------------------------------------ 1957-- Preview 1958------------------------------------------------------------------------------ 1959 1960-- | Retrieve the first value targeted by a 'Fold' or 'Traversal' (or 'Just' the result 1961-- from a 'Getter' or 'Lens'). See also 'firstOf' and '^?', which are similar with 1962-- some subtle differences (explained below). 1963-- 1964-- @ 1965-- 'Data.Maybe.listToMaybe' '.' 'toList' ≡ 'preview' 'folded' 1966-- @ 1967-- 1968-- @ 1969-- 'preview' = 'view' '.' 'pre' 1970-- @ 1971-- 1972-- 1973-- Unlike '^?', this function uses a 1974-- 'Control.Monad.Reader.MonadReader' to read the value to be focused in on. 1975-- This allows one to pass the value as the last argument by using the 1976-- 'Control.Monad.Reader.MonadReader' instance for @(->) s@ 1977-- However, it may also be used as part of some deeply nested transformer stack. 1978-- 1979-- 'preview' uses a monoidal value to obtain the result. 1980-- This means that it generally has good performance, but can occasionally cause space leaks 1981-- or even stack overflows on some data types. 1982-- There is another function, 'firstOf', which avoids these issues at the cost of 1983-- a slight constant performance cost and a little less flexibility. 1984-- 1985-- It may be helpful to think of 'preview' as having one of the following 1986-- more specialized types: 1987-- 1988-- @ 1989-- 'preview' :: 'Getter' s a -> s -> 'Maybe' a 1990-- 'preview' :: 'Fold' s a -> s -> 'Maybe' a 1991-- 'preview' :: 'Lens'' s a -> s -> 'Maybe' a 1992-- 'preview' :: 'Iso'' s a -> s -> 'Maybe' a 1993-- 'preview' :: 'Traversal'' s a -> s -> 'Maybe' a 1994-- @ 1995-- 1996-- 1997-- @ 1998-- 'preview' :: 'MonadReader' s m => 'Getter' s a -> m ('Maybe' a) 1999-- 'preview' :: 'MonadReader' s m => 'Fold' s a -> m ('Maybe' a) 2000-- 'preview' :: 'MonadReader' s m => 'Lens'' s a -> m ('Maybe' a) 2001-- 'preview' :: 'MonadReader' s m => 'Iso'' s a -> m ('Maybe' a) 2002-- 'preview' :: 'MonadReader' s m => 'Traversal'' s a -> m ('Maybe' a) 2003-- 2004-- @ 2005preview :: MonadReader s m => Getting (First a) s a -> m (Maybe a) 2006preview l = asks (getFirst #. foldMapOf l (First #. Just)) 2007{-# INLINE preview #-} 2008 2009-- | Retrieve the first index and value targeted by a 'Fold' or 'Traversal' (or 'Just' the result 2010-- from a 'Getter' or 'Lens'). See also ('^@?'). 2011-- 2012-- @ 2013-- 'ipreview' = 'view' '.' 'ipre' 2014-- @ 2015-- 2016-- This is usually applied in the 'Control.Monad.Reader.Reader' 2017-- 'Control.Monad.Monad' @(->) s@. 2018-- 2019-- @ 2020-- 'ipreview' :: 'IndexedGetter' i s a -> s -> 'Maybe' (i, a) 2021-- 'ipreview' :: 'IndexedFold' i s a -> s -> 'Maybe' (i, a) 2022-- 'ipreview' :: 'IndexedLens'' i s a -> s -> 'Maybe' (i, a) 2023-- 'ipreview' :: 'IndexedTraversal'' i s a -> s -> 'Maybe' (i, a) 2024-- @ 2025-- 2026-- However, it may be useful to think of its full generality when working with 2027-- a 'Control.Monad.Monad' transformer stack: 2028-- 2029-- @ 2030-- 'ipreview' :: 'MonadReader' s m => 'IndexedGetter' s a -> m ('Maybe' (i, a)) 2031-- 'ipreview' :: 'MonadReader' s m => 'IndexedFold' s a -> m ('Maybe' (i, a)) 2032-- 'ipreview' :: 'MonadReader' s m => 'IndexedLens'' s a -> m ('Maybe' (i, a)) 2033-- 'ipreview' :: 'MonadReader' s m => 'IndexedTraversal'' s a -> m ('Maybe' (i, a)) 2034-- @ 2035ipreview :: MonadReader s m => IndexedGetting i (First (i, a)) s a -> m (Maybe (i, a)) 2036ipreview l = asks (getFirst #. ifoldMapOf l (\i a -> First (Just (i, a)))) 2037{-# INLINE ipreview #-} 2038 2039-- | Retrieve a function of the first value targeted by a 'Fold' or 2040-- 'Traversal' (or 'Just' the result from a 'Getter' or 'Lens'). 2041-- 2042-- This is usually applied in the 'Control.Monad.Reader.Reader' 2043-- 'Control.Monad.Monad' @(->) s@. 2044 2045-- @ 2046-- 'previews' = 'views' '.' 'pre' 2047-- @ 2048-- 2049-- @ 2050-- 'previews' :: 'Getter' s a -> (a -> r) -> s -> 'Maybe' r 2051-- 'previews' :: 'Fold' s a -> (a -> r) -> s -> 'Maybe' r 2052-- 'previews' :: 'Lens'' s a -> (a -> r) -> s -> 'Maybe' r 2053-- 'previews' :: 'Iso'' s a -> (a -> r) -> s -> 'Maybe' r 2054-- 'previews' :: 'Traversal'' s a -> (a -> r) -> s -> 'Maybe' r 2055-- @ 2056-- 2057-- However, it may be useful to think of its full generality when working with 2058-- a 'Monad' transformer stack: 2059-- 2060-- @ 2061-- 'previews' :: 'MonadReader' s m => 'Getter' s a -> (a -> r) -> m ('Maybe' r) 2062-- 'previews' :: 'MonadReader' s m => 'Fold' s a -> (a -> r) -> m ('Maybe' r) 2063-- 'previews' :: 'MonadReader' s m => 'Lens'' s a -> (a -> r) -> m ('Maybe' r) 2064-- 'previews' :: 'MonadReader' s m => 'Iso'' s a -> (a -> r) -> m ('Maybe' r) 2065-- 'previews' :: 'MonadReader' s m => 'Traversal'' s a -> (a -> r) -> m ('Maybe' r) 2066-- @ 2067previews :: MonadReader s m => Getting (First r) s a -> (a -> r) -> m (Maybe r) 2068previews l f = asks (getFirst . foldMapOf l (First #. Just . f)) 2069{-# INLINE previews #-} 2070 2071-- | Retrieve a function of the first index and value targeted by an 'IndexedFold' or 2072-- 'IndexedTraversal' (or 'Just' the result from an 'IndexedGetter' or 'IndexedLens'). 2073-- See also ('^@?'). 2074-- 2075-- @ 2076-- 'ipreviews' = 'views' '.' 'ipre' 2077-- @ 2078-- 2079-- This is usually applied in the 'Control.Monad.Reader.Reader' 2080-- 'Control.Monad.Monad' @(->) s@. 2081-- 2082-- @ 2083-- 'ipreviews' :: 'IndexedGetter' i s a -> (i -> a -> r) -> s -> 'Maybe' r 2084-- 'ipreviews' :: 'IndexedFold' i s a -> (i -> a -> r) -> s -> 'Maybe' r 2085-- 'ipreviews' :: 'IndexedLens'' i s a -> (i -> a -> r) -> s -> 'Maybe' r 2086-- 'ipreviews' :: 'IndexedTraversal'' i s a -> (i -> a -> r) -> s -> 'Maybe' r 2087-- @ 2088-- 2089-- However, it may be useful to think of its full generality when working with 2090-- a 'Control.Monad.Monad' transformer stack: 2091-- 2092-- @ 2093-- 'ipreviews' :: 'MonadReader' s m => 'IndexedGetter' i s a -> (i -> a -> r) -> m ('Maybe' r) 2094-- 'ipreviews' :: 'MonadReader' s m => 'IndexedFold' i s a -> (i -> a -> r) -> m ('Maybe' r) 2095-- 'ipreviews' :: 'MonadReader' s m => 'IndexedLens'' i s a -> (i -> a -> r) -> m ('Maybe' r) 2096-- 'ipreviews' :: 'MonadReader' s m => 'IndexedTraversal'' i s a -> (i -> a -> r) -> m ('Maybe' r) 2097-- @ 2098ipreviews :: MonadReader s m => IndexedGetting i (First r) s a -> (i -> a -> r) -> m (Maybe r) 2099ipreviews l f = asks (getFirst . ifoldMapOf l (\i -> First #. Just . f i)) 2100{-# INLINE ipreviews #-} 2101 2102------------------------------------------------------------------------------ 2103-- Preuse 2104------------------------------------------------------------------------------ 2105 2106-- | Retrieve the first value targeted by a 'Fold' or 'Traversal' (or 'Just' the result 2107-- from a 'Getter' or 'Lens') into the current state. 2108-- 2109-- @ 2110-- 'preuse' = 'use' '.' 'pre' 2111-- @ 2112-- 2113-- @ 2114-- 'preuse' :: 'MonadState' s m => 'Getter' s a -> m ('Maybe' a) 2115-- 'preuse' :: 'MonadState' s m => 'Fold' s a -> m ('Maybe' a) 2116-- 'preuse' :: 'MonadState' s m => 'Lens'' s a -> m ('Maybe' a) 2117-- 'preuse' :: 'MonadState' s m => 'Iso'' s a -> m ('Maybe' a) 2118-- 'preuse' :: 'MonadState' s m => 'Traversal'' s a -> m ('Maybe' a) 2119-- @ 2120preuse :: MonadState s m => Getting (First a) s a -> m (Maybe a) 2121preuse l = gets (preview l) 2122{-# INLINE preuse #-} 2123 2124-- | Retrieve the first index and value targeted by an 'IndexedFold' or 'IndexedTraversal' (or 'Just' the index 2125-- and result from an 'IndexedGetter' or 'IndexedLens') into the current state. 2126-- 2127-- @ 2128-- 'ipreuse' = 'use' '.' 'ipre' 2129-- @ 2130-- 2131-- @ 2132-- 'ipreuse' :: 'MonadState' s m => 'IndexedGetter' i s a -> m ('Maybe' (i, a)) 2133-- 'ipreuse' :: 'MonadState' s m => 'IndexedFold' i s a -> m ('Maybe' (i, a)) 2134-- 'ipreuse' :: 'MonadState' s m => 'IndexedLens'' i s a -> m ('Maybe' (i, a)) 2135-- 'ipreuse' :: 'MonadState' s m => 'IndexedTraversal'' i s a -> m ('Maybe' (i, a)) 2136-- @ 2137ipreuse :: MonadState s m => IndexedGetting i (First (i, a)) s a -> m (Maybe (i, a)) 2138ipreuse l = gets (ipreview l) 2139{-# INLINE ipreuse #-} 2140 2141-- | Retrieve a function of the first value targeted by a 'Fold' or 2142-- 'Traversal' (or 'Just' the result from a 'Getter' or 'Lens') into the current state. 2143-- 2144-- @ 2145-- 'preuses' = 'uses' '.' 'pre' 2146-- @ 2147-- 2148-- @ 2149-- 'preuses' :: 'MonadState' s m => 'Getter' s a -> (a -> r) -> m ('Maybe' r) 2150-- 'preuses' :: 'MonadState' s m => 'Fold' s a -> (a -> r) -> m ('Maybe' r) 2151-- 'preuses' :: 'MonadState' s m => 'Lens'' s a -> (a -> r) -> m ('Maybe' r) 2152-- 'preuses' :: 'MonadState' s m => 'Iso'' s a -> (a -> r) -> m ('Maybe' r) 2153-- 'preuses' :: 'MonadState' s m => 'Traversal'' s a -> (a -> r) -> m ('Maybe' r) 2154-- @ 2155preuses :: MonadState s m => Getting (First r) s a -> (a -> r) -> m (Maybe r) 2156preuses l f = gets (previews l f) 2157{-# INLINE preuses #-} 2158 2159-- | Retrieve a function of the first index and value targeted by an 'IndexedFold' or 2160-- 'IndexedTraversal' (or a function of 'Just' the index and result from an 'IndexedGetter' 2161-- or 'IndexedLens') into the current state. 2162-- 2163-- @ 2164-- 'ipreuses' = 'uses' '.' 'ipre' 2165-- @ 2166-- 2167-- @ 2168-- 'ipreuses' :: 'MonadState' s m => 'IndexedGetter' i s a -> (i -> a -> r) -> m ('Maybe' r) 2169-- 'ipreuses' :: 'MonadState' s m => 'IndexedFold' i s a -> (i -> a -> r) -> m ('Maybe' r) 2170-- 'ipreuses' :: 'MonadState' s m => 'IndexedLens'' i s a -> (i -> a -> r) -> m ('Maybe' r) 2171-- 'ipreuses' :: 'MonadState' s m => 'IndexedTraversal'' i s a -> (i -> a -> r) -> m ('Maybe' r) 2172-- @ 2173ipreuses :: MonadState s m => IndexedGetting i (First r) s a -> (i -> a -> r) -> m (Maybe r) 2174ipreuses l f = gets (ipreviews l f) 2175{-# INLINE ipreuses #-} 2176 2177------------------------------------------------------------------------------ 2178-- Profunctors 2179------------------------------------------------------------------------------ 2180 2181 2182-- | This allows you to 'Control.Traversable.traverse' the elements of a pretty much any 'LensLike' construction in the opposite order. 2183-- 2184-- This will preserve indexes on 'Indexed' types and will give you the elements of a (finite) 'Fold' or 'Traversal' in the opposite order. 2185-- 2186-- This has no practical impact on a 'Getter', 'Setter', 'Lens' or 'Iso'. 2187-- 2188-- /NB:/ To write back through an 'Iso', you want to use 'Control.Lens.Isomorphic.from'. 2189-- Similarly, to write back through an 'Prism', you want to use 'Control.Lens.Review.re'. 2190backwards :: (Profunctor p, Profunctor q) => Optical p q (Backwards f) s t a b -> Optical p q f s t a b 2191backwards l f = forwards #. l (Backwards #. f) 2192{-# INLINE backwards #-} 2193 2194------------------------------------------------------------------------------ 2195-- Indexed Folds 2196------------------------------------------------------------------------------ 2197 2198-- | Fold an 'IndexedFold' or 'IndexedTraversal' by mapping indices and values to an arbitrary 'Monoid' with access 2199-- to the @i@. 2200-- 2201-- When you don't need access to the index then 'foldMapOf' is more flexible in what it accepts. 2202-- 2203-- @ 2204-- 'foldMapOf' l ≡ 'ifoldMapOf' l '.' 'const' 2205-- @ 2206-- 2207-- @ 2208-- 'ifoldMapOf' :: 'IndexedGetter' i s a -> (i -> a -> m) -> s -> m 2209-- 'ifoldMapOf' :: 'Monoid' m => 'IndexedFold' i s a -> (i -> a -> m) -> s -> m 2210-- 'ifoldMapOf' :: 'IndexedLens'' i s a -> (i -> a -> m) -> s -> m 2211-- 'ifoldMapOf' :: 'Monoid' m => 'IndexedTraversal'' i s a -> (i -> a -> m) -> s -> m 2212-- @ 2213-- 2214ifoldMapOf :: IndexedGetting i m s a -> (i -> a -> m) -> s -> m 2215ifoldMapOf l f = getConst #. l (Const #. Indexed f) 2216{-# INLINE ifoldMapOf #-} 2217 2218-- | Right-associative fold of parts of a structure that are viewed through an 'IndexedFold' or 'IndexedTraversal' with 2219-- access to the @i@. 2220-- 2221-- When you don't need access to the index then 'foldrOf' is more flexible in what it accepts. 2222-- 2223-- @ 2224-- 'foldrOf' l ≡ 'ifoldrOf' l '.' 'const' 2225-- @ 2226-- 2227-- @ 2228-- 'ifoldrOf' :: 'IndexedGetter' i s a -> (i -> a -> r -> r) -> r -> s -> r 2229-- 'ifoldrOf' :: 'IndexedFold' i s a -> (i -> a -> r -> r) -> r -> s -> r 2230-- 'ifoldrOf' :: 'IndexedLens'' i s a -> (i -> a -> r -> r) -> r -> s -> r 2231-- 'ifoldrOf' :: 'IndexedTraversal'' i s a -> (i -> a -> r -> r) -> r -> s -> r 2232-- @ 2233ifoldrOf :: IndexedGetting i (Endo r) s a -> (i -> a -> r -> r) -> r -> s -> r 2234ifoldrOf l f z = flip appEndo z . getConst #. l (Const #. Endo #. Indexed f) 2235{-# INLINE ifoldrOf #-} 2236 2237-- | Left-associative fold of the parts of a structure that are viewed through an 'IndexedFold' or 'IndexedTraversal' with 2238-- access to the @i@. 2239-- 2240-- When you don't need access to the index then 'foldlOf' is more flexible in what it accepts. 2241-- 2242-- @ 2243-- 'foldlOf' l ≡ 'ifoldlOf' l '.' 'const' 2244-- @ 2245-- 2246-- @ 2247-- 'ifoldlOf' :: 'IndexedGetter' i s a -> (i -> r -> a -> r) -> r -> s -> r 2248-- 'ifoldlOf' :: 'IndexedFold' i s a -> (i -> r -> a -> r) -> r -> s -> r 2249-- 'ifoldlOf' :: 'IndexedLens'' i s a -> (i -> r -> a -> r) -> r -> s -> r 2250-- 'ifoldlOf' :: 'IndexedTraversal'' i s a -> (i -> r -> a -> r) -> r -> s -> r 2251-- @ 2252ifoldlOf :: IndexedGetting i (Dual (Endo r)) s a -> (i -> r -> a -> r) -> r -> s -> r 2253ifoldlOf l f z = (flip appEndo z .# getDual) `rmap` ifoldMapOf l (\i -> Dual #. Endo #. flip (f i)) 2254{-# INLINE ifoldlOf #-} 2255 2256-- | Return whether or not any element viewed through an 'IndexedFold' or 'IndexedTraversal' 2257-- satisfy a predicate, with access to the @i@. 2258-- 2259-- When you don't need access to the index then 'anyOf' is more flexible in what it accepts. 2260-- 2261-- @ 2262-- 'anyOf' l ≡ 'ianyOf' l '.' 'const' 2263-- @ 2264-- 2265-- @ 2266-- 'ianyOf' :: 'IndexedGetter' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2267-- 'ianyOf' :: 'IndexedFold' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2268-- 'ianyOf' :: 'IndexedLens'' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2269-- 'ianyOf' :: 'IndexedTraversal'' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2270-- @ 2271ianyOf :: IndexedGetting i Any s a -> (i -> a -> Bool) -> s -> Bool 2272ianyOf l f = getAny #. getConst #. l (Const #. Any #. Indexed f) 2273{-# INLINE ianyOf #-} 2274 2275-- | Return whether or not all elements viewed through an 'IndexedFold' or 'IndexedTraversal' 2276-- satisfy a predicate, with access to the @i@. 2277-- 2278-- When you don't need access to the index then 'allOf' is more flexible in what it accepts. 2279-- 2280-- @ 2281-- 'allOf' l ≡ 'iallOf' l '.' 'const' 2282-- @ 2283-- 2284-- @ 2285-- 'iallOf' :: 'IndexedGetter' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2286-- 'iallOf' :: 'IndexedFold' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2287-- 'iallOf' :: 'IndexedLens'' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2288-- 'iallOf' :: 'IndexedTraversal'' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2289-- @ 2290iallOf :: IndexedGetting i All s a -> (i -> a -> Bool) -> s -> Bool 2291iallOf l f = getAll #. getConst #. l (Const #. All #. Indexed f) 2292{-# INLINE iallOf #-} 2293 2294-- | Return whether or not none of the elements viewed through an 'IndexedFold' or 'IndexedTraversal' 2295-- satisfy a predicate, with access to the @i@. 2296-- 2297-- When you don't need access to the index then 'noneOf' is more flexible in what it accepts. 2298-- 2299-- @ 2300-- 'noneOf' l ≡ 'inoneOf' l '.' 'const' 2301-- @ 2302-- 2303-- @ 2304-- 'inoneOf' :: 'IndexedGetter' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2305-- 'inoneOf' :: 'IndexedFold' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2306-- 'inoneOf' :: 'IndexedLens'' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2307-- 'inoneOf' :: 'IndexedTraversal'' i s a -> (i -> a -> 'Bool') -> s -> 'Bool' 2308-- @ 2309inoneOf :: IndexedGetting i Any s a -> (i -> a -> Bool) -> s -> Bool 2310inoneOf l f = not . ianyOf l f 2311{-# INLINE inoneOf #-} 2312 2313-- | Traverse the targets of an 'IndexedFold' or 'IndexedTraversal' with access to the @i@, discarding the results. 2314-- 2315-- When you don't need access to the index then 'traverseOf_' is more flexible in what it accepts. 2316-- 2317-- @ 2318-- 'traverseOf_' l ≡ 'Control.Lens.Traversal.itraverseOf' l '.' 'const' 2319-- @ 2320-- 2321-- @ 2322-- 'itraverseOf_' :: 'Functor' f => 'IndexedGetter' i s a -> (i -> a -> f r) -> s -> f () 2323-- 'itraverseOf_' :: 'Applicative' f => 'IndexedFold' i s a -> (i -> a -> f r) -> s -> f () 2324-- 'itraverseOf_' :: 'Functor' f => 'IndexedLens'' i s a -> (i -> a -> f r) -> s -> f () 2325-- 'itraverseOf_' :: 'Applicative' f => 'IndexedTraversal'' i s a -> (i -> a -> f r) -> s -> f () 2326-- @ 2327itraverseOf_ :: Functor f => IndexedGetting i (Traversed r f) s a -> (i -> a -> f r) -> s -> f () 2328itraverseOf_ l f = void . getTraversed #. getConst #. l (Const #. Traversed #. Indexed f) 2329{-# INLINE itraverseOf_ #-} 2330 2331-- | Traverse the targets of an 'IndexedFold' or 'IndexedTraversal' with access to the index, discarding the results 2332-- (with the arguments flipped). 2333-- 2334-- @ 2335-- 'iforOf_' ≡ 'flip' '.' 'itraverseOf_' 2336-- @ 2337-- 2338-- When you don't need access to the index then 'forOf_' is more flexible in what it accepts. 2339-- 2340-- @ 2341-- 'forOf_' l a ≡ 'iforOf_' l a '.' 'const' 2342-- @ 2343-- 2344-- @ 2345-- 'iforOf_' :: 'Functor' f => 'IndexedGetter' i s a -> s -> (i -> a -> f r) -> f () 2346-- 'iforOf_' :: 'Applicative' f => 'IndexedFold' i s a -> s -> (i -> a -> f r) -> f () 2347-- 'iforOf_' :: 'Functor' f => 'IndexedLens'' i s a -> s -> (i -> a -> f r) -> f () 2348-- 'iforOf_' :: 'Applicative' f => 'IndexedTraversal'' i s a -> s -> (i -> a -> f r) -> f () 2349-- @ 2350iforOf_ :: Functor f => IndexedGetting i (Traversed r f) s a -> s -> (i -> a -> f r) -> f () 2351iforOf_ = flip . itraverseOf_ 2352{-# INLINE iforOf_ #-} 2353 2354-- | Run monadic actions for each target of an 'IndexedFold' or 'IndexedTraversal' with access to the index, 2355-- discarding the results. 2356-- 2357-- When you don't need access to the index then 'mapMOf_' is more flexible in what it accepts. 2358-- 2359-- @ 2360-- 'mapMOf_' l ≡ 'Control.Lens.Setter.imapMOf' l '.' 'const' 2361-- @ 2362-- 2363-- @ 2364-- 'imapMOf_' :: 'Monad' m => 'IndexedGetter' i s a -> (i -> a -> m r) -> s -> m () 2365-- 'imapMOf_' :: 'Monad' m => 'IndexedFold' i s a -> (i -> a -> m r) -> s -> m () 2366-- 'imapMOf_' :: 'Monad' m => 'IndexedLens'' i s a -> (i -> a -> m r) -> s -> m () 2367-- 'imapMOf_' :: 'Monad' m => 'IndexedTraversal'' i s a -> (i -> a -> m r) -> s -> m () 2368-- @ 2369imapMOf_ :: Monad m => IndexedGetting i (Sequenced r m) s a -> (i -> a -> m r) -> s -> m () 2370imapMOf_ l f = liftM skip . getSequenced #. getConst #. l (Const #. Sequenced #. Indexed f) 2371{-# INLINE imapMOf_ #-} 2372 2373-- | Run monadic actions for each target of an 'IndexedFold' or 'IndexedTraversal' with access to the index, 2374-- discarding the results (with the arguments flipped). 2375-- 2376-- @ 2377-- 'iforMOf_' ≡ 'flip' '.' 'imapMOf_' 2378-- @ 2379-- 2380-- When you don't need access to the index then 'forMOf_' is more flexible in what it accepts. 2381-- 2382-- @ 2383-- 'forMOf_' l a ≡ 'Control.Lens.Traversal.iforMOf' l a '.' 'const' 2384-- @ 2385-- 2386-- @ 2387-- 'iforMOf_' :: 'Monad' m => 'IndexedGetter' i s a -> s -> (i -> a -> m r) -> m () 2388-- 'iforMOf_' :: 'Monad' m => 'IndexedFold' i s a -> s -> (i -> a -> m r) -> m () 2389-- 'iforMOf_' :: 'Monad' m => 'IndexedLens'' i s a -> s -> (i -> a -> m r) -> m () 2390-- 'iforMOf_' :: 'Monad' m => 'IndexedTraversal'' i s a -> s -> (i -> a -> m r) -> m () 2391-- @ 2392iforMOf_ :: Monad m => IndexedGetting i (Sequenced r m) s a -> s -> (i -> a -> m r) -> m () 2393iforMOf_ = flip . imapMOf_ 2394{-# INLINE iforMOf_ #-} 2395 2396-- | Concatenate the results of a function of the elements of an 'IndexedFold' or 'IndexedTraversal' 2397-- with access to the index. 2398-- 2399-- When you don't need access to the index then 'concatMapOf' is more flexible in what it accepts. 2400-- 2401-- @ 2402-- 'concatMapOf' l ≡ 'iconcatMapOf' l '.' 'const' 2403-- 'iconcatMapOf' ≡ 'ifoldMapOf' 2404-- @ 2405-- 2406-- @ 2407-- 'iconcatMapOf' :: 'IndexedGetter' i s a -> (i -> a -> [r]) -> s -> [r] 2408-- 'iconcatMapOf' :: 'IndexedFold' i s a -> (i -> a -> [r]) -> s -> [r] 2409-- 'iconcatMapOf' :: 'IndexedLens'' i s a -> (i -> a -> [r]) -> s -> [r] 2410-- 'iconcatMapOf' :: 'IndexedTraversal'' i s a -> (i -> a -> [r]) -> s -> [r] 2411-- @ 2412iconcatMapOf :: IndexedGetting i [r] s a -> (i -> a -> [r]) -> s -> [r] 2413iconcatMapOf = ifoldMapOf 2414{-# INLINE iconcatMapOf #-} 2415 2416-- | The 'ifindOf' function takes an 'IndexedFold' or 'IndexedTraversal', a predicate that is also 2417-- supplied the index, a structure and returns the left-most element of the structure 2418-- matching the predicate, or 'Nothing' if there is no such element. 2419-- 2420-- When you don't need access to the index then 'findOf' is more flexible in what it accepts. 2421-- 2422-- @ 2423-- 'findOf' l ≡ 'ifindOf' l '.' 'const' 2424-- @ 2425-- 2426-- @ 2427-- 'ifindOf' :: 'IndexedGetter' i s a -> (i -> a -> 'Bool') -> s -> 'Maybe' a 2428-- 'ifindOf' :: 'IndexedFold' i s a -> (i -> a -> 'Bool') -> s -> 'Maybe' a 2429-- 'ifindOf' :: 'IndexedLens'' i s a -> (i -> a -> 'Bool') -> s -> 'Maybe' a 2430-- 'ifindOf' :: 'IndexedTraversal'' i s a -> (i -> a -> 'Bool') -> s -> 'Maybe' a 2431-- @ 2432ifindOf :: IndexedGetting i (Endo (Maybe a)) s a -> (i -> a -> Bool) -> s -> Maybe a 2433ifindOf l f = ifoldrOf l (\i a y -> if f i a then Just a else y) Nothing 2434{-# INLINE ifindOf #-} 2435 2436-- | The 'ifindMOf' function takes an 'IndexedFold' or 'IndexedTraversal', a monadic predicate that is also 2437-- supplied the index, a structure and returns in the monad the left-most element of the structure 2438-- matching the predicate, or 'Nothing' if there is no such element. 2439-- 2440-- When you don't need access to the index then 'findMOf' is more flexible in what it accepts. 2441-- 2442-- @ 2443-- 'findMOf' l ≡ 'ifindMOf' l '.' 'const' 2444-- @ 2445-- 2446-- @ 2447-- 'ifindMOf' :: 'Monad' m => 'IndexedGetter' i s a -> (i -> a -> m 'Bool') -> s -> m ('Maybe' a) 2448-- 'ifindMOf' :: 'Monad' m => 'IndexedFold' i s a -> (i -> a -> m 'Bool') -> s -> m ('Maybe' a) 2449-- 'ifindMOf' :: 'Monad' m => 'IndexedLens'' i s a -> (i -> a -> m 'Bool') -> s -> m ('Maybe' a) 2450-- 'ifindMOf' :: 'Monad' m => 'IndexedTraversal'' i s a -> (i -> a -> m 'Bool') -> s -> m ('Maybe' a) 2451-- @ 2452ifindMOf :: Monad m => IndexedGetting i (Endo (m (Maybe a))) s a -> (i -> a -> m Bool) -> s -> m (Maybe a) 2453ifindMOf l f = ifoldrOf l (\i a y -> f i a >>= \r -> if r then return (Just a) else y) $ return Nothing 2454{-# INLINE ifindMOf #-} 2455 2456-- | /Strictly/ fold right over the elements of a structure with an index. 2457-- 2458-- When you don't need access to the index then 'foldrOf'' is more flexible in what it accepts. 2459-- 2460-- @ 2461-- 'foldrOf'' l ≡ 'ifoldrOf'' l '.' 'const' 2462-- @ 2463-- 2464-- @ 2465-- 'ifoldrOf'' :: 'IndexedGetter' i s a -> (i -> a -> r -> r) -> r -> s -> r 2466-- 'ifoldrOf'' :: 'IndexedFold' i s a -> (i -> a -> r -> r) -> r -> s -> r 2467-- 'ifoldrOf'' :: 'IndexedLens'' i s a -> (i -> a -> r -> r) -> r -> s -> r 2468-- 'ifoldrOf'' :: 'IndexedTraversal'' i s a -> (i -> a -> r -> r) -> r -> s -> r 2469-- @ 2470ifoldrOf' :: IndexedGetting i (Dual (Endo (r -> r))) s a -> (i -> a -> r -> r) -> r -> s -> r 2471ifoldrOf' l f z0 xs = ifoldlOf l f' id xs z0 2472 where f' i k x z = k $! f i x z 2473{-# INLINE ifoldrOf' #-} 2474 2475-- | Fold over the elements of a structure with an index, associating to the left, but /strictly/. 2476-- 2477-- When you don't need access to the index then 'foldlOf'' is more flexible in what it accepts. 2478-- 2479-- @ 2480-- 'foldlOf'' l ≡ 'ifoldlOf'' l '.' 'const' 2481-- @ 2482-- 2483-- @ 2484-- 'ifoldlOf'' :: 'IndexedGetter' i s a -> (i -> r -> a -> r) -> r -> s -> r 2485-- 'ifoldlOf'' :: 'IndexedFold' i s a -> (i -> r -> a -> r) -> r -> s -> r 2486-- 'ifoldlOf'' :: 'IndexedLens'' i s a -> (i -> r -> a -> r) -> r -> s -> r 2487-- 'ifoldlOf'' :: 'IndexedTraversal'' i s a -> (i -> r -> a -> r) -> r -> s -> r 2488-- @ 2489ifoldlOf' :: IndexedGetting i (Endo (r -> r)) s a -> (i -> r -> a -> r) -> r -> s -> r 2490ifoldlOf' l f z0 xs = ifoldrOf l f' id xs z0 2491 where f' i x k z = k $! f i z x 2492{-# INLINE ifoldlOf' #-} 2493 2494-- | Monadic fold right over the elements of a structure with an index. 2495-- 2496-- When you don't need access to the index then 'foldrMOf' is more flexible in what it accepts. 2497-- 2498-- @ 2499-- 'foldrMOf' l ≡ 'ifoldrMOf' l '.' 'const' 2500-- @ 2501-- 2502-- @ 2503-- 'ifoldrMOf' :: 'Monad' m => 'IndexedGetter' i s a -> (i -> a -> r -> m r) -> r -> s -> m r 2504-- 'ifoldrMOf' :: 'Monad' m => 'IndexedFold' i s a -> (i -> a -> r -> m r) -> r -> s -> m r 2505-- 'ifoldrMOf' :: 'Monad' m => 'IndexedLens'' i s a -> (i -> a -> r -> m r) -> r -> s -> m r 2506-- 'ifoldrMOf' :: 'Monad' m => 'IndexedTraversal'' i s a -> (i -> a -> r -> m r) -> r -> s -> m r 2507-- @ 2508ifoldrMOf :: Monad m => IndexedGetting i (Dual (Endo (r -> m r))) s a -> (i -> a -> r -> m r) -> r -> s -> m r 2509ifoldrMOf l f z0 xs = ifoldlOf l f' return xs z0 2510 where f' i k x z = f i x z >>= k 2511{-# INLINE ifoldrMOf #-} 2512 2513-- | Monadic fold over the elements of a structure with an index, associating to the left. 2514-- 2515-- When you don't need access to the index then 'foldlMOf' is more flexible in what it accepts. 2516-- 2517-- @ 2518-- 'foldlMOf' l ≡ 'ifoldlMOf' l '.' 'const' 2519-- @ 2520-- 2521-- @ 2522-- 'ifoldlMOf' :: 'Monad' m => 'IndexedGetter' i s a -> (i -> r -> a -> m r) -> r -> s -> m r 2523-- 'ifoldlMOf' :: 'Monad' m => 'IndexedFold' i s a -> (i -> r -> a -> m r) -> r -> s -> m r 2524-- 'ifoldlMOf' :: 'Monad' m => 'IndexedLens'' i s a -> (i -> r -> a -> m r) -> r -> s -> m r 2525-- 'ifoldlMOf' :: 'Monad' m => 'IndexedTraversal'' i s a -> (i -> r -> a -> m r) -> r -> s -> m r 2526-- @ 2527ifoldlMOf :: Monad m => IndexedGetting i (Endo (r -> m r)) s a -> (i -> r -> a -> m r) -> r -> s -> m r 2528ifoldlMOf l f z0 xs = ifoldrOf l f' return xs z0 2529 where f' i x k z = f i z x >>= k 2530{-# INLINE ifoldlMOf #-} 2531 2532-- | Extract the key-value pairs from a structure. 2533-- 2534-- When you don't need access to the indices in the result, then 'toListOf' is more flexible in what it accepts. 2535-- 2536-- @ 2537-- 'toListOf' l ≡ 'map' 'snd' '.' 'itoListOf' l 2538-- @ 2539-- 2540-- @ 2541-- 'itoListOf' :: 'IndexedGetter' i s a -> s -> [(i,a)] 2542-- 'itoListOf' :: 'IndexedFold' i s a -> s -> [(i,a)] 2543-- 'itoListOf' :: 'IndexedLens'' i s a -> s -> [(i,a)] 2544-- 'itoListOf' :: 'IndexedTraversal'' i s a -> s -> [(i,a)] 2545-- @ 2546itoListOf :: IndexedGetting i (Endo [(i,a)]) s a -> s -> [(i,a)] 2547itoListOf l = ifoldrOf l (\i a -> ((i,a):)) [] 2548{-# INLINE itoListOf #-} 2549 2550-- | An infix version of 'itoListOf'. 2551 2552-- @ 2553-- ('^@..') :: s -> 'IndexedGetter' i s a -> [(i,a)] 2554-- ('^@..') :: s -> 'IndexedFold' i s a -> [(i,a)] 2555-- ('^@..') :: s -> 'IndexedLens'' i s a -> [(i,a)] 2556-- ('^@..') :: s -> 'IndexedTraversal'' i s a -> [(i,a)] 2557-- @ 2558(^@..) :: s -> IndexedGetting i (Endo [(i,a)]) s a -> [(i,a)] 2559s ^@.. l = ifoldrOf l (\i a -> ((i,a):)) [] s 2560{-# INLINE (^@..) #-} 2561 2562-- | Perform a safe 'head' (with index) of an 'IndexedFold' or 'IndexedTraversal' or retrieve 'Just' the index and result 2563-- from an 'IndexedGetter' or 'IndexedLens'. 2564-- 2565-- When using a 'IndexedTraversal' as a partial 'IndexedLens', or an 'IndexedFold' as a partial 'IndexedGetter' this can be a convenient 2566-- way to extract the optional value. 2567-- 2568-- @ 2569-- ('^@?') :: s -> 'IndexedGetter' i s a -> 'Maybe' (i, a) 2570-- ('^@?') :: s -> 'IndexedFold' i s a -> 'Maybe' (i, a) 2571-- ('^@?') :: s -> 'IndexedLens'' i s a -> 'Maybe' (i, a) 2572-- ('^@?') :: s -> 'IndexedTraversal'' i s a -> 'Maybe' (i, a) 2573-- @ 2574(^@?) :: s -> IndexedGetting i (Endo (Maybe (i, a))) s a -> Maybe (i, a) 2575s ^@? l = ifoldrOf l (\i x _ -> Just (i,x)) Nothing s 2576{-# INLINE (^@?) #-} 2577 2578-- | Perform an *UNSAFE* 'head' (with index) of an 'IndexedFold' or 'IndexedTraversal' assuming that it is there. 2579-- 2580-- @ 2581-- ('^@?!') :: s -> 'IndexedGetter' i s a -> (i, a) 2582-- ('^@?!') :: s -> 'IndexedFold' i s a -> (i, a) 2583-- ('^@?!') :: s -> 'IndexedLens'' i s a -> (i, a) 2584-- ('^@?!') :: s -> 'IndexedTraversal'' i s a -> (i, a) 2585-- @ 2586(^@?!) :: HasCallStack => s -> IndexedGetting i (Endo (i, a)) s a -> (i, a) 2587s ^@?! l = ifoldrOf l (\i x _ -> (i,x)) (error "(^@?!): empty Fold") s 2588{-# INLINE (^@?!) #-} 2589 2590-- | Retrieve the index of the first value targeted by a 'IndexedFold' or 'IndexedTraversal' which is equal to a given value. 2591-- 2592-- @ 2593-- 'Data.List.elemIndex' ≡ 'elemIndexOf' 'folded' 2594-- @ 2595-- 2596-- @ 2597-- 'elemIndexOf' :: 'Eq' a => 'IndexedFold' i s a -> a -> s -> 'Maybe' i 2598-- 'elemIndexOf' :: 'Eq' a => 'IndexedTraversal'' i s a -> a -> s -> 'Maybe' i 2599-- @ 2600elemIndexOf :: Eq a => IndexedGetting i (First i) s a -> a -> s -> Maybe i 2601elemIndexOf l a = findIndexOf l (a ==) 2602{-# INLINE elemIndexOf #-} 2603 2604-- | Retrieve the indices of the values targeted by a 'IndexedFold' or 'IndexedTraversal' which are equal to a given value. 2605-- 2606-- @ 2607-- 'Data.List.elemIndices' ≡ 'elemIndicesOf' 'folded' 2608-- @ 2609-- 2610-- @ 2611-- 'elemIndicesOf' :: 'Eq' a => 'IndexedFold' i s a -> a -> s -> [i] 2612-- 'elemIndicesOf' :: 'Eq' a => 'IndexedTraversal'' i s a -> a -> s -> [i] 2613-- @ 2614elemIndicesOf :: Eq a => IndexedGetting i (Endo [i]) s a -> a -> s -> [i] 2615elemIndicesOf l a = findIndicesOf l (a ==) 2616{-# INLINE elemIndicesOf #-} 2617 2618-- | Retrieve the index of the first value targeted by a 'IndexedFold' or 'IndexedTraversal' which satisfies a predicate. 2619-- 2620-- @ 2621-- 'Data.List.findIndex' ≡ 'findIndexOf' 'folded' 2622-- @ 2623-- 2624-- @ 2625-- 'findIndexOf' :: 'IndexedFold' i s a -> (a -> 'Bool') -> s -> 'Maybe' i 2626-- 'findIndexOf' :: 'IndexedTraversal'' i s a -> (a -> 'Bool') -> s -> 'Maybe' i 2627-- @ 2628findIndexOf :: IndexedGetting i (First i) s a -> (a -> Bool) -> s -> Maybe i 2629findIndexOf l p = preview (l . filtered p . asIndex) 2630{-# INLINE findIndexOf #-} 2631 2632-- | Retrieve the indices of the values targeted by a 'IndexedFold' or 'IndexedTraversal' which satisfy a predicate. 2633-- 2634-- @ 2635-- 'Data.List.findIndices' ≡ 'findIndicesOf' 'folded' 2636-- @ 2637-- 2638-- @ 2639-- 'findIndicesOf' :: 'IndexedFold' i s a -> (a -> 'Bool') -> s -> [i] 2640-- 'findIndicesOf' :: 'IndexedTraversal'' i s a -> (a -> 'Bool') -> s -> [i] 2641-- @ 2642findIndicesOf :: IndexedGetting i (Endo [i]) s a -> (a -> Bool) -> s -> [i] 2643findIndicesOf l p = toListOf (l . filtered p . asIndex) 2644{-# INLINE findIndicesOf #-} 2645 2646------------------------------------------------------------------------------- 2647-- Converting to Folds 2648------------------------------------------------------------------------------- 2649 2650-- | Filter an 'IndexedFold' or 'IndexedGetter', obtaining an 'IndexedFold'. 2651-- 2652-- >>> [0,0,0,5,5,5]^..traversed.ifiltered (\i a -> i <= a) 2653-- [0,5,5,5] 2654-- 2655-- Compose with 'ifiltered' to filter another 'IndexedLens', 'IndexedIso', 'IndexedGetter', 'IndexedFold' (or 'IndexedTraversal') with 2656-- access to both the value and the index. 2657-- 2658-- Note: As with 'filtered', this is /not/ a legal 'IndexedTraversal', unless you are very careful not to invalidate the predicate on the target! 2659ifiltered :: (Indexable i p, Applicative f) => (i -> a -> Bool) -> Optical' p (Indexed i) f a a 2660ifiltered p f = Indexed $ \i a -> if p i a then indexed f i a else pure a 2661{-# INLINE ifiltered #-} 2662 2663-- | Obtain an 'IndexedFold' by taking elements from another 2664-- 'IndexedFold', 'IndexedLens', 'IndexedGetter' or 'IndexedTraversal' while a predicate holds. 2665-- 2666-- @ 2667-- 'itakingWhile' :: (i -> a -> 'Bool') -> 'IndexedFold' i s a -> 'IndexedFold' i s a 2668-- 'itakingWhile' :: (i -> a -> 'Bool') -> 'IndexedTraversal'' i s a -> 'IndexedFold' i s a 2669-- 'itakingWhile' :: (i -> a -> 'Bool') -> 'IndexedLens'' i s a -> 'IndexedFold' i s a 2670-- 'itakingWhile' :: (i -> a -> 'Bool') -> 'IndexedGetter' i s a -> 'IndexedFold' i s a 2671-- @ 2672-- 2673-- Note: Applying 'itakingWhile' to an 'IndexedLens' or 'IndexedTraversal' will still allow you to use it as a 2674-- pseudo-'IndexedTraversal', but if you change the value of any target to one where the predicate returns 2675-- 'False', then you will break the 'Traversal' laws and 'Traversal' fusion will no longer be sound. 2676itakingWhile :: (Indexable i p, Profunctor q, Contravariant f, Applicative f) 2677 => (i -> a -> Bool) 2678 -> Optical' (Indexed i) q (Const (Endo (f s))) s a 2679 -> Optical' p q f s a 2680itakingWhile p l f = (flip appEndo noEffect .# getConst) `rmap` l g where 2681 g = Indexed $ \i a -> Const . Endo $ if p i a then (indexed f i a *>) else const noEffect 2682{-# INLINE itakingWhile #-} 2683 2684-- | Obtain an 'IndexedFold' by dropping elements from another 'IndexedFold', 'IndexedLens', 'IndexedGetter' or 'IndexedTraversal' while a predicate holds. 2685-- 2686-- @ 2687-- 'idroppingWhile' :: (i -> a -> 'Bool') -> 'IndexedFold' i s a -> 'IndexedFold' i s a 2688-- 'idroppingWhile' :: (i -> a -> 'Bool') -> 'IndexedTraversal'' i s a -> 'IndexedFold' i s a -- see notes 2689-- 'idroppingWhile' :: (i -> a -> 'Bool') -> 'IndexedLens'' i s a -> 'IndexedFold' i s a -- see notes 2690-- 'idroppingWhile' :: (i -> a -> 'Bool') -> 'IndexedGetter' i s a -> 'IndexedFold' i s a 2691-- @ 2692-- 2693-- Note: As with `droppingWhile` applying 'idroppingWhile' to an 'IndexedLens' or 'IndexedTraversal' will still 2694-- allow you to use it as a pseudo-'IndexedTraversal', but if you change the value of the first target to one 2695-- where the predicate returns 'True', then you will break the 'Traversal' laws and 'Traversal' fusion will 2696-- no longer be sound. 2697idroppingWhile :: (Indexable i p, Profunctor q, Applicative f) 2698 => (i -> a -> Bool) 2699 -> Optical (Indexed i) q (Compose (State Bool) f) s t a a 2700 -> Optical p q f s t a a 2701idroppingWhile p l f = (flip evalState True .# getCompose) `rmap` l g where 2702 g = Indexed $ \ i a -> Compose $ state $ \b -> let 2703 b' = b && p i a 2704 in (if b' then pure a else indexed f i a, b') 2705{-# INLINE idroppingWhile #-} 2706 2707------------------------------------------------------------------------------ 2708-- Misc. 2709------------------------------------------------------------------------------ 2710 2711skip :: a -> () 2712skip _ = () 2713{-# INLINE skip #-} 2714 2715------------------------------------------------------------------------------ 2716-- Folds with Reified Monoid 2717------------------------------------------------------------------------------ 2718 2719-- | Fold a value using a specified 'Fold' and 'Monoid' operations. 2720-- This is like 'foldBy' where the 'Foldable' instance can be 2721-- manually specified. 2722-- 2723-- @ 2724-- 'foldByOf' 'folded' ≡ 'foldBy' 2725-- @ 2726-- 2727-- @ 2728-- 'foldByOf' :: 'Getter' s a -> (a -> a -> a) -> a -> s -> a 2729-- 'foldByOf' :: 'Fold' s a -> (a -> a -> a) -> a -> s -> a 2730-- 'foldByOf' :: 'Lens'' s a -> (a -> a -> a) -> a -> s -> a 2731-- 'foldByOf' :: 'Traversal'' s a -> (a -> a -> a) -> a -> s -> a 2732-- 'foldByOf' :: 'Iso'' s a -> (a -> a -> a) -> a -> s -> a 2733-- @ 2734-- 2735-- >>> foldByOf both (++) [] ("hello","world") 2736-- "helloworld" 2737foldByOf :: Fold s a -> (a -> a -> a) -> a -> s -> a 2738foldByOf l f z = reifyMonoid f z (foldMapOf l ReflectedMonoid) 2739 2740-- | Fold a value using a specified 'Fold' and 'Monoid' operations. 2741-- This is like 'foldMapBy' where the 'Foldable' instance can be 2742-- manually specified. 2743-- 2744-- @ 2745-- 'foldMapByOf' 'folded' ≡ 'foldMapBy' 2746-- @ 2747-- 2748-- @ 2749-- 'foldMapByOf' :: 'Getter' s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r 2750-- 'foldMapByOf' :: 'Fold' s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r 2751-- 'foldMapByOf' :: 'Traversal'' s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r 2752-- 'foldMapByOf' :: 'Lens'' s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r 2753-- 'foldMapByOf' :: 'Iso'' s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r 2754-- @ 2755-- 2756-- >>> foldMapByOf both (+) 0 length ("hello","world") 2757-- 10 2758foldMapByOf :: Fold s a -> (r -> r -> r) -> r -> (a -> r) -> s -> r 2759foldMapByOf l f z g = reifyMonoid f z (foldMapOf l (ReflectedMonoid #. g)) 2760