lens-5.2.3: Lenses, Folds and Traversals

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

Data.List.Lens

Description

Traversals for manipulating parts of a list.

Additional optics for manipulating lists are present more generically in this package.

The `Ixed` class allows traversing the element at a specific list index.

    >>> [0..10] ^? ix 4
    Just 4

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

    >>> [0..10] ^? ix 14
    Nothing

    >>> [0..5] & ix 14 .~ 2
    [0,1,2,3,4,5]

The `Cons` and `AsEmpty` classes provide `Prism`s for list constructors.

    >>> [1..10] ^? _Cons
    Just (1,[2,3,4,5,6,7,8,9,10])

    >>> [] ^? _Cons
    Nothing

    >>> [] ^? _Empty
    Just ()

    >>> _Cons # (1, _Empty # ()) :: [Int]
    [1]

Additionally, `Snoc` provides a `Prism` for accessing the end of a list. Note that this `Prism` always will need to traverse the whole list.

    >>> [1..5] ^? _Snoc
    Just ([1,2,3,4],5)

    >>> _Snoc # ([1,2],5)
    [1,2,5]

An instance of `Plated` allows for finding locations in the list where a traversal matches.

    >>> [Nothing, Just 7, Just 3, Nothing] & deep (ix 0 . _Just) +~ 10
    [Nothing,Just 17,Just 3,Nothing]

An instance of `Reversing` provides an `Iso` between a list and its reverse.

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

It's possible to work under a prefix or suffix of a list using `Prefixed` and `Suffixed`.

    >>> "preview" ^? prefixed "pre"
    Just "view"

    >>> suffixed ".o" # "hello"
    "hello.o"

At present, Data.List.Lens re-exports `Prefixed` and `Suffixed` for backwards compatibility, as `prefixed` and `suffixed` used to be top-level functions defined in this module. This may change in a future major release of `lens`.

Finally, it's possible to traverse, fold over, and map over index-value pairs thanks to instances of `TraversableWithIndex`, `FoldableWithIndex`, and `FunctorWithIndex`.

    >>> imap (,) "Hello"
    [(0,'H'),(1,'e'),(2,'l'),(3,'l'),(4,'o')]

    >>> ifoldMap replicate "Hello"
    "ellllloooo"

    >>> itraverse_ (curry print) "Hello"
    (0,'H')
    (1,'e')
    (2,'l')
    (3,'l')
    (4,'o')

Synopsis

- class Prefixed t where
  - prefixed :: t -> Prism' t t
- class Suffixed t where
  - suffixed :: t -> Prism' t t
- stripSuffix :: Eq a => [a] -> [a] -> Maybe [a]

# Documentation

class Prefixed t where #

Methods

prefixed :: t -> Prism' t t #

A `Prism` stripping a prefix from a sequence when used as a `Traversal`, or prepending that prefix when run backwards:

    >>> "preview" ^? prefixed "pre"
    Just "view"

    >>> "review" ^? prefixed "pre"
    Nothing

    >>> prefixed "pre" # "amble"
    "preamble"

#### Instances

Instances details

Prefixed ByteString # |
Instance details Defined in Control.Lens.Prism Methods prefixed :: ByteString -> Prism' ByteString ByteString #
Prefixed ByteString # |
Instance details Defined in Control.Lens.Prism Methods prefixed :: ByteString -> Prism' ByteString ByteString #
Prefixed Text # |
Instance details Defined in Control.Lens.Prism Methods prefixed :: Text -> Prism' Text Text #
Prefixed Text # |
Instance details Defined in Control.Lens.Prism Methods prefixed :: Text -> Prism' Text Text #
Eq a => Prefixed [a] # |
Instance details Defined in Control.Lens.Prism Methods prefixed :: [a] -> Prism' [a] [a] #

class Suffixed t where #

Methods

suffixed :: t -> Prism' t t #

A `Prism` stripping a suffix from a sequence when used as a `Traversal`, or appending that suffix when run backwards:

    >>> "review" ^? suffixed "view"
    Just "re"

    >>> "review" ^? suffixed "tire"
    Nothing

    >>> suffixed ".o" # "hello"
    "hello.o"

#### Instances

Instances details

Suffixed ByteString # |
Instance details Defined in Control.Lens.Prism Methods suffixed :: ByteString -> Prism' ByteString ByteString #
Suffixed ByteString # |
Instance details Defined in Control.Lens.Prism Methods suffixed :: ByteString -> Prism' ByteString ByteString #
Suffixed Text # |
Instance details Defined in Control.Lens.Prism Methods suffixed :: Text -> Prism' Text Text #
Suffixed Text # |
Instance details Defined in Control.Lens.Prism Methods suffixed :: Text -> Prism' Text Text #
Eq a => Suffixed [a] # |
Instance details Defined in Control.Lens.Prism Methods suffixed :: [a] -> Prism' [a] [a] #

stripSuffix :: Eq a => [a] -> [a] -> Maybe [a] #

\(\mathcal{O}(\min(m,n))\). The `stripSuffix` function drops the given suffix from a list. It returns `Nothing` if the list did not end with the suffix given, or `Just` the list after the suffix, if it does.

    >>> stripSuffix "bar" "foobar"
    Just "foo"

    >>> stripSuffix "foo" "foo"
    Just ""

    >>> stripSuffix "bar" "barfoo"
    Nothing

    >>> stripSuffix "foo" "barfoobaz"
    Nothing