Control.Lens

This package provides lens families, setters, getters, traversals and folds that can all be composed automatically with each other (and other lenses from other van Laarhoven lens libraries) using (.) from Prelude, while reducing the complexity of the API.

Lenses

type Lens a b c d = forall f. Functor f => (c -> f d) -> a -> f b

A Lens is actually a lens family as described in http://comonad.com/reader/2012/mirrored-lenses/.

With great power comes great responsibility and a Lens is subject to the lens laws:

 view l (set l b a)  = b
 set l (view l a) a  = a
 set l c (set l b a) = set l c a

These laws are strong enough that the 4 type parameters of a Lens cannot vary fully independently. For more on how they interact, read the Why is it a Lens Family? section of http://comonad.com/reader/2012/mirrored-lenses/.

Every Lens can be used directly as a Getter, Setter, Fold or Traversal.

 identity :: Lens (Identity a) (Identity b) a b
 identity f (Identity a) = Identity <$> f a

Simple Lenses

type Simple f a b = f a a b b

A Simple Lens, Simple Setter, or Simple Traversal can be used instead of a Lens Setter or Traversal whenever the type variables don't change upon setting a value.

 imaginary :: Simple Lens (Complex a) a
 imaginary f (e :+ i) = (e :+) <$> f i

 traverseHead :: Simple Traversal [a] a

Constructing Lenses

lens :: (a -> c) -> (d -> a -> b) -> Lens a b c d

Build a Lens from a getter and a setter.

 lens :: Functor f => (a -> c) -> (d -> a -> b) -> (c -> f d) -> a -> f b

iso :: (a -> c) -> (d -> b) -> Lens a b c d

Built a Lens from an isomorphism family

 iso :: Functor f => (a -> c) -> (d -> b) -> (c -> f d) -> a -> f b

clone :: Functor f => ((c -> IndexedStore c d d) -> a -> IndexedStore c d b) -> (c -> f d) -> a -> f b

Cloning a Lens is one way to make sure you arent given something weaker, such as a Traversal and can be used as a way to pass around lenses that have to be monomorphic in f.

Getters

type Getter a b c d = forall z. (c -> Const z d) -> a -> Const z b

A Getter describes how to retrieve a single value in a way that can be composed with other lens-like constructions.

Unlike a Lens a Getter is read-only. Since a Getter cannot be used to write back there are no lens laws that can be applied to it.

Moreover, a Getter can be used directly as a Fold, since it just ignores the Monoid.

In practice the b and d are left dangling and unused, and as such is no real point in using a Simple Getter.

to :: (a -> c) -> Getter a b c d

Build a Getter

Getting Values

view :: ((c -> Const c d) -> a -> Const c b) -> a -> c

View the value pointed to by a Getter or Lens or the result of folding over all the results of a Fold or Traversal that points at a monoidal values.

It may be useful to think of view as having these more restrictive signatures:

 view :: Lens a b c d -> a -> c
 view :: Getter a b c d -> a -> c
 view :: Monoid m => Fold a b m d -> a -> m
 view :: Monoid m => Traversal a b m d -> a -> m

views :: ((c -> Const m d) -> a -> Const m b) -> (c -> m) -> a -> m

View the value of a Getter, Lens or the result of folding over the result of mapping the targets of a Fold or Traversal.

It may be useful to think of views as having these more restrictive signatures:

 views :: Getter a b c d -> (c -> d) -> a -> d
 views :: Lens a b c d -> (c -> d) -> a -> d
 views :: Monoid m => Fold a b c d -> (c -> m) -> a -> m
 views :: Monoid m => Traversal a b c d -> (c -> m) -> a -> m

(^.) :: a -> ((c -> Const c d) -> a -> Const c b) -> c

View the value pointed to by a Getter or Lens or the result of folding over all the results of a Fold or Traversal that points at a monoidal values.

This is the same operation as view with the arguments flipped.

The fixity and semantics are such that subsequent field accesses can be performed with (Prelude..)

 ghci> ((0, 1 :+ 2), 3)^._1._2.to magnitude
 2.23606797749979

(^$) :: ((c -> Const c d) -> a -> Const c b) -> a -> c

View the value pointed to by a Getter or Lens or the result of folding over all the results of a Fold or Traversal that points at a monoidal values.

This is the same operation as view, only infix.

Setters

type Setter a b c d = (c -> Identity d) -> a -> Identity b

The only Lens-like law that applies to a Setter l is that

 set l c (set l b a) = set l c a

You can't view a Setter in general, so the other two laws do not apply.

You can compose a Setter with a Lens or a Traversal using (.) from the Prelude but the result is always only a Setter.

sets :: ((c -> d) -> a -> b) -> Setter a b c d

Build a Setter

 sets . adjust = id
 adjust . sets = id

mapped :: Functor f => Setter (f a) (f b) a b

This setter can be used to map over all of the values in a container.

Setting Values

adjust :: Setter a b c d -> (c -> d) -> a -> b

Modify the target of a Lens or all the targets of a Setter or Traversal with a function.

 fmap = adjust traverse

Two useful free theorems hold for this type:

 sets . adjust = id
 adjust . sets = id

 adjust :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b

set :: Setter a b c d -> d -> a -> b

Replace the target of a Lens or all of the targets of a Setter or Traversal with a constant value.

 (<$) = set traverse

 set :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b

(^%=) :: Setter a b c d -> (c -> d) -> a -> b

Modifies the target of a Lens or all of the targets of a Setter or Traversal with a user supplied function.

This is an infix version of adjust

 fmap f = traverse ^%= f

 (^%=) :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b

(^=) :: Setter a b c d -> d -> a -> b

Replace the target of a Lens or all of the targets of a Setter or Traversal with a constant value.

This is an infix version of set

 f <$ a = traverse ^= f $ a

 (^=) :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b

(^+=) :: Num c => Setter a b c c -> c -> a -> b

Increment the target(s) of a numerically valued Lens, Setter' or Traversal

 ghci> _1 ^+= 1 $ (1,2)
 (2,2)

 (^+=) :: Num c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b

(^-=) :: Num c => Setter a b c c -> c -> a -> b

Decrement the target(s) of a numerically valued Lens, Setter or Traversal

 ghci> _1 ^-= 2 $ (1,2)
 (-1,2)

 (^-=) :: ((c -> Identity c) -> a -> Identity b) -> c -> a -> b

(^*=) :: Num c => Setter a b c c -> c -> a -> b

Multiply the target(s) of a numerically valued Lens, Setter or Traversal

 ghci> _2 ^*= 4 $ (1,2)
 (1,8)

 (^*=) :: Num c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b

(^/=) :: Fractional c => Setter a b c c -> c -> a -> b

Divide the target(s) of a numerically valued Lens, Setter or Traversal

 (^/=) :: Fractional c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b

(^||=) :: Setter a b Bool Bool -> Bool -> a -> b

Logically || the target(s) of a Bool-valued Lens or Setter

 (^||=):: ((Bool -> Identity Bool) -> a -> Identity b) -> Bool -> a -> b

(^&&=) :: Setter a b Bool Bool -> Bool -> a -> b

Logically && the target(s) of a Bool-valued Lens or Setter

(^&&=) :: ((Bool -> Identity Bool) -> a -> Identity b) -> Bool -> a -> b

(^|=) :: Bits c => Setter a b c c -> c -> a -> b

Bitwise .|. the target(s) of a Bool-valued Lens or Setter

 (^|=):: Bits c => ((c -> Identity c) -> a -> Identity b) -> Bool -> a -> b

(^&=) :: Bits c => Setter a b c c -> c -> a -> b

Bitwise .&. the target(s) of a Bool-valued Lens or Setter

 (^&=) :: Bits c => ((b -> Identity b) -> a -> Identity a) -> c -> a -> b

Manipulating State

access :: MonadState a m => ((c -> Const c d) -> a -> Const c b) -> m c

Access the target of a Lens or Getter in the current state, or access a summary of a Fold or Traversal that points to a monoidal value.

(%=) :: MonadState a m => Setter a a c d -> (c -> d) -> m ()

Map over the target of a Lens or all of the targets of a Setter or 'Traversal in our monadic state.

(~=) :: MonadState a m => Setter a a c d -> d -> m ()

Replace the target of a Lens or all of the targets of a Setter or Traversal in our monadic state with a new value, irrespective of the old.

(+=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by adding a value

(-=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by subtracting a value

(*=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by multiplying by value

(//=) :: (MonadState a m, Fractional b) => Simple Setter a b -> b -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by dividing by a value

(||=) :: MonadState a m => Simple Setter a Bool -> Bool -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by taking their logical || with a value

(&&=) :: MonadState a m => Simple Setter a Bool -> Bool -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by taking their logical && with a value

(|=) :: (MonadState a m, Bits b) => Simple Setter a b -> b -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by computing its bitwise .|. with another value.

(&=) :: (MonadState a m, Bits b) => Simple Setter a b -> b -> m ()

Modify the target(s) of a Simple Lens, Setter or Traversal by computing its bitwise .&. with another value.

(%%=) :: MonadState a m => ((b -> (c, b)) -> a -> (c, a)) -> (b -> (c, b)) -> m c

Modify the target of a Lens in the current state returning some extra information of c or modify all targets of a Traversal in the current state, extracting extra information of type c and return a monoidal summary of the changes.

It may be useful to think of '(%%=)', instead, as having either of the following more restricted type signatures:

 (%%=) :: MonadState a m => Simple Lens a b -> (b -> (c, b) -> m c
 (%%=) :: (MonadState a m, Monoid c) => Simple Traversal a b -> (b -> (c, b) -> m c

class Focus st where

This class allows us to use focus on a number of different monad transformers.

Methods

focus :: Monad m => ((b -> Focusing m c b) -> a -> Focusing m c a) -> st b m c -> st a m c

Use a lens to lift an operation with simpler context into a larger context

This is commonly used to lift actions in a simpler state monad into a state monad with a larger state type.

Instances

Focus ReaderT

We can focus Reader environments, too!

Focus StateT

Focus StateT

Common Lenses

_1 :: Lens (a, c) (b, c) a b

This is a lens that can change the value (and type) of the first field of a pair.

 ghci> (1,2)^._1
 1

 ghci> _1 ^= "hello" $ (1,2)
 ("hello",2)

 _1 :: Functor f => (a -> f b) -> (a,c) -> f (a,c)

_2 :: Lens (c, a) (c, b) a b

As _1, but for the second field of a pair.

 anyOf _2 :: (c -> Bool) -> (a, c) -> Bool
 traverse._2 :: (Applicative f, Traversable t) => (a -> f b) -> t (c, a) -> f (t (c, b))
 foldMapOf (traverse._2) :: (Traversable t, Monoid m) => (c -> m) -> t (b, c) -> m

 _2 :: Functor f => (a -> f b) -> (c,a) -> f (c,b)

valueAt :: Ord k => k -> Simple Lens (Map k v) (Maybe v)

This Lens can be used to read, write or delete the value associated with a key in a Map.

 ghci> Map.fromList [("hello",12)] ^. valueAt "hello"
 Just 12

 valueAt :: Ord k => k -> (Maybe v -> f (Maybe v)) -> Map k v -> f (Map k v)

valueAtInt :: Int -> Simple Lens (IntMap v) (Maybe v)

This Lens can be used to read, write or delete a member of an IntMap.

 ghci> IntMap.fromList [(1,"hello")]  ^. valueAtInt 1
 Just "hello"

 ghci> valueAtInt 2 ^= "goodbye" $ IntMap.fromList [(1,"hello")]
 fromList [(1,"hello"),(2,"goodbye")]

 valueAtInt :: Int -> (Maybe v -> f (Maybe v)) -> IntMap v -> f (IntMap v)

bitAt :: Bits b => Int -> Simple Lens b Bool

This lens can be used to access the value of the nth bit in a number.

bitsAt n is only a legal Lens into b if 0 <= n < bitSize (undefined :: b)

contains :: Ord k => k -> Simple Lens (Set k) Bool

This Lens can be used to read, write or delete a member of a Set

 ghci> contains 3 ^= False $ Set.fromList [1,2,3,4]
 fromList [1,2,4]

 contains :: Ord k => k -> (Bool -> f Bool) -> Set k -> f (Set k)

containsInt :: Int -> Simple Lens IntSet Bool

This Lens can be used to read, write or delete a member of an IntSet

 ghci> containsInt 3 ^= False $ IntSet.fromList [1,2,3,4]
 fromList [1,2,4]

 containsInt :: Int -> (Bool -> f Bool) -> IntSet -> f IntSet

identity :: Lens (Identity a) (Identity b) a b

This lens can be used to access the contents of the Identity monad

resultAt :: Eq e => e -> Simple Lens (e -> a) a

This lens can be used to change the result of a function but only where the arguments match the key given.

Folds

type Fold a b c d = forall m. Monoid m => (c -> Const m d) -> a -> Const m b

A Fold describes how to retrieve multiple values in a way that can be composed with other lens-like constructions.

A Fold a b c d provides a structure with operations very similar to those of the Foldable typeclass, see foldMapOf and the other Fold combinators.

By convention, if there exists a foo method that expects a Foldable (f c), then there should be a fooOf method that takes a Fold a b c d and a value of type a.

A Getter is a legal Fold that just ignores the supplied Monoid

Unlike a Traversal a Fold is read-only. Since a Fold cannot be used to write back there are no lens laws that can be applied to it.

In practice the b and d are left dangling and unused, and as such is no real point in a Simple Fold.

Common Folds

folded :: Foldable f => Fold (f c) b c d

Obtain a Fold from any Foldable

folding :: Foldable f => (a -> f c) -> Fold a b c d

Building a Fold

Fold Combinators

foldMapOf :: ((c -> Const m d) -> a -> Const m b) -> (c -> m) -> a -> m

 foldMap = foldMapOf folded

 foldMapOf = views

 foldMapOf ::             Getter a b c d    -> (c -> m) -> a -> m
 foldMapOf ::             Lens a b c d      -> (c -> m) -> a -> m
 foldMapOf :: Monoid m => Fold a b c d      -> (c -> m) -> a -> m
 foldMapOf :: Monoid m => Traversal a b c d -> (c -> m) -> a -> m

foldrOf :: ((c -> Const (Endo e) d) -> a -> Const (Endo e) b) -> (c -> e -> e) -> e -> a -> e

 foldr = foldrOf folded

 foldrOf :: Getter a b c d    -> (c -> e -> e) -> e -> a -> e
 foldrOf :: Lens a b c d      -> (c -> e -> e) -> e -> a -> e
 foldrOf :: Fold a b c d      -> (c -> e -> e) -> e -> a -> e
 foldrOf :: Traversal a b c d -> (c -> e -> e) -> e -> a -> e

foldOf :: ((m -> Const m d) -> a -> Const m b) -> a -> m

 fold = foldOf folded

 foldOf = view

 foldOf ::             Getter a b m d    -> a -> m
 foldOf ::             Lens a b m d      -> a -> m
 foldOf :: Monoid m => Fold a b m d      -> a -> m
 foldOf :: Monoid m => Traversal a b m d -> a -> m

toListOf :: ((c -> Const [c] d) -> a -> Const [c] b) -> a -> [c]

 toList = toListOf folded

 toListOf :: Getter a b c d    -> a -> [c]
 toListOf :: Lens a b c d      -> a -> [c]
 toListOf :: Fold a b c d      -> a -> [c]
 toListOf :: Traversal a b c d -> a -> [c]

anyOf :: ((c -> Const Any d) -> a -> Const Any b) -> (c -> Bool) -> a -> Bool

 any = anyOf folded

 anyOf :: Getter a b c d    -> (c -> Bool) -> a -> Bool
 anyOf :: Lens a b c d      -> (c -> Bool) -> a -> Bool
 anyOf :: Fold a b c d      -> (c -> Bool) -> a -> Bool
 anyOf :: Traversal a b c d -> (c -> Bool) -> a -> Bool

allOf :: ((c -> Const All d) -> a -> Const All b) -> (c -> Bool) -> a -> Bool

 all = allOf folded

 allOf :: Getter a b c d    -> (c -> Bool) -> a -> Bool
 allOf :: Lens a b c d      -> (c -> Bool) -> a -> Bool
 allOf :: Fold a b c d      -> (c -> Bool) -> a -> Bool
 allOf :: Traversal a b c d -> (c -> Bool) -> a -> Bool

andOf :: ((Bool -> Const All d) -> a -> Const All b) -> a -> Bool

 and = andOf folded

 andOf :: Getter a b Bool d   -> a -> Bool
 andOf :: Lens a b Bool d     -> a -> Bool
 andOf :: Fold a b Bool d     -> a -> Bool
 andOf :: Traversl a b Bool d -> a -> Bool

orOf :: ((Bool -> Const Any d) -> a -> Const Any b) -> a -> Bool

 or = orOf folded

 orOf :: Getter a b Bool d    -> a -> Bool
 orOf :: Lens a b Bool d      -> a -> Bool
 orOf :: Fold a b Bool d      -> a -> Bool
 orOf :: Traversal a b Bool d -> a -> Bool

productOf :: ((c -> Const (Product c) d) -> a -> Const (Product c) b) -> a -> c

 product = productOf folded

 productOf ::          Getter a b c d    -> a -> c
 productOf ::          Lens a b c d      -> a -> c
 productOf :: Num c => Fold a b c d      -> a -> c
 productOf :: Num c => Traversal a b c d -> a -> c

sumOf :: ((c -> Const (Sum c) d) -> a -> Const (Sum c) b) -> a -> c

 sum = sumOf folded

 sumOf _1 :: (a, b) -> a
 sumOf (folded._1) :: (Foldable f, Num a) => f (a, b) -> a

 sumOf ::          Getter a b c d    -> a -> c
 sumOf ::          Lens a b c d      -> a -> c
 sumOf :: Num c => Fold a b c d      -> a -> c
 sumOf :: Num c => Traversal a b c d -> a -> c

traverseOf_ :: Functor f => ((c -> Const (Traversed f) d) -> a -> Const (Traversed f) b) -> (c -> f e) -> a -> f ()

When passed a Getter, traverseOf_ can work over a Functor.

When passed a Fold, traverseOf_ requires an Applicative.

 traverse_ = traverseOf_ folded

 traverseOf_ _2 :: Functor f => (c -> f e) -> (c1, c) -> f ()
 traverseOf_ traverseLeft :: Applicative f => (a -> f b) -> Either a c -> f ()

The rather specific signature of traverseOf_ allows it to be used as if the signature was either:

 traverseOf_ :: Functor f     => Getter a b c d    -> (c -> f e) -> a -> f ()
 traverseOf_ :: Functor f     => Lens a b c d      -> (c -> f e) -> a -> f ()
 traverseOf_ :: Applicative f => Fold a b c d      -> (c -> f e) -> a -> f ()
 traverseOf_ :: Applicative f => Traversal a b c d -> (c -> f e) -> a -> f ()

forOf_ :: Functor f => ((c -> Const (Traversed f) d) -> a -> Const (Traversed f) b) -> a -> (c -> f e) -> f ()

 for_ = forOf_ folded

 forOf_ :: Functor f     => Getter a b c d    -> a -> (c -> f e) -> f ()
 forOf_ :: Functor f     => Lens a b c d      -> a -> (c -> f e) -> f ()
 forOf_ :: Applicative f => Fold a b c d      -> a -> (c -> f e) -> f ()
 forOf_ :: Applicative f => Traversal a b c d -> a -> (c -> f e) -> f ()

sequenceAOf_ :: Functor f => ((f () -> Const (Traversed f) d) -> a -> Const (Traversed f) b) -> a -> f ()

 sequenceA_ = sequenceAOf_ folded

 sequenceAOf_ :: Functor f     => Getter a b (f ()) d    -> a -> f ()
 sequenceAOf_ :: Functor f     => Lens a b (f ()) d      -> a -> f ()
 sequenceAOf_ :: Applicative f => Fold a b (f ()) d      -> a -> f ()
 sequenceAOf_ :: Applicative f => Traversal a b (f ()) d -> a -> f ()

mapMOf_ :: Monad m => ((c -> Const (Traversed (WrappedMonad m)) d) -> a -> Const (Traversed (WrappedMonad m)) b) -> (c -> m e) -> a -> m ()

 mapM_ = mapMOf_ folded

 mapMOf_ :: Monad m => Getter a b c d    -> (c -> m e) -> a -> m ()
 mapMOf_ :: Monad m => Lens a b c d      -> (c -> m e) -> a -> m ()
 mapMOf_ :: Monad m => Fold a b c d      -> (c -> m e) -> a -> m ()
 mapMOf_ :: Monad m => Traversal a b c d -> (c -> m e) -> a -> m ()

forMOf_ :: Monad m => ((c -> Const (Traversed (WrappedMonad m)) d) -> a -> Const (Traversed (WrappedMonad m)) b) -> a -> (c -> m e) -> m ()

 forM_ = forMOf_ folded

 forMOf_ :: Monad m => Getter a b c d    -> a -> (c -> m e) -> m ()
 forMOf_ :: Monad m => Lens a b c d      -> a -> (c -> m e) -> m ()
 forMOf_ :: Monad m => Fold a b c d      -> a -> (c -> m e) -> m ()
 forMOf_ :: Monad m => Traversal a b c d -> a -> (c -> m e) -> m ()

sequenceOf_ :: Monad m => ((m c -> Const (Traversed (WrappedMonad m)) d) -> a -> Const (Traversed (WrappedMonad m)) b) -> a -> m ()

 sequence_ = sequenceOf_ folded

 sequenceOf_ :: Monad m => Getter a b (m b) d    -> a -> m ()
 sequenceOf_ :: Monad m => Lens a b (m b) d      -> a -> m ()
 sequenceOf_ :: Monad m => Fold a b (m b) d      -> a -> m ()
 sequenceOf_ :: Monad m => Traversal a b (m b) d -> a -> m ()

asumOf :: Alternative f => ((f c -> Const (Endo (f c)) d) -> a -> Const (Endo (f c)) b) -> a -> f c

The sum of a collection of actions, generalizing concatOf.

 asum = asumOf folded

 asumOf :: Alternative f => Getter a b c d    -> a -> f c
 asumOf :: Alternative f => Lens a b c d      -> a -> f c
 asumOf :: Alternative f => Fold a b c d      -> a -> f c
 asumOf :: Alternative f => Traversal a b c d -> a -> f c

msumOf :: MonadPlus m => ((m c -> Const (Endo (m c)) d) -> a -> Const (Endo (m c)) b) -> a -> m c

The sum of a collection of actions, generalizing concatOf.

 msum = msumOf folded

 msumOf :: MonadPlus m => Getter a b c d    -> a -> m c
 msumOf :: MonadPlus m => Lens a b c d      -> a -> m c
 msumOf :: MonadPlus m => Fold a b c d      -> a -> m c
 msumOf :: MonadPlus m => Traversal a b c d -> a -> m c

concatMapOf :: ((c -> Const [e] d) -> a -> Const [e] b) -> (c -> [e]) -> a -> [e]

 concatMap = concatMapOf folded

 concatMapOf :: Getter a b c d     -> (c -> [e]) -> a -> [e]
 concatMapOf :: Lens a b c d      -> (c -> [e]) -> a -> [e]
 concatMapOf :: Fold a b c d      -> (c -> [e]) -> a -> [e]
 concatMapOf :: Traversal a b c d -> (c -> [e]) -> a -> [e]

concatOf :: (([e] -> Const [e] d) -> a -> Const [e] b) -> a -> [e]

 concat = concatOf folded

 concatOf :: Getter a b [e] d -> a -> [e]
 concatOf :: Lens a b [e] d -> a -> [e]
 concatOf :: Fold a b [e] d -> a -> [e]
 concatOf :: a b [e] d -> a -> [e]

elemOf :: Eq c => ((c -> Const Any d) -> a -> Const Any b) -> c -> a -> Bool

 elem = elemOf folded

 elemOf :: Eq c => Getter a b c d    -> c -> a -> Bool
 elemOf :: Eq c => Lens a b c d      -> c -> a -> Bool
 elemOf :: Eq c => Fold a b c d      -> c -> a -> Bool
 elemOf :: Eq c => Traversal a b c d -> c -> a -> Bool

notElemOf :: Eq c => ((c -> Const Any d) -> a -> Const Any b) -> c -> a -> Bool

 notElem = notElemOf folded

 notElemOf :: Eq c => Getter a b c d    -> c -> a -> Bool
 notElemOf :: Eq c => Fold a b c d      -> c -> a -> Bool
 notElemOf :: Eq c => Lens a b c d      -> c -> a -> Bool
 notElemOf :: Eq c => Traversal a b c d -> c -> a -> Bool

Traversals

type Traversal a b c d = forall f. Applicative f => (c -> f d) -> a -> f b

A Traversal can be used directly as a Setter or a Fold (but not as a Lens) and provides the ability to both read and update multiple fields, subject to some relatively weak Traversal laws.

These are also known as MultiLens families, but they have the signature and spirit of

 traverse :: Traversable f => Traversal (f a) (f b) a b

and the more evocative name suggests their application.

Common Traversals

traverseNothing :: Traversal a a c d

This is the traversal that never succeeds at returning any values

 traverseNothing :: Applicative f => (c -> f d) -> a -> f a

traverseValueAt :: Ord k => k -> Simple Traversal (Map k v) v

Traverse the value at a given key in a Map

 traverseValueAt :: (Applicative f, Ord k) => k -> (v -> f v) -> Map k v -> f (Map k v)
 traverseValueAt k = valueAt k . traverse

traverseValueAtInt :: Int -> Simple Traversal (IntMap v) v

Traverse the value at a given key in an IntMap

 traverseValueAtInt :: Applicative f => Int -> (v -> f v) -> IntMap v -> f (IntMap v)
 traverseValueAtInt k = valueAtInt k . traverse

traverseHead :: Simple Traversal [a] a

 traverseHead :: Applicative f => (a -> f a) -> [a] -> f [a]

traverseTail :: Simple Traversal [a] [a]

 traverseTail :: Applicative f => ([a] -> f [a]) -> [a] -> f [a]

traverseLast :: Simple Traversal [a] a

Traverse the last element in a list.

 traverseLast = traverseValueAtMax

 traverseLast :: Applicative f => (a -> f a) -> [a] -> f [a]

traverseInit :: Simple Traversal [a] [a]

Traverse all but the last element of a list

 traverseInit :: Applicative f => ([a] -> f [a]) -> [a] -> f [a]

traverseLeft :: Traversal (Either a c) (Either b c) a b

A traversal for tweaking the left-hand value in an Either:

 traverseLeft :: Applicative f => (a -> f b) -> Either a c -> f (Either b c)

traverseRight :: Traversal (Either c a) (Either c b) a b

traverse the right-hand value in an Either:

 traverseRight :: Applicative f => (a -> f b) -> Either c a -> f (Either c a)
 traverseRight = traverse

Unfortunately the instance for 'Traversable (Either c)' is still missing from base, so this can't just be traverse

traverseElement :: Traversable t => Int -> Simple Traversal (t a) a

Traverse a single element in a traversable container.

 traverseElement :: (Applicative f, Traversable t) => Int -> (a -> f a) -> t a -> f (t a)

traverseElements :: Traversable t => (Int -> Bool) -> Simple Traversal (t a) a

Traverse elements where a predicate holds on their position in a traversable container

 traverseElements :: Applicative f, Traversable t) => (Int -> Bool) -> (a -> f a) -> t a -> f (t a)

class TraverseByteString t where

Provides ad hoc overloading for traverseByteString

Methods

traverseByteString :: Simple Traversal t Word8

Traverse the individual bytes in a ByteString

 anyOf traverseByteString (==0x80) :: TraverseByteString b => b -> Bool

Instances

TraverseByteString ByteString

TraverseByteString ByteString

class TraverseValueAtMin t where

Types that support traversal of the value of the minimal key

This is separate from TraverseValueAtMax because a min-heap or max-heap may be able to support one, but not the other.

Methods

traverseValueAtMin :: Simple Traversal (t v) v

Traverse the value for the minimal key

Instances

TraverseValueAtMin []

TraverseValueAtMin Seq

TraverseValueAtMin IntMap

TraverseValueAtMin (Map k)

class TraverseValueAtMax t where

Types that support traversal of the value of the maximal key

This is separate from TraverseValueAtMin because a min-heap or max-heap may be able to support one, but not the other.

Methods

traverseValueAtMax :: Simple Traversal (t v) v

Traverse the value for the maximal key

Instances

TraverseValueAtMax []

TraverseValueAtMax Seq

TraverseValueAtMax IntMap

TraverseValueAtMax (Map k)

traverseBits :: Bits b => Simple Traversal b Bool

Traverse over all bits in a numeric type.

 ghci> toListOf traverseBits (5 :: Word8)
 [True,False,True,False,False,False,False,False]

If you supply this an Integer, it won't crash, but the result will be an infinite traversal that can be productively consumed.

 ghci> toListOf traverseBits 5
 [True,False,True,False,False,False,False,False,False,False,False,False...

Traversal Combinators

mapMOf :: ((c -> WrappedMonad m d) -> a -> WrappedMonad m b) -> (c -> m d) -> a -> m b

 mapM = mapMOf traverse

 mapMOf :: Monad m => Lens a b c d      -> (c -> m d) -> a -> m b
 mapMOf :: Monad m => Traversal a b c d -> (c -> m d) -> a -> m b

sequenceAOf :: Applicative f => ((f c -> f (f c)) -> a -> f b) -> a -> f b

 sequenceA = sequenceAOf traverse

 sequenceAOf :: Applicative f => Lens a b (f c) (f c)      -> a -> f b
 sequenceAOf :: Applicative f => Traversal a b (f c) (f c) -> a -> f b

sequenceOf :: Monad m => ((m c -> WrappedMonad m (m c)) -> a -> WrappedMonad m b) -> a -> m b

 sequence = sequenceOf traverse

 sequenceOf :: Monad m => Lens a b (m c) (m c)      -> a -> m b
 sequenceOf :: Monad m => Traversal a b (m c) (m c) -> a -> m b

elementOf :: Applicative f => ((c -> AppliedState f c) -> a -> AppliedState f b) -> Int -> (c -> f c) -> a -> f b

A Traversal of the nth element of another Traversal

 traverseHead = elementOf traverse 0

elementsOf :: Applicative f => ((c -> AppliedState f c) -> a -> AppliedState f b) -> (Int -> Bool) -> (c -> f c) -> a -> f b

A Traversal of the elements in another Traversal where their positions in that Traversal satisfy a predicate

 traverseTail = elementsOf traverse (>0)

transposeOf :: (([c] -> ZipList c) -> a -> ZipList b) -> a -> [b]

 transpose = transposeOf traverse -- modulo the ragged arrays support

 transposeOf _2 :: (b, [a]) -> [(b, a)]