Optics.Indexed

Class for optic kinds that can have indices.

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 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')]

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')]

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')]

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.

Type synonym for an indexed affine fold.

Tag for an affine fold.

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.

Type synonym for a type-modifying indexed affine traversal.

Tag for an affine traversal.

Type synonym for a type-preserving indexed affine traversal.

Type synonym for a type-modifying van Laarhoven indexed affine traversal.

Note: this isn't exactly van Laarhoven representation as there is no Pointed class (which would be a superclass of Applicative that contains pure but not <*>). You can interpret the first argument as a dictionary of Pointed that supplies the point function (i.e. the implementation of pure).

Type synonym for a type-preserving van Laarhoven indexed affine traversal.

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).

Type synonym for an indexed fold.

A container that supports folding with an additional index.

Tag for a fold.

Fold with index via embedding into a monoid.

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.

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")

Type synonym for an indexed getter.

Tag for a getter.

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.

Type synonym for a type-modifying indexed lens.

Tag for a lens.

Type synonym for a type-preserving indexed lens.

Type synonym for a type-modifying van Laarhoven indexed lens.

Type synonym for a type-preserving van Laarhoven indexed lens.

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.

Type synonym for a type-modifying indexed setter.

A Functor with an additional index.

Instances must satisfy a modified form of the Functor laws:

imap f . imap g ≡ imap (\i -> f i . g i)
imap (\_ a -> a) ≡ id

Tag for a setter.

Type synonym for a type-preserving indexed setter.

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).

Type synonym for a type-modifying indexed traversal.

A Traversable with an additional index.

An instance must satisfy a (modified) form of the Traversable laws:

itraverse (const Identity) ≡ Identity
fmap (itraverse f) . itraverse g ≡ getCompose . itraverse (\i -> Compose . fmap (f i) . g i)

Tag for a traversal.

Type synonym for a type-preserving indexed traversal.

Map each element of a structure targeted by an IxTraversal (supplying the index), evaluate these actions from left to right, and collect the results.

This yields the van Laarhoven representation of an indexed traversal.

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

Type synonym for a type-modifying van Laarhoven indexed traversal.

Type synonym for a type-preserving van Laarhoven indexed traversal.

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 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.

Generalizes Data.Traversable.mapAccumL to an arbitrary IxTraversal.

imapAccumLOf accumulates state from left to right.

mapAccumLOf o ≡ imapAccumLOf o . const

Generalizes Data.Traversable.mapAccumR to an arbitrary IxTraversal.

imapAccumROf accumulates state from right to left.

mapAccumROf o ≡ imapAccumROf o . const

Filter results of an IxTraversal that don't satisfy a predicate on the indices.

>>> toListOf (itraversed %& indices even) "foobar""foa"

An indexed version of partsOf that receives the entire list of indices as its indices.

This permits the use of scanl1 over an arbitrary IxTraversal.

This permits the use of scanr1 over an arbitrary IxTraversal.

Convert an indexed traversal to an IxAffineTraversal that visits the first element of the original traversal.

For the fold version see ipre.

>>> [1,2,3] & iover (isingular itraversed) (-)[-1,2,3]

Build an indexed traversal from the van Laarhoven representation.

itraversalVL . itraverseOf ≡ id
itraverseOf . itraversalVL ≡ id

Indexed traversal via the TraversableWithIndex class.

itraverseOf itraversed ≡ itraverse

>>> iover (itraversed <%> itraversed) (,) ["ab", "cd"][[((0,0),'a'),((0,1),'b')],[((1,0),'c'),((1,1),'d')]]

A Functor with an additional index.

Instances must satisfy a modified form of the Functor laws:

imap f . imap g ≡ imap (\i -> f i . g i)
imap (\_ a -> a) ≡ id