From c0f0ac39d7baf90eb41b39a4b1b30d65db1a7b0c Mon Sep 17 00:00:00 2001 From: Alejandro Serrano Date: Thu, 30 Nov 2023 16:09:51 +0100 Subject: [PATCH] Docs about collectors --- .../learn/collections-functions/collectors.md | 49 +++++++++++++++++++ .../learn/collections-functions/memoize.md | 2 +- .../learn/collections-functions/recursive.md | 2 +- .../docs/learn/collections-functions/utils.md | 2 +- content/docs/learn/overview.md | 1 + 5 files changed, 53 insertions(+), 3 deletions(-) create mode 100644 content/docs/learn/collections-functions/collectors.md diff --git a/content/docs/learn/collections-functions/collectors.md b/content/docs/learn/collections-functions/collectors.md new file mode 100644 index 00000000..ed9753a2 --- /dev/null +++ b/content/docs/learn/collections-functions/collectors.md @@ -0,0 +1,49 @@ +--- +sidebar_position: 2 +description: Better aggregation over sequences +--- + +# Collectors + +Collectors help build complex computations over sequences of values, +guaranteeing that those values are consumed only once. + +Take for example the computation of the average of a list. You can +certainly write a simple version using the built-in functions, + +```kotlin +val average = list.sum() / list.size +``` + + +Note however that this implementation traverses the list _twice_, +one per operation over the list. This may not be a problem for small +lists but could become more problematic with longer collections. +Some data structures, like `Sequence` or `Flow`, impose an +even larger footprint, as their elements are computed every time +you need a new one. + +Collectors separate the description of the aggregation you want +to perform from the actual collection. To create a new collector +you use one of the built-in ones, and combine them using `zip`. + +```kotlin +val averageCollector = zip(Collectors.sum, Collectors.length) { s, l -> + s.toDouble() / l.toDouble() +} +``` + +You then may apply the collector to the sequence or collection you want. + +```kotlin +val average = list.collect(averageCollector) +``` + + +:::note Influences + +The API implemented in `arrow-collectors` is heavily influenced by +Java's [`Collector`](https://docs.oracle.com/javase/8/docs/api/java/util/stream/Collector.html) +and Haskell's [`foldl` library](https://hackage.haskell.org/package/foldl/docs/Control-Foldl.html). + +::: \ No newline at end of file diff --git a/content/docs/learn/collections-functions/memoize.md b/content/docs/learn/collections-functions/memoize.md index 7f64a802..61a2df2e 100644 --- a/content/docs/learn/collections-functions/memoize.md +++ b/content/docs/learn/collections-functions/memoize.md @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 description: Avoiding duplicate work for pure functions --- diff --git a/content/docs/learn/collections-functions/recursive.md b/content/docs/learn/collections-functions/recursive.md index 5ac8b41c..437f3d98 100644 --- a/content/docs/learn/collections-functions/recursive.md +++ b/content/docs/learn/collections-functions/recursive.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 description: Making functions stack-safe and efficient --- diff --git a/content/docs/learn/collections-functions/utils.md b/content/docs/learn/collections-functions/utils.md index 36ccf530..85528261 100644 --- a/content/docs/learn/collections-functions/utils.md +++ b/content/docs/learn/collections-functions/utils.md @@ -1,5 +1,5 @@ --- -sidebar_position: 4 +sidebar_position: 5 description: Composition, partial application, and currying --- diff --git a/content/docs/learn/overview.md b/content/docs/learn/overview.md index 978bad1d..556742d1 100644 --- a/content/docs/learn/overview.md +++ b/content/docs/learn/overview.md @@ -33,6 +33,7 @@ Each section in the documentation roughly corresponds to one of the libraries th | Library | Features | | --- | --- | | `arrow-core`
_Companion to [Kotlin's standard library](https://kotlinlang.org/api/latest/jvm/stdlib/)_ | [Typed errors](../typed-errors/), including `Raise`, `Either`, and `Option`
[Non-empty collections](../collections-functions/non-empty)
[Utilities for functions](../collections-functions/utils/) and [memoization](../collections-functions/recursive/) | +| `arrow-collectors`
_Companion to [`fold`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/fold.html) and [`reduce`](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/reduce.html)_ | [Aggregation with single traversal](../collections-functions/collectors/) | | `arrow-fx-coroutines`
_Companion to [KotlinX Coroutines](https://kotlinlang.org/api/kotlinx.coroutines/kotlinx-coroutines-core/)_ | [High-level concurrency](../coroutines/parallel), including `parMap` and `parZip`
[Resource management](../coroutines/resource-safety/) | | `arrow-resilience` | [Resilience patterns](../resilience/) | | `arrow-fx-stm` | [Software Transactional Memory](../coroutines/stm/) (STM) |