Control.Lens.At

lens-4.13.2.1: Lenses, Folds and Traversals

Copyright | (C) 2012-16 Edward Kmett
License | BSD-style (see the file LICENSE)
Maintainer | Edward Kmett <ekmett@gmail.com>
Stability | experimental
Portability | non-portable
Safe Haskell | Trustworthy
Language | Haskell98

Control.Lens.At

Contents

- At
- Ixed
- Contains

Description

Synopsis

- class Ixed m => At m where
  - at :: Index m -> Lens' m (Maybe (IxValue m))
- sans :: At m => Index m -> m -> m
- iat :: At m => Index m -> IndexedLens' (Index m) m (Maybe (IxValue m))
- type family Index s :: *
- type family IxValue m :: *
- class Ixed m where
  - ix :: Index m -> Traversal' m (IxValue m)
- ixAt :: At m => Index m -> Traversal' m (IxValue m)
- iix :: Ixed m => Index m -> IndexedTraversal' (Index m) m (IxValue m)
- class Contains m where
  - contains :: Index m -> Lens' m Bool
- icontains :: Contains m => Index m -> IndexedLens' (Index m) m Bool

# At

class Ixed m => At m where

`At` provides a `Lens` that can be used to read, write or delete the value associated with a key in a `Map`-like container on an ad hoc basis.

An instance of `At` should satisfy:

    ix k ≡ at k . traverse

Methods

at :: Index m -> Lens' m (Maybe (IxValue m))

    >>> Map.fromList [(1,"world")] ^.at 1
    Just "world"

    >>> at 1 ?~ "hello" $ Map.empty
    fromList [(1,"hello")]

Note: `Map`-like containers form a reasonable instance, but not `Array`-like ones, where you cannot satisfy the `Lens` laws.

Instances

At IntSet |
At (Maybe a) |
At (IntMap a) |
Ord k => At (Set k) |
(Eq k, Hashable k) => At (HashSet k) |
Ord k => At (Map k a) |
(Eq k, Hashable k) => At (HashMap k a) |

sans :: At m => Index m -> m -> m

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

    sans k = at k .~ Nothing

iat :: At m => Index m -> IndexedLens' (Index m) m (Maybe (IxValue m))

An indexed version of `at`.

    >>> Map.fromList [(1,"world")] ^@. iat 1
    (1,Just "world")

    >>> iat 1 %@~ (\i x -> if odd i then Just "hello" else Nothing) $ Map.empty
    fromList [(1,"hello")]

    >>> iat 2 %@~ (\i x -> if odd i then Just "hello" else Nothing) $ Map.empty
    fromList []

# Ixed

type family Index s :: *

Instances

type Index ByteString = Int |
type Index ByteString = Int64 |
type Index IntSet = Int |
type Index Text = Int64 |
type Index Text = Int |
type Index [a] = Int |
type Index (Identity a) = () |
type Index (Complex a) = Int |
type Index (Maybe a) = () |
type Index (IntMap a) = Int |
type Index (Set a) = a |
type Index (Tree a) = [Int] |
type Index (Seq a) = Int |
type Index (NonEmpty a) = Int |
type Index (HashSet a) = a |
type Index (Vector a) = Int |
type Index (Vector a) = Int |
type Index (Vector a) = Int |
type Index (Vector a) = Int |
type Index (e -> a) = e |
type Index (a, b) = Int |
type Index (UArray i e) = i |
type Index (Array i e) = i |
type Index (Map k a) = k |
type Index (HashMap k a) = k |
type Index (a, b, c) = Int |
type Index (a, b, c, d) = Int |
type Index (a, b, c, d, e) = Int |
type Index (a, b, c, d, e, f) = Int |
type Index (a, b, c, d, e, f, g) = Int |
type Index (a, b, c, d, e, f, g, h) = Int |
type Index (a, b, c, d, e, f, g, h, i) = Int |

type family IxValue m :: *

This provides a common notion of a value at an index that is shared by both `Ixed` and `At`.

Instances

type IxValue ByteString = Word8 |
type IxValue ByteString = Word8 |
type IxValue IntSet = () |
type IxValue Text = Char |
type IxValue Text = Char |
type IxValue [a] = a |
type IxValue (Identity a) = a |
type IxValue (Maybe a) = a |
type IxValue (IntMap a) = a |
type IxValue (Set k) = () |
type IxValue (Tree a) = a |
type IxValue (Seq a) = a |
type IxValue (NonEmpty a) = a |
type IxValue (HashSet k) = () |
type IxValue (Vector a) = a |
type IxValue (Vector a) = a |
type IxValue (Vector a) = a |
type IxValue (Vector a) = a |
type IxValue (e -> a) = a |
type IxValue (a, a2) = a |
    ix :: Int -> Traversal' (a,a) a
type IxValue (UArray i e) = e |
type IxValue (Array i e) = e |
type IxValue (Map k a) = a |
type IxValue (HashMap k a) = a |
type IxValue (a, a2, a3) = a |
    ix :: Int -> Traversal' (a,a,a) a
type IxValue (a, a2, a3, a4) = a |
    ix :: Int -> Traversal' (a,a,a,a) a
type IxValue (a, a2, a3, a4, a5) = a |
    ix :: Int -> Traversal' (a,a,a,a,a) a
type IxValue (a, a2, a3, a4, a5, a6) = a |
    ix :: Int -> Traversal' (a,a,a,a,a,a) a
type IxValue (a, a2, a3, a4, a5, a6, a7) = a |
    ix :: Int -> Traversal' (a,a,a,a,a,a,a) a
type IxValue (a, a2, a3, a4, a5, a6, a7, a8) = a |
    ix :: Int -> Traversal' (a,a,a,a,a,a,a,a) a
type IxValue (a, a2, a3, a4, a5, a6, a7, a8, a9) = a |
    ix :: Int -> Traversal' (a,a,a,a,a,a,a,a,a) a

class Ixed m where

This simple `Traversal` lets you `traverse` the value at a given key in a `Map` or element at an ordinal position in a list or `Seq`.

Minimal complete definition

Nothing

Methods

ix :: Index m -> Traversal' m (IxValue m)

This simple `Traversal` lets you `traverse` the value at a given key in a `Map` or element at an ordinal position in a list or `Seq`.

NB: Setting the value of this `Traversal` will only set the value in `at` if it is already present.

If you want to be able to insert missing values, you want `at`.

    >>> Seq.fromList [a,b,c,d] & ix 2 %~ f
    fromList [a,b,f c,d]

    >>> Seq.fromList [a,b,c,d] & ix 2 .~ e
    fromList [a,b,e,d]

    >>> Seq.fromList [a,b,c,d] ^? ix 2
    Just c

    >>> Seq.fromList [] ^? ix 2
    Nothing

Instances

Ixed ByteString |
Ixed ByteString |
Ixed IntSet |
Ixed Text |
Ixed Text |
Ixed [a] |
Ixed (Identity a) |
Ixed (Maybe a) |
Ixed (IntMap a) |
Ord k => Ixed (Set k) |
Ixed (Tree a) |
Ixed (Seq a) |
Ixed (NonEmpty a) |
(Eq k, Hashable k) => Ixed (HashSet k) |
Ixed (Vector a) |
Unbox a => Ixed (Vector a) |
Storable a => Ixed (Vector a) |
Prim a => Ixed (Vector a) |
Eq e => Ixed (e -> a) |
(~) * a a2 => Ixed (a, a2) |
(IArray UArray e, Ix i) => Ixed (UArray i e) |
    arr ! i ≡ arr ^. ix i
    arr // [(i,e)] ≡ ix i .~ e $ arr
Ix i => Ixed (Array i e) |
    arr ! i ≡ arr ^. ix i
    arr // [(i,e)] ≡ ix i .~ e $ arr
Ord k => Ixed (Map k a) |
(Eq k, Hashable k) => Ixed (HashMap k a) |
((~) * a a2, (~) * a a3) => Ixed (a, a2, a3) |
((~) * a a2, (~) * a a3, (~) * a a4) => Ixed (a, a2, a3, a4) |
((~) * a a2, (~) * a a3, (~) * a a4, (~) * a a5) => Ixed (a, a2, a3, a4, a5) |
((~) * a a2, (~) * a a3, (~) * a a4, (~) * a a5, (~) * a a6) => Ixed (a, a2, a3, a4, a5, a6) |
((~) * a a2, (~) * a a3, (~) * a a4, (~) * a a5, (~) * a a6, (~) * a a7) => Ixed (a, a2, a3, a4, a5, a6, a7) |
((~) * a a2, (~) * a a3, (~) * a a4, (~) * a a5, (~) * a a6, (~) * a a7, (~) * a a8) => Ixed (a, a2, a3, a4, a5, a6, a7, a8) |
((~) * a a2, (~) * a a3, (~) * a a4, (~) * a a5, (~) * a a6, (~) * a a7, (~) * a a8, (~) * a a9) => Ixed (a, a2, a3, a4, a5, a6, a7, a8, a9) |

ixAt :: At m => Index m -> Traversal' m (IxValue m)

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

iix :: Ixed m => Index m -> IndexedTraversal' (Index m) m (IxValue m)

An indexed version of `ix`.

    >>> Seq.fromList [a,b,c,d] & iix 2 %@~ f'
    fromList [a,b,f' 2 c,d]

    >>> Seq.fromList [a,b,c,d] & iix 2 .@~ h
    fromList [a,b,h 2,d]

    >>> Seq.fromList [a,b,c,d] ^@? iix 2
    Just (2,c)

    >>> Seq.fromList [] ^@? iix 2
    Nothing

# Contains

class Contains m where

This class provides a simple `Lens` that lets you view (and modify) information about whether or not a container contains a given `Index`.

Methods

contains :: Index m -> Lens' m Bool

    >>> IntSet.fromList [1,2,3,4] ^. contains 3
    True

    >>> IntSet.fromList [1,2,3,4] ^. contains 5
    False

    >>> IntSet.fromList [1,2,3,4] & contains 3 .~ False
    fromList [1,2,4]

Instances

Contains IntSet |
Ord a => Contains (Set a) |
(Eq a, Hashable a) => Contains (HashSet a) |

icontains :: Contains m => Index m -> IndexedLens' (Index m) m Bool

An indexed version of `contains`.

    >>> IntSet.fromList [1,2,3,4] ^@. icontains 3
    (3,True)

    >>> IntSet.fromList [1,2,3,4] ^@. icontains 5
    (5,False)

    >>> IntSet.fromList [1,2,3,4] & icontains 3 %@~ \i x -> if odd i then not x else x
    fromList [1,2,4]

    >>> IntSet.fromList [1,2,3,4] & icontains 3 %@~ \i x -> if even i then not x else x
    fromList [1,2,3,4]