Implement QPromise<Sequence<T>>::map(mapper) (#15)

Iterate over all the promise value (i.e. `Sequence<T>`) and map the sequence to another using the given `mapper` function. Also provide a static helper to directly map values (`QtPromise::map(values, mapper)`).

docs/SUMMARY.md

@@ -10,6 +10,7 @@
   * [.isFulfilled](qtpromise/qpromise/isfulfilled.md)
   * [.isPending](qtpromise/qpromise/ispending.md)
   * [.isRejected](qtpromise/qpromise/isrejected.md)
+  * [.map](qtpromise/qpromise/map.md)
   * [.tap](qtpromise/qpromise/tap.md)
   * [.tapFail](qtpromise/qpromise/tapfail.md)
   * [.then](qtpromise/qpromise/then.md)
@@ -20,3 +21,4 @@
   * [::resolve (static)](qtpromise/qpromise/resolve.md)
   * [qPromise](qtpromise/helpers/qpromise.md)
   * [qPromiseAll](qtpromise/helpers/qpromiseall.md)
+  * [QtPromise::map](qtpromise/helpers/map.md)

docs/qtpromise/api-reference.md

@@ -9,6 +9,7 @@
 * [`QPromise<T>::isFulfilled`](qpromise/isfulfilled.md)
 * [`QPromise<T>::isPending`](qpromise/ispending.md)
 * [`QPromise<T>::isRejected`](qpromise/isrejected.md)
+* [`QPromise<T>::map`](qpromise/map.md)
 * [`QPromise<T>::tap`](qpromise/tap.md)
 * [`QPromise<T>::tapFail`](qpromise/tapfail.md)
 * [`QPromise<T>::then`](qpromise/then.md)
@@ -25,3 +26,4 @@
 
 * [`qPromise`](helpers/qpromise.md)
 * [`qPromiseAll`](helpers/qpromiseall.md)
+* [`QtPromise::map`](helpers/map.md)

docs/qtpromise/helpers/map.md

@@ -0,0 +1,43 @@
+## `QtPromise::map`
+
+```cpp
+QtPromise::map(Sequence<T> values, Mapper mapper) -> QPromise<QVector<R>>
+
+// With:
+// - Sequence: STL compatible container (e.g. QVector, etc.)
+// - Mapper: Function(T value, int index) -> R | QPromise<R>
+```
+
+Iterates over `values` and [maps the sequence](https://en.wikipedia.org/wiki/Map_%28higher-order_function%29)
+to another using the given `mapper` function. The type returned by `mapper` determines the type
+of the `output` promise. If `mapper` throws, `output` is rejected with the new exception.
+
+If `mapper` returns a promise (or `QFuture`), the `output` promise is delayed until all the
+promises are resolved. If any of the promises fails, `output` immediately rejects with the
+error of the promise that rejected, whether or not the other promises are resolved.
+
+```cpp
+auto output = QtPromise::map(QVector{
+    QUrl("http://a..."),
+    QUrl("http://b..."),
+    QUrl("http://c...")
+}, [](const QUrl& url, ...) {
+    return QPromise<QByteArray>([&](auto resolve, auto reject) {
+        // download content at url and resolve
+        // {...}
+    });
+});
+
+// 'output' resolves as soon as all promises returned by
+// 'mapper' are fulfilled or at least one is rejected.
+
+// 'output' type: QPromise<QVector<QByteArray>>
+output.then([](const QVector<QByteArray>& res) {
+    // {...}
+});
+```
+
+> **Note:** the order of the output sequence values is guarantee to be the same as the original
+sequence, regardless of completion order of the promises returned by `mapper`.
+
+See also: [`QPromise<T>::map`](../qpromise/map.md)

docs/qtpromise/qpromise/map.md

@@ -0,0 +1,57 @@
+## `QPromise<Sequence<T>>::map`
+
+> **Important:** applies only to promise with sequence value.
+
+```cpp
+QPromise<Sequence<T>>::map(Mapper mapper) -> QPromise<QVector<R>>
+
+// With:
+// - Sequence: STL compatible container (e.g. QVector, etc.)
+// - Mapper: Function(T value, int index) -> R | QPromise<R>
+```
+
+Iterates over all the promise values (i.e. `Sequence<T>`) and [maps the sequence](https://en.wikipedia.org/wiki/Map_%28higher-order_function%29)
+to another using the given `mapper` function. The type returned by `mapper` determines the type
+of the `output` promise. If `mapper` throws, `output` is rejected with the new exception.
+
+If `mapper` returns a promise (or `QFuture`), the `output` promise is delayed until all the
+promises are resolved. If any of the promises fails, `output` immediately rejects with the
+error of the promise that rejected, whether or not the other promises are resolved.
+
+```cpp
+QPromise<QList<QUrl>> input = {...}
+
+auto output = input.map([](const QUrl& url, int index) {
+    return QPromise<QByteArray>([&](auto resolve, auto reject) {
+        // download content at 'url' and resolve
+        // {...}
+    });
+}).map([](const QByteArray& value, ...) {
+    // process the downloaded QByteArray
+    // {...}
+    return DownloadResult(value);
+});
+
+// 'output' resolves as soon as all promises returned by
+// 'mapper' are fulfilled or at least one is rejected.
+
+// 'output' type: QPromise<QVector<DownloadResult>>
+output.then([](const QVector<DownloadResult>& res) {
+    // {...}
+});
+```
+
+> **Note:** the order of the output sequence values is guarantee to be the same as the original
+sequence, regardless of completion order of the promises returned by `mapper`.
+
+This function is provided for convenience and is similar to:
+
+```cpp
+promise.then([](const Sequence<T>& values) {
+    return QtPromise::map(values, [](const T& value, int index) {
+        return // {...}
+    });
+});
+```
+
+See also: [`QtPromise::map`](../helpers/map.md)