Optics.Extra

& is a reverse application operator. This provides notational convenience. Its precedence is one higher than that of the forward application operator $, which allows & to be nested in $.

This is a version of flip id, where id is specialized from a -> a to (a -> b) -> (a -> b) which by the associativity of (->) is (a -> b) -> a -> b. flipping this yields a -> (a -> b) -> b which is the type signature of &

Examples

>>> 5 & (+1) & show"6"

>>> sqrt $ [1 / n^2 | n <- [1..1000]] & sum & (*6)3.1406380562059946

Flipped version of <$>.

(<&>) = flip fmap

Examples

Apply (+1) to a list, a Just and a Right:

>>> Just 2 <&> (+1)Just 3

>>> [1,2,3] <&> (+1)[2,3,4]

>>> Right 3 <&> (+1)Right 4

Traverse elements with access to the index i, discarding the results (with the arguments flipped).

ifor_ ≡ flip itraverse_

When you don't need access to the index then for_ is more flexible in what it accepts.

for_ a ≡ ifor_ a . const

Extract the key-value pairs from a structure.

When you don't need access to the indices in the result, then toList is more flexible in what it accepts.

toList ≡ Data.List.map snd . itoList

Traverse elements with access to the index i, discarding the results.

When you don't need access to the index then traverse_ is more flexible in what it accepts.

traverse_ l = itraverse . const

Traverse with an index (and the arguments flipped).

for a ≡ ifor a . const
ifor ≡ flip itraverse

A Prism that matches on the Left constructor of Either.

A Prism that matches on the Right constructor of Either.

Shortcut for % _Just %.

Useful for composing lenses of Maybe type.

A Prism that matches on the Just constructor of Maybe.

A Prism that matches on the Nothing constructor of Maybe.

Strict version of _1

Strict version of _2

Strict version of _3

Strict version of _4

Strict version of _5

Strict version of _6

Strict version of _7

Strict version of _8

Strict version of _9

Try the first AffineFold. If it returns no entry, try the second one.

>>> preview (ix 1 % re _Left `afailing` ix 2 % re _Right) [0,1,2,3]Just (Left 1)

>>> preview (ix 42 % re _Left `afailing` ix 2 % re _Right) [0,1,2,3]Just (Right 2)

Obtain an AffineFold by lifting traverse_ like function.

afoldVL . atraverseOf_ ≡ id
atraverseOf_ . afoldVL ≡ id

Create an AffineFold from a partial function.

>>> preview (afolding listToMaybe) "foo"Just 'f'

Traverse over the target of an AffineFold, computing a Functor-based answer, but unlike atraverseOf do not construct a new structure.

Filter result(s) of a fold that don't satisfy a predicate.

Check to see if this AffineFold doesn't match.

>>> isn't _Just NothingTrue

The negation of this operator is is from Optics.Core.Extras.

Retrieve the value targeted by an AffineFold.

>>> let _Right = prism Right $ either (Left . Left) Right

>>> preview _Right (Right 'x')Just 'x'

>>> preview _Right (Left 'y')Nothing

Retrieve a function of the value targeted by an AffineFold.

Try the first AffineTraversal. If it does not return an entry, try the second one.

>>> over (ix 2 `adisjoin` ix 1) (*5) [1,2,3][1,2,15]>>> over (ix 2 `adisjoin` ix 1) (*5) [1,2][1,10]

Build an affine traversal from a matcher and an updater.

If you want to build an AffineTraversal from the van Laarhoven representation, use atraversalVL.

Build an affine traversal from the van Laarhoven representation.

Example:

>>> :{azSnd = atraversalVL $ \point f ab@(a, b) ->  if a >= 'a' && a <= 'z'  then (a, ) <$> f b  else point ab:}

>>> preview azSnd ('a', "Hi")Just "Hi"

>>> preview azSnd ('@', "Hi")Nothing

>>> over azSnd (++ "!!!") ('f', "Hi")('f',"Hi!!!")

>>> set azSnd "Bye" ('Y', "Hi")('Y',"Hi")

Traverse over the target of an AffineTraversal and compute a Functor-based answer.

Retrieve the value targeted by an AffineTraversal or return the original value while allowing the type to change if it does not match.

preview o ≡ either (const Nothing) id . matching o

Filter result(s) of a traversal that don't satisfy a predicate.

Note: This is not a legal Traversal, unless you are very careful not to invalidate the predicate on the target.

As a counter example, consider that given evens = unsafeFiltered even the second Traversal law is violated:

over evens succ . Optics.over evens succ /= over evens (succ . succ)

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!

For a safe variant see indices (or filtered for read-only optics).

Work with an affine traversal as a matcher and an updater.

Run an arrow command and use the output to set all the targets of an optic to the result.

runKleisli action ((), (), ()) where
  action =      assignA _1 (Kleisli (const getVal1))
           >>> assignA _2 (Kleisli (const getVal2))
           >>> assignA _3 (Kleisli (const getVal3))
  getVal1 :: Either String Int
  getVal1 = ...
  getVal2 :: Either String Bool
  getVal2 = ...
  getVal3 :: Either String Char
  getVal3 = ...

has the type Either String (Int, Bool, Char)

Version of at strict in the value inside the Just constructor.

Example:

>>> (at () .~ Just (error "oops") $ Nothing) `seq` ()()

>>> (at' () .~ Just (error "oops") $ Nothing) `seq` ()*** Exception: oops...

>>> view (at ()) (Just $ error "oops") `seq` ()()

>>> view (at' ()) (Just $ error "oops") `seq` ()*** Exception: oops...

It also works as expected for other data structures:

>>> (at 1 .~ Just (error "oops") $ Map.empty) `seq` ()()

>>> (at' 1 .~ Just (error "oops") $ Map.empty) `seq` ()*** Exception: oops...

A definition of ix for types with an At instance. This is the default if you don't specify a definition for ix.

Delete the value associated with a key in a Map-like container

sans k = at k .~ Nothing

Lift coerce to the a parameter of an optic.

Lift coerce to the b parameter of an optic.

Lift coerce to the s parameter of an optic.

Lift coerce to the t parameter of an optic.

Pattern synonym for matching on the leftmost element of a structure.

>>> case ['a','b','c'] of (x :< _) -> x'a'

Pattern synonym for matching on the rightmost element of a structure.

>>> case ['a','b','c'] of (_ :> x) -> x'c'

cons an element onto a container.

This is an infix alias for cons.

>>> 1 <| [][1]

>>> 'a' <| "bc""abc"

>>> 1 <| [][1]

>>> 1 <| [2, 3][1,2,3]

An AffineTraversal reading and writing to the head of a non-empty container.

>>> "abc" ^? _headJust 'a'

>>> "abc" & _head .~ 'd'"dbc"

>>> [1,2,3] & _head %~ (*10)[10,2,3]

>>> [] & _head %~ absurd[]

>>> [1,2,3] ^? _headJust 1

>>> [] ^? _headNothing

>>> [1,2] ^? _headJust 1

>>> [] & _head .~ 1[]

>>> [0] & _head .~ 2[2]

>>> [0,1] & _head .~ 2[2,1]

An AffineTraversal reading and replacing all but the a last element of a non-empty container.

>>> "abcd" ^? _initJust "abc"

>>> "" ^? _initNothing

>>> "ab" & _init .~ "cde""cdeb"

>>> [] & _init .~ [1,2][]

>>> [1,2,3,4] & _init % traversed %~ (*10)[10,20,30,4]

>>> [1,2,3] ^? _initJust [1,2]

>>> "hello" ^? _initJust "hell"

>>> [] ^? _initNothing

An AffineTraversal reading and writing to the last element of a non-empty container.

>>> "abc" ^? _lastJust 'c'

>>> "" ^? _lastNothing

>>> [1,2,3] & _last %~ (+1)[1,2,4]

>>> [1,2] ^? _lastJust 2

>>> [] & _last .~ 1[]

>>> [0] & _last .~ 2[2]

>>> [0,1] & _last .~ 2[0,2]

An AffineTraversal reading and writing to the tail of a non-empty container.

>>> "ab" & _tail .~ "cde""acde"

>>> [] & _tail .~ [1,2][]

>>> [1,2,3,4,5] & _tail % traversed %~ (*10)[1,20,30,40,50]

>>> [1,2] & _tail .~ [3,4,5][1,3,4,5]

>>> [] & _tail .~ [1,2][]

>>> "abc" ^? _tailJust "bc"

>>> "hello" ^? _tailJust "ello"

>>> "" ^? _tailNothing

cons an element onto a container.

>>> cons 'a' """a"

>>> cons 'a' "bc""abc"

snoc an element onto the end of a container.

>>> snoc "hello" '!'"hello!"

Attempt to extract the left-most element from a container, and a version of the container without that element.

>>> uncons []Nothing

>>> uncons [1, 2, 3]Just (1,[2,3])

Attempt to extract the right-most element from a container, and a version of the container without that element.

>>> unsnoc "hello!"Just ("hello",'!')

>>> unsnoc ""Nothing

snoc an element onto the end of a container.

This is an infix alias for snoc.

>>> "" |> 'a'"a"

>>> "bc" |> 'a'"bca"

Pattern synonym for matching on any type with an AsEmpty instance.

>>> case Nothing of { Empty -> True; _ -> False }True

Returns True if every target of a Fold satisfies a predicate.

>>> allOf each (>=3) (4,5)True>>> allOf folded (>=2) [1..10]False

all ≡ allOf folded

Returns True if every target of a Fold is True.

>>> andOf each (True, False)False>>> andOf each (True, True)True

and ≡ andOf folded

Returns True if any target of a Fold satisfies a predicate.

>>> anyOf each (=='x') ('x','y')True

The sum of a collection of actions.

>>> asumOf each ("hello","world")"helloworld"

>>> asumOf each (Nothing, Just "hello", Nothing)Just "hello"

asum ≡ asumOf folded

This allows you to traverse the elements of a Fold in the opposite order.

Given a Fold that knows how to locate immediate children, fold all of the transitive descendants of a node, including itself.

Does the element occur anywhere within a given Fold of the structure?

>>> elemOf each "hello" ("hello","world")True

elem ≡ elemOf folded

Try the first Fold. If it returns no entries, try the second one.

>>> toListOf (ix 1 `failing` ix 0) [4,7][7]>>> toListOf (ix 1 `failing` ix 0) [4][4]

The findMOf function takes a Fold, a monadic predicate and a structure and returns in the monad the leftmost element of the structure matching the predicate, or Nothing if there is no such element.

>>> findMOf each (\x -> print ("Checking " ++ show x) >> return (even x)) (1,3,4,6)"Checking 1""Checking 3""Checking 4"Just 4

>>> findMOf each (\x -> print ("Checking " ++ show x) >> return (even x)) (1,3,5,7)"Checking 1""Checking 3""Checking 5""Checking 7"Nothing

findMOf folded :: (Monad m, Foldable f) => (a -> m Bool) -> f a -> m (Maybe a)

The findOf function takes a Fold, a predicate and a structure and returns the leftmost element of the structure matching the predicate, or Nothing if there is no such element.

>>> findOf each even (1,3,4,6)Just 4

>>> findOf folded even [1,3,5,7]Nothing

find ≡ findOf folded

Fold via embedding into a monoid.

Combine the results of a fold using a monoid.

Obtain a Fold by lifting traverse_ like function.

foldVL . traverseOf_ ≡ id
traverseOf_ . foldVL ≡ id

Fold via the Foldable class.

Obtain a Fold by lifting an operation that returns a Foldable result.

This can be useful to lift operations from Data.List and elsewhere into a Fold.

>>> toListOf (folding (drop 1)) [1,2,3,4][2,3,4]

Fold left-associatively, and strictly.

Fold right-associatively.

Obtain a Fold by lifting foldr like function.

>>> toListOf (foldring foldr) [1,2,3,4][1,2,3,4]

A version of traverseOf_ with the arguments flipped.

Check to see if this optic matches 1 or more entries.

>>> has _Left (Left 12)True

>>> has _Right (Left 12)False

This will always return True for a Lens or Getter.

>>> has _1 ("hello","world")True

Check to see if this Fold or Traversal has no matches.

>>> hasn't _Left (Right 12)True

>>> hasn't _Left (Left 12)False

Retrieve the first entry of a Fold.

>>> headOf folded [1..10]Just 1

>>> headOf each (1,2)Just 1

Retrieve the last entry of a Fold.

>>> lastOf folded [1..10]Just 10

>>> lastOf each (1,2)Just 2

Calculate the number of targets there are for a Fold in a given container.

Note: This can be rather inefficient for large containers and just like length, this will not terminate for infinite folds.

length ≡ lengthOf folded

>>> lengthOf _1 ("hello",())1

>>> lengthOf folded [1..10]10

>>> lengthOf (folded % folded) [[1,2],[3,4],[5,6]]6

The lookupOf function takes a Fold, a key, and a structure containing key/value pairs. It returns the first value corresponding to the given key. This function generalizes lookup to work on an arbitrary Fold instead of lists.

>>> lookupOf folded 4 [(2, 'a'), (4, 'b'), (4, 'c')]Just 'b'

>>> lookupOf folded 2 [(2, 'a'), (4, 'b'), (4, 'c')]Just 'a'

Obtain the maximum element (if any) targeted by a Fold according to a user supplied Ordering.

>>> maximumByOf folded (compare `on` length) ["mustard","relish","ham"]Just "mustard"

In the interest of efficiency, This operation has semantics more strict than strictly necessary.

maximumBy cmp ≡ fromMaybe (error "empty") . maximumByOf folded cmp

Obtain the maximum element (if any) targeted by a Fold safely.

Note: maximumOf on a valid Iso, Lens or Getter will always return Just a value.

>>> maximumOf folded [1..10]Just 10

>>> maximumOf folded []Nothing

>>> maximumOf (folded % filtered even) [1,4,3,6,7,9,2]Just 6

maximum ≡ fromMaybe (error "empty") . maximumOf folded

In the interest of efficiency, This operation has semantics more strict than strictly necessary. \o -> getMax . foldMapOf o Max has lazier semantics but could leak memory.

Obtain the minimum element (if any) targeted by a Fold according to a user supplied Ordering.

In the interest of efficiency, This operation has semantics more strict than strictly necessary.

>>> minimumByOf folded (compare `on` length) ["mustard","relish","ham"]Just "ham"

minimumBy cmp ≡ fromMaybe (error "empty") . minimumByOf folded cmp

Obtain the minimum element (if any) targeted by a Fold safely.

Note: minimumOf on a valid Iso, Lens or Getter will always return Just a value.

>>> minimumOf folded [1..10]Just 1

>>> minimumOf folded []Nothing

>>> minimumOf (folded % filtered even) [1,4,3,6,7,9,2]Just 2

minimum ≡ fromMaybe (error "empty") . minimumOf folded

In the interest of efficiency, This operation has semantics more strict than strictly necessary. \o -> getMin . foldMapOf o Min has lazier semantics but could leak memory.

The sum of a collection of actions.

>>> msumOf each ("hello","world")"helloworld"

>>> msumOf each (Nothing, Just "hello", Nothing)Just "hello"

msum ≡ msumOf folded

Returns True only if no targets of a Fold satisfy a predicate.

>>> noneOf each (not . isn't _Nothing) (Just 3, Just 4, Just 5)True>>> noneOf (folded % folded) (<10) [[13,99,20],[3,71,42]]False

Does the element not occur anywhere within a given Fold of the structure?

>>> notElemOf each 'd' ('a','b','c')True

>>> notElemOf each 'a' ('a','b','c')False

notElem ≡ notElemOf folded

Returns True if any target of a Fold is True.

>>> orOf each (True, False)True>>> orOf each (False, False)False

or ≡ orOf folded

Perform a fold-like computation on each value, technically a paramorphism.

Convert a fold to an AffineFold that visits the first element of the original fold.

For the traversal version see singular.

Calculate the Product of every number targeted by a Fold.

>>> productOf each (4,5)20>>> productOf folded [1,2,3,4,5]120

product ≡ productOf folded

This operation may be more strict than you would expect. If you want a lazier version use \o -> getProduct . foldMapOf o Product.

Evaluate each action in a structure observed by a Fold from left to right, ignoring the results.

sequenceA_ ≡ sequenceOf_ folded

>>> sequenceOf_ each (putStrLn "hello",putStrLn "world")helloworld

Calculate the Sum of every number targeted by a Fold.

>>> sumOf each (5,6)11>>> sumOf folded [1,2,3,4]10>>> sumOf (folded % each) [(1,2),(3,4)]10

sum ≡ sumOf folded

This operation may be more strict than you would expect. If you want a lazier version use \o -> getSum . foldMapOf o Sum

Return entries of the first Fold, then the second one.

>>> toListOf (_1 % ix 0 `summing` _2 % ix 1) ([1,2], [4,7,1])[1,7]

For the traversal version see adjoin.

Fold to a list.

>>> toListOf (_1 % folded % _Right) ([Right 'h', Left 5, Right 'i'], "bye")"hi"

Traverse over all of the targets of a Fold, computing an Applicative-based answer, but unlike traverseOf do not construct a new structure. traverseOf_ generalizes traverse_ to work over any Fold.

>>> traverseOf_ each putStrLn ("hello","world")helloworld

traverse_ ≡ traverseOf_ folded

Build a Fold that unfolds its values from a seed.

Prelude.unfoldr ≡ toListOf . unfolded

>>> toListOf (unfolded $ \b -> if b == 0 then Nothing else Just (b, b - 1)) 10[10,9,8,7,6,5,4,3,2,1]

Given a Fold that knows how to locate immediate children, retrieve all of the transitive descendants of a node, including itself.

Build a getter from a function.

View the value pointed to by a getter.

If you want to view a type-modifying optic that is insufficiently polymorphic to be type-preserving, use getting.

View the function of the value pointed to by a getter.

Compose two indexed optics and drop indices of the left one. (If you want to compose a non-indexed and an indexed optic, you can just use (%).)

>>> itoListOf (ifolded %> ifolded) ["foo", "bar"][(0,'f'),(1,'o'),(2,'o'),(0,'b'),(1,'a'),(2,'r')]

Compose two indexed optics and drop indices of the right one. (If you want to compose an indexed and a non-indexed optic, you can just use (%).)

>>> itoListOf (ifolded <% ifolded) ["foo", "bar"][(0,'f'),(0,'o'),(0,'o'),(1,'b'),(1,'a'),(1,'r')]

Compose two indexed optics. Their indices are composed as a pair.

>>> itoListOf (ifolded <%> ifolded) ["foo", "bar"][((0,0),'f'),((0,1),'o'),((0,2),'o'),((1,0),'b'),((1,1),'a'),((1,2),'r')]

Flatten indices obtained from two indexed optics.

>>> itoListOf (ifolded % ifolded %& icompose (,)) ["foo","bar"][((0,0),'f'),((0,1),'o'),((0,2),'o'),((1,0),'b'),((1,1),'a'),((1,2),'r')]

Flatten indices obtained from three indexed optics.

>>> itoListOf (ifolded % ifolded % ifolded %& icompose3 (,,)) [["foo","bar"],["xyz"]][((0,0,0),'f'),((0,0,1),'o'),((0,0,2),'o'),((0,1,0),'b'),((0,1,1),'a'),((0,1,2),'r'),((1,0,0),'x'),((1,0,1),'y'),((1,0,2),'z')]

Flatten indices obtained from four indexed optics.

Flatten indices obtained from five indexed optics.

Flatten indices obtained from arbitrary number of indexed optics.

Remap the index.

>>> itoListOf (reindexed succ ifolded) "foo"[(1,'f'),(2,'o'),(3,'o')]

>>> itoListOf (ifolded %& reindexed succ) "foo"[(1,'f'),(2,'o'),(3,'o')]

Construct a conjoined indexed optic that provides a separate code path when used without indices. Useful for defining indexed optics that are as efficient as their unindexed equivalents when used without indices.

Note: conjoined f g is well-defined if and only if f ≡ noIx g.

Compose two optics of compatible flavours.

Returns an optic of the appropriate supertype. If either or both optics are indexed, the composition preserves all the indices.

Compose two optics of the same flavour.

Normally you can simply use (%) instead, but this may be useful to help type inference if the type of one of the optics is otherwise under-constrained.

Flipped function application, specialised to optics and binding tightly.

Useful for post-composing optics transformations:

>>> toListOf (ifolded %& ifiltered (\i s -> length s <= i)) ["", "a","abc"]["","a"]

Explicit cast from one optic flavour to another.

The resulting optic kind is given in the first type argument, so you can use TypeApplications to set it. For example

 castOptic @A_Lens o

turns o into a Lens.

This is the identity function, modulo some constraint jiggery-pokery.

anon a p generalizes non a to take any value and a predicate.

anon a ≡ non' . nearly a

This function assumes that p a holds True and generates an isomorphism between Maybe (a | not (p a)) and a.

>>> Map.empty & at "hello" % anon Map.empty Map.null % at "world" ?~ "!!!"fromList [("hello",fromList [("world","!!!")])]

>>> Map.fromList [("hello", Map.fromList [("world","!!!")])] & at "hello" % anon Map.empty Map.null % at "world" .~ NothingfromList []

Based on ala from Conor McBride's work on Epigram.

This version is generalized to accept any Iso, not just a newtype.

>>> au (coerced1 @Sum) foldMap [1,2,3,4]10

You may want to think of this combinator as having the following, simpler type:

au :: Iso s t a b -> ((b -> t) -> e -> s) -> e -> a

Data types that are representationally equal are isomorphic.

>>> view coerced 'x' :: Identity CharIdentity 'x'

Special case of coerced for trivial newtype wrappers.

>>> over (coerced1 @Identity) (++ "bar") (Identity "foo")Identity "foobar"

Type-preserving version of coerced with type parameters rearranged for TypeApplications.

>>> newtype MkInt = MkInt Int deriving Show

>>> over (coercedTo @Int) (*3) (MkInt 2)MkInt 6

The canonical isomorphism for currying and uncurrying a function.

curried = iso curry uncurry

>>> view curried fst 3 43

Capture type constraints as an isomorphism.

Note: This is the identity optic:

>>> :t view equalityview equality :: a -> a

The isomorphism for flipping a function.

>>> (view flipped (,)) 1 2(2,1)

Given a function that is its own inverse, this gives you an Iso using it in both directions.

involuted ≡ join iso

>>> "live" ^. involuted reverse"evil"

>>> "live" & involuted reverse %~ ('d':)"lived"

Build an iso from a pair of inverse functions.

If you want to build an Iso from the van Laarhoven representation, use isoVL from the optics-vl package.

If v is an element of a type a, and a' is a sans the element v, then non v is an isomorphism from Maybe a' to a.

non ≡ non' . only

Keep in mind this is only a real isomorphism if you treat the domain as being Maybe (a sans v).

This is practically quite useful when you want to have a Data.Map.Map where all the entries should have non-zero values.

>>> Map.fromList [("hello",1)] & at "hello" % non 0 %~ (+2)fromList [("hello",3)]

>>> Map.fromList [("hello",1)] & at "hello" % non 0 %~ (subtract 1)fromList []

>>> Map.fromList [("hello",1)] ^. at "hello" % non 01

>>> Map.fromList [] ^. at "hello" % non 00

This combinator is also particularly useful when working with nested maps.

e.g. When you want to create the nested Data.Map.Map when it is missing:

>>> Map.empty & at "hello" % non Map.empty % at "world" ?~ "!!!"fromList [("hello",fromList [("world","!!!")])]

and when have deleting the last entry from the nested Data.Map.Map mean that we should delete its entry from the surrounding one:

>>> Map.fromList [("hello", Map.fromList [("world","!!!")])] & at "hello" % non Map.empty % at "world" .~ NothingfromList []

It can also be used in reverse to exclude a given value:

>>> non 0 # rem 10 4Just 2

>>> non 0 # rem 10 5Nothing

non' p generalizes non (p # ()) to take any unit Prism

This function generates an isomorphism between Maybe (a | isn't p a) and a.

>>> Map.singleton "hello" Map.empty & at "hello" % non' _Empty % at "world" ?~ "!!!"fromList [("hello",fromList [("world","!!!")])]

>>> Map.fromList [("hello", Map.fromList [("world","!!!")])] & at "hello" % non' _Empty % at "world" .~ NothingfromList []

Proof of reflexivity.

The canonical isomorphism for uncurrying and currying a function.

uncurried = iso uncurry curry

uncurried = re curried

>>> (view uncurried (+)) (1,2)3

The opposite of working over a Setter is working under an isomorphism.

under ≡ over . re

Extract the two components of an isomorphism.

Obtain a potentially empty IxAffineFold by taking the element from another AffineFold and using it as an index.

Try the first IxAffineFold. If it returns no entry, try the second one.

Obtain an IxAffineFold by lifting itraverse_ like function.

aifoldVL . iatraverseOf_ ≡ id
aitraverseOf_ . iafoldVL ≡ id

Create an IxAffineFold from a partial function.

Traverse over the target of an IxAffineFold, computing a Functor-based answer, but unlike iatraverseOf do not construct a new structure.

Retrieve the value along with its index targeted by an IxAffineFold.

Retrieve a function of the value and its index targeted by an IxAffineFold.

Try the first IxAffineTraversal. If it does not return a entry, try the second one.

>>> iover (ifst `iadisjoin` isnd) (++) ("foo", "bar")("barfoo","bar")

>>> iover (ignored `iadisjoin` isnd) (++) ("foo", "bar")("foo","foobar")

Build an indexed affine traversal from a matcher and an updater.

If you want to build an IxAffineTraversal from the van Laarhoven representation, use iatraversalVL.

Build an indexed affine traversal from the van Laarhoven representation.

Traverse over the target of an IxAffineTraversal and compute a Functor-based answer.

This is the trivial empty IxAffineTraversal, i.e. the optic that targets no substructures.

This is the identity element when a Fold, AffineFold, IxFold, IxAffineFold, Traversal or IxTraversal is viewed as a monoid.

>>> 6 & ignored %~ absurd6

Obtain a potentially empty IxAffineTraversal by taking the element from another AffineFold and using it as an index.

• - Note: This is not a legal IxTraversal, unless you are very careful not to invalidate the predicate on the target (see unsafeFiltered for more details).

Return whether or not all elements viewed through an IxFold satisfy a predicate, with access to the i.

When you don't need access to the index then allOf is more flexible in what it accepts.

allOf o ≡ iallOf o . const

Return whether or not any element viewed through an IxFold satisfies a predicate, with access to the i.

When you don't need access to the index then anyOf is more flexible in what it accepts.

anyOf o ≡ ianyOf o . const

This allows you to traverse the elements of an IxFold in the opposite order.

Try the first IxFold. If it returns no entries, try the second one.

>>> itoListOf (_1 % ifolded `ifailing` _2 % ifolded) (["a"], ["b","c"])[(0,"a")]>>> itoListOf (_1 % ifolded `ifailing` _2 % ifolded) ([], ["b","c"])[(0,"b"),(1,"c")]

Filter results of an IxFold that don't satisfy a predicate.

>>> toListOf (ifolded %& ifiltered (>)) [3,2,1,0][1,0]

The ifindMOf function takes an IxFold, a monadic predicate that is also supplied the index, a structure and returns in the monad the left-most element of the structure matching the predicate, or Nothing if there is no such element.

When you don't need access to the index then findMOf is more flexible in what it accepts.

The ifindOf function takes an IxFold, a predicate that is also supplied the index, a structure and returns the left-most element of the structure along with its index matching the predicate, or Nothing if there is no such element.

When you don't need access to the index then findOf is more flexible in what it accepts.

Fold with index via embedding into a monoid.

Obtain an indexed fold by lifting itraverse_ like function.

ifoldVL . itraverseOf_ ≡ id
itraverseOf_ . ifoldVL ≡ id

Indexed fold via FoldableWithIndex class.

Obtain an IxFold by lifting an operation that returns a FoldableWithIndex result.

This can be useful to lift operations from Data.List and elsewhere into an IxFold.

>>> itoListOf (ifolding words) "how are you"[(0,"how"),(1,"are"),(2,"you")]

Fold with index left-associatively, and strictly.

Fold with index right-associatively.

Obtain an IxFold by lifting ifoldr like function.

>>> itoListOf (ifoldring ifoldr) "hello"[(0,'h'),(1,'e'),(2,'l'),(3,'l'),(4,'o')]

A version of itraverseOf_ with the arguments flipped.

Retrieve the first entry of an IxFold along with its index.

>>> iheadOf ifolded [1..10]Just (0,1)

Retrieve the last entry of an IxFold along with its index.

>>> ilastOf ifolded [1..10]Just (9,10)

Return whether or not none of the elements viewed through an IxFold satisfy a predicate, with access to the i.

When you don't need access to the index then noneOf is more flexible in what it accepts.

noneOf o ≡ inoneOf o . const

Convert an indexed fold to an IxAffineFold that visits the first element of the original fold.

For the traversal version see isingular.

Return entries of the first IxFold, then the second one.

>>> itoListOf (ifolded `isumming` ibackwards_ ifolded) ["a","b"][(0,"a"),(1,"b"),(1,"b"),(0,"a")]

For the traversal version see iadjoin.

Fold with index to a list.

>>> itoListOf (folded % ifolded) ["abc", "def"][(0,'a'),(1,'b'),(2,'c'),(0,'d'),(1,'e'),(2,'f')]

Note: currently indexed optics can be used as non-indexed.

>>> toListOf (folded % ifolded) ["abc", "def"]"abcdef"

Traverse over all of the targets of an IxFold, computing an Applicative-based answer, but unlike itraverseOf do not construct a new structure.

>>> itraverseOf_ each (curry print) ("hello","world")(0,"hello")(1,"world")

Build an indexed getter from a function.

>>> iview (ito id) ('i', 'x')('i','x')

View the value pointed to by an indexed getter.

View the function of the value pointed to by an indexed getter.

Use a value itself as its own index. This is essentially an indexed version of equality.

Focus on both sides of an Either.

There is an indexed field for every type in the Void.

>>> set (mapped % devoid) 1 [][]

>>> over (_Just % devoid) abs NothingNothing

Indexed _1 with other half of a pair as an index.

See isnd for examples.

Build an indexed lens from a getter and a setter.

If you want to build an IxLens from the van Laarhoven representation, use ilensVL.

Build an indexed lens from the van Laarhoven representation.

Indexed _2 with other half of a pair as an index. Specialized version of itraversed to pairs, which can be IxLens.

>>> iview isnd ('a', True)('a',True)

That is not possible with itraversed, because it is an IxTraversal.

>>> :t itraversed :: IxTraversal i (i, a) (i, b) a bitraversed :: IxTraversal i (i, a) (i, b) a b  :: IxTraversal i (i, a) (i, b) a b

Convert an indexed lens to its van Laarhoven representation.

Work with an indexed lens in the van Laarhoven representation.

Indexed setter via the FunctorWithIndex class.

iover imapped ≡ imap

Apply an indexed setter as a modifier.

Apply an indexed setter as a modifier, strictly.

Apply an indexed setter.

iset o f ≡ iover o (i _ -> f i)

Apply an indexed setter, strictly.

Build an indexed setter from a function to modify the element(s).

Traverse the nth element of a Traversable container.

element ≡ elementOf traversed

Traverse the nth element of a Traversal if it exists.

Traverse elements of a Traversable container where their ordinal positions match a predicate.

elements ≡ elementsOf traverse

Traverse selected elements of a Traversal where their ordinal positions match a predicate.

Combine two disjoint indexed traversals into one.

>>> iover (_1 % itraversed `iadjoin` _2 % itraversed) (+) ([0, 0, 0], (3, 5))([0,1,2],(3,8))

Note: if the argument traversals are not disjoint, the result will not respect the IxTraversal laws, because it will visit the same element multiple times. See section 7 of Understanding Idiomatic Traversals Backwards and Forwards by Bird et al. for why this is illegal.

>>> iview (ipartsOf (each `iadjoin` each)) ("x","y")([0,1,0,1],["x","y","x","y"])>>> iset (ipartsOf (each `iadjoin` each)) (const ["a","b","c","d"]) ("x","y")("c","d")

For the IxFold version see isumming.

This allows you to traverse the elements of an indexed traversal in the opposite order.

Try the first IxTraversal. If it returns no entries, try the second one.

>>> iover (_1 % itraversed `idisjoin` _2 % itraversed) (+) ([0, 0, 0], (3, 5))([0,1,2],(3,5))

>>> iover (ignored `idisjoin` _2 % itraversed) (+) ([0, 0, 0], (3, 5))([0,0,0],(3,8))

Try to map a function which uses the index over this IxTraversal, returning Nothing if the IxTraversal has no targets.

Version of ifailover strict in the application of the function.

A version of itraverseOf with the arguments flipped.