Skip to content

Commit fabf082

Browse files
authored
Maintain Traverse and TraverseFilter documents (#122)
* Maintain `Traverse` and `TraverseFilter` documents * Modify a sentence
1 parent ac8b27c commit fabf082

File tree

5 files changed

+122
-5
lines changed

5 files changed

+122
-5
lines changed

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/typeclasses/Traverse.kt

+3-3
Original file line numberDiff line numberDiff line change
@@ -528,13 +528,13 @@ import arrow.core.ValidatedNel
528528
interface Traverse<F> : Functor<F>, Foldable<F> {
529529

530530
/**
531-
* Given a function which returns a G effect, thread this effect through the running of this function on all the
532-
* values in F, returning an F<B> in a G context.
531+
* Given a function which returns a [G] effect, thread this effect through the running of this function on all the
532+
* values in [F], returning an [F]<[B]> in a [G] context.
533533
*/
534534
fun <G, A, B> Kind<F, A>.traverse(AP: Applicative<G>, f: (A) -> Kind<G, B>): Kind<G, Kind<F, B>>
535535

536536
/**
537-
* Thread all the G effects through the F structure to invert the structure from F<G<A>> to G<F<A>>.
537+
* Thread all the [G] effects through the [F] structure to invert the structure from [F]<[G]<[A]>> to [G]<[F]<[A]>>.
538538
*/
539539
fun <G, A> Kind<F, Kind<G, A>>.sequence(AG: Applicative<G>): Kind<G, Kind<F, A>> = traverse(AG, ::identity)
540540

arrow-libs/core/arrow-core-data/src/main/kotlin/arrow/typeclasses/TraverseFilter.kt

+7
Original file line numberDiff line numberDiff line change
@@ -26,11 +26,18 @@ interface TraverseFilter<F> : Traverse<F>, FunctorFilter<F> {
2626
Id.just(a)
2727
}
2828

29+
/**
30+
* Returns [F]<[B]> in [G] context by applying [AP] on a selector function [f], which returns [Option] of [B]
31+
* in [G] context.
32+
*/
2933
fun <G, A, B> Kind<F, A>.traverseFilter(AP: Applicative<G>, f: (A) -> Kind<G, Option<B>>): Kind<G, Kind<F, B>>
3034

3135
override fun <A, B> Kind<F, A>.filterMap(f: (A) -> Option<B>): Kind<F, B> =
3236
traverseFilter(IdApplicative) { Id(f(it)) }.value()
3337

38+
/**
39+
* Returns [F]<[A]> in [G] context by applying [GA] on a selector function [f] in [G] context.
40+
*/
3441
fun <G, A> Kind<F, A>.filterA(f: (A) -> Kind<G, Boolean>, GA: Applicative<G>): Kind<G, Kind<F, A>> = GA.run {
3542
traverseFilter(this) { a -> f(a).map { b -> if (b) Some(a) else None } }
3643
}

arrow-libs/core/arrow-docs/docs/arrow/typeclasses/functor/README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -114,4 +114,4 @@ since they are all subtypes of `Functor`
114114
ank_macro_hierarchy(arrow.typeclasses.Functor)
115115

116116
[functor_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-data/src/main/kotlin/arrow/typeclasses/Functor.kt
117-
[functor_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/test/laws/FunctorLaws.kt
117+
[functor_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/core/test/laws/FunctorLaws.kt
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
layout: docs-core
3+
title: Traverse
4+
permalink: /arrow/typeclasses/traverse/
5+
---
6+
7+
## Traverse
8+
9+
10+
11+
12+
The `Traverse` typeclass is allowing to commute types from `F<G<A>>` to `G<F<A>>` over sequential execution of code.
13+
The main use of this is traversal over a structure with an effect.
14+
This doc focuses on the methods provided by the typeclass.
15+
16+
### Main Combinators
17+
18+
`Traverse` includes all combinators present in [`Functor`]({{ '/arrow/typeclasses/functor/' | relative_url }})
19+
and [`Foldable`]({{ '/arrow/typeclasses/foldable/' | relative_url }}).
20+
21+
#### Kind<F, A>#traverse
22+
23+
Given a function which returns a `G` effect, thread this effect through the running of this function on all the values
24+
in `F`, returning an `F<B>` in a `G` context.
25+
26+
```kotlin:ank
27+
import arrow.core.*
28+
import arrow.core.extensions.id.applicative.applicative
29+
import arrow.core.extensions.traverse
30+
31+
Some(1).traverse(Id.applicative()) { Id.just(it * 2) }
32+
```
33+
34+
#### Kind<F, Kind<G, A>>#sequence
35+
36+
Thread all the `G` effects through the `F` structure to invert the structure from `F<G<A>>` to `G<F<A>>`.
37+
38+
```kotlin:ank
39+
import arrow.core.*
40+
import arrow.core.extensions.id.applicative.applicative
41+
42+
Const<Int, Nothing>(1).sequence<Nothing, Int, ForId>(Id.applicative())
43+
```
44+
45+
### Laws
46+
47+
Arrow provides [`TraverseLaws`][travers_laws_source]{:target="_blank"} in the form of test cases for internal verification of lawful instances and third party apps creating their own `Traverse` instances.
48+
49+
#### Creating your own `Traverse` instances
50+
51+
Arrow already provides `Traverse` instances for most common datatypes both in Arrow and the Kotlin stdlib.
52+
Oftentimes, you may find the need to provide your own for unsupported datatypes.
53+
54+
See [Deriving and creating custom typeclass]({{ '/patterns/glossary' | relative_url }})
55+
56+
### Data types
57+
58+
```kotlin:ank:replace
59+
import arrow.reflect.*
60+
import arrow.typeclasses.Traverse
61+
62+
TypeClass(Traverse::class).dtMarkdownList()
63+
```
64+
65+
ank_macro_hierarchy(arrow.typeclasses.Traverse)
66+
67+
[travers_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/core/test/laws/TraverseLaws.kt

arrow-libs/core/arrow-docs/docs/arrow/typeclasses/traversefilter/README.md

+44-1
Original file line numberDiff line numberDiff line change
@@ -9,8 +9,49 @@ permalink: /arrow/typeclasses/traversefilter/
99

1010

1111

12-
TODO. Meanwhile you can find a short description in the [intro to typeclasses]({{ '/typeclasses/intro/' | relative_url }}).
12+
`TraverseFilter` is helpful when you want to combine `Traverse` and `FunctorFilter` as one combined operation.
13+
This doc focuses on the methods provided by the typeclass.
1314

15+
### Main Combinators
16+
17+
`TraverseFilter` includes all combinators present in [`Traverse`]({{ '/arrow/typeclasses/traverse/' | relative_url }})
18+
and [`FunctorFilter`]({{ '/arrow/typeclasses/functorfilter/' | relative_url }}).
19+
20+
#### Kind<F, A>#traverseFilter
21+
22+
Returns `F<B>` in `G` context by applying `AP` on a selector function `f`, which returns `Option` of `B` in `G` context.
23+
24+
```kotlin:ank
25+
import arrow.core.*
26+
import arrow.core.extensions.id.applicative.applicative
27+
import arrow.core.extensions.traverseFilter
28+
29+
Some(1).traverseFilter(Id.applicative()) { Id.just(None) }
30+
Some(1).traverseFilter(Id.applicative()) { Id.just((it * 2).some()) }
31+
```
32+
33+
#### Kind<F, A>#filterA
34+
35+
Returns `F<A>` in `G` context by applying `GA` on a selector function `f` in `G` context.
36+
37+
```kotlin:ank
38+
import arrow.core.*
39+
import arrow.core.extensions.id.applicative.applicative
40+
import arrow.core.extensions.option.traverseFilter.filterA
41+
42+
Some(1).filterA({ Id.just(false) }, Id.applicative())
43+
```
44+
45+
### Laws
46+
47+
Arrow provides [`TraverseFilterLaws`][travers_filter_laws_source]{:target="_blank"} in the form of test cases for internal verification of lawful instances and third party apps creating their own `TraverseFilter` instances.
48+
49+
#### Creating your own `TraverseFilter` instances
50+
51+
Arrow already provides `TraverseFilter` instances for most common datatypes both in Arrow and the Kotlin stdlib.
52+
Oftentimes, you may find the need to provide your own for unsupported datatypes.
53+
54+
See [Deriving and creating custom typeclass]({{ '/patterns/glossary' | relative_url }})
1455

1556
### Data types
1657

@@ -22,3 +63,5 @@ TypeClass(TraverseFilter::class).dtMarkdownList()
2263
```
2364

2465
ank_macro_hierarchy(arrow.typeclasses.TraverseFilter)
66+
67+
[travers_filter_laws_source]: https://github.com/arrow-kt/arrow-core/blob/master/arrow-core-test/src/main/kotlin/arrow/core/test/laws/TraverseFilterLaws.kt

0 commit comments

Comments
 (0)