Add forEachAccumulating and refactor mapOrAccumulate

[kyay10]

First discussed on Slack.

This seems to be a useful primitive. I don't know whether exposing the iterator methods is a good idea or not. One can always use asSequence, but with extra wrapping.
I also added some missing mapOrAccumulate overloads that are refactored from other files.

[github-actions]

Kover Report

File	Coverage [51.91%]
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/Sequence.kt	34.02%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/map.kt	91.24%
arrow-libs/core/arrow-core/src/commonMain/kotlin/arrow/core/raise/RaiseAccumulate.kt	65.47%

Total Project Coverage	52.71%

[serras]

I like the idea of this API, especially because then mapOrAccumulate becomes simply buildList { forEachOrAccumulate { ... } }. However, I think that the implementation is quite too convoluted compared to the previous one (I've left a suggestion on how to fix it).

[serras]

I think that we should follow the convention from the rest of the functions, and call this forEachOrAccumulate instead (in line with zipOrAccumulate and mapOrAccumulate). WDYT @kyay10 @nomisRev ?

[serras]

One can always use asSequence, but with extra wrapping.

Note that it's important to keep the semantics of Sequence, which is lazy evaluation of the elements. It's not the same to do sequence.toList().map(f).asSequence() that sequence.map(f); the latter won't start doing any work until the sequence is inspected, whereas the former will.

[kyay10]

wrt forEachOrAccumulate: orXXX is usually used in the stdlib as some failing strategy with some normal return value. forEachAccumulating sounds more verb-like and hence imperative, which fits well with forEach. However, I see that consistency might be desireable here, so I'm fine with either name.

[kyay10]

It's not the same to do sequence.toList().map(f).asSequence() that sequence.map(f); the latter won't start doing any work until the sequence is inspected, whereas the former will.

What I meant here was exposing forEachAccumulating(iterator: Iterator<A>). I left it exposed because it might be useful, but we might want to make it internal and instead users can use the sequence overload by wrapping their iterator in a sequence.

[kyay10]

Quick note: I've used buildXXX extensively here, but I think there was a concern before that we should just use mutable collections to allow users to mutate if they really want to rather cheaply. Not sure If the take on that has changed, but just figured I should mention it