add filter, deprecate unsafeSelect

[julien-truffaut]

This PR adds Optional.filter and filter method on all Optics and ApplyOptics.

filter allows to select the targets which satisfy a predicate, for example:

val positiveNumbers = Traversal.fromTraverse[List, Int].filter(_ > 0)
val list = List(1,2,-3,4,-5)

positiveNumbers.getAll(list) == List(1,2,4)
positiveNumbers.modify(_ * 10)(list) == List(10,20,-3,40,-5) // only the positive numbers are multiplied by 10

filter can break the fusion law that says that modify(f).modify(g) == modify(f andThen g), for example:

val list       = List(1, 5, -3)
val firstStep  = positiveNumbers.modify(_ - 3)(list)            // List(-2, 2, -3)
val secondStep = positiveNumbers.modify(_ * 2)(firstStep)       // List(-2, 4, -3)
val bothSteps  = positiveNumbers.modify(x => (x - 3) * 2)(list) // List(-4, 4, -3)

In bothSteps, the first value is -4 = (1 - 3) * 2 but in secondStep it is -2 = (1 - 3).
The second update _ * 2 wasn't applied because the target became negative after the first update _ - 3.

In other words, filter breaks the property if replace or modify invalidate the predicate.

A safe usage would be to filter on one field and update another one, for example:

case class User(name: String, coins: Int, address: Address)
case class Address(line1: String, country: String)

val users: Traversal[State, User] = ...
val coins: Lens[User, Int] = ...

users
  .filter(_.address.country == "UK")
  .andThen(coins)
  .modify(_ - 5) // remove 5 coins to all UK users

[cquiroz]

Cool, this will be useful

[jdegoes]

Yes, please!