Implement QPromise<Sequence<T>>::filter(filterer)

Add a new method that iterates over all the promise values (i.e. `Sequence<T>`) and filters the sequence to another using the given `filterer` function. If `filterer` returns `true`, a copy of the item is put in the `output` sequence, otherwise, the item will not appear in `output`. Also provide a static helper to directly filter values (`QtPromise::filter(values, filterer)`).

docs/SUMMARY.md

@@ -6,6 +6,7 @@
   * [QPromise](qtpromise/qpromise/constructor.md)
   * [.delay](qtpromise/qpromise/delay.md)
   * [.fail](qtpromise/qpromise/fail.md)
+  * [.filter](qtpromise/qpromise/filter.md)
   * [.finally](qtpromise/qpromise/finally.md)
   * [.isFulfilled](qtpromise/qpromise/isfulfilled.md)
   * [.isPending](qtpromise/qpromise/ispending.md)
@@ -21,4 +22,5 @@
   * [::resolve (static)](qtpromise/qpromise/resolve.md)
   * [qPromise](qtpromise/helpers/qpromise.md)
   * [qPromiseAll](qtpromise/helpers/qpromiseall.md)
+  * [QtPromise::filter](qtpromise/helpers/filter.md)
   * [QtPromise::map](qtpromise/helpers/map.md)

docs/qtpromise/api-reference.md

@@ -5,6 +5,7 @@
 * [`QPromise<T>::QPromise`](qpromise/constructor.md)
 * [`QPromise<T>::delay`](qpromise/delay.md)
 * [`QPromise<T>::fail`](qpromise/fail.md)
+* [`QPromise<T>::filter`](qpromise/filter.md)
 * [`QPromise<T>::finally`](qpromise/finally.md)
 * [`QPromise<T>::isFulfilled`](qpromise/isfulfilled.md)
 * [`QPromise<T>::isPending`](qpromise/ispending.md)
@@ -26,4 +27,5 @@
 
 * [`qPromise`](helpers/qpromise.md)
 * [`qPromiseAll`](helpers/qpromiseall.md)
+* [`QtPromise::filter`](helpers/filter.md)
 * [`QtPromise::map`](helpers/map.md)

docs/qtpromise/helpers/filter.md

@@ -0,0 +1,44 @@
+## `QtPromise::filter`
+
+```cpp
+QtPromise::filter(Sequence<T> values, Filterer filterer) -> QPromise<Sequence<T>>
+
+// With:
+// - Sequence: STL compatible container (e.g. QVector, etc.)
+// - Filterer: Function(T value, int index) -> bool
+```
+
+Iterates over `values` and [filters the sequence](https://en.wikipedia.org/wiki/Filter_%28higher-order_function%29)
+to another using the given `filterer` function. If `filterer` returns `true`, a copy of the item
+is put in the `output` sequence, otherwise, the item will not appear in  `output`. If `filterer`
+throws, `output` is rejected with the new exception.
+
+If `filterer` returns a promise (or `QFuture`), the `output` promise is delayed until all the
+promises are resolved. If any of the promises fail, `output` immediately rejects with the error
+of the promise that rejected, whether or not the other promises are resolved.
+
+```cpp
+auto output = QtPromise::filter(QVector{
+    QUrl("http://a..."),
+    QUrl("http://b..."),
+    QUrl("http://c...")
+}, [](const QUrl& url, ...) {
+    return QPromise<bool>([&](auto resolve, auto reject) {
+        // resolve(true) if 'url' is reachable, else resolve(false)
+        // {...}
+    });
+});
+
+// 'output' resolves as soon as all promises returned by
+// 'filterer' are fulfilled or at least one is rejected.
+
+// 'output' type: QPromise<QVector<QUrl>>
+output.then([](const QVector<QUrl>& res) {
+    // 'res' contains only reachable URLs
+});
+```
+
+> **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 `filterer`.
+
+See also: [`QPromise<T>::filter`](../qpromise/filter.md)

docs/qtpromise/qpromise/filter.md

@@ -0,0 +1,45 @@
+## `QPromise<Sequence<T>>::filter`
+
+> **Important:** applies only to promise with sequence value.
+
+```cpp
+QPromise<Sequence<T>>::filter(Filter filterer) -> QPromise<Sequence<T>>
+
+// With:
+// - Sequence: STL compatible container (e.g. QVector, etc.)
+// - Filterer: Function(T value, int index) -> bool
+```
+
+Iterates over all the promise values (i.e. `Sequence<T>`) and [filters the sequence](https://en.wikipedia.org/wiki/Filter_%28higher-order_function%29)
+to another using the given `filterer` function. If `filterer` returns `true`, a copy of the item
+is put in the `output` sequence, otherwise, the item will not appear in  `output`. If `filterer`
+throws, `output` is rejected with the new exception.
+
+If `filterer` returns a promise (or `QFuture`), the `output` promise is delayed until all the
+promises are resolved. If any of the promises fail, `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.filter([](const QUrl& url, ...) {
+    return url.isValid();  // Keep only valid URLs
+}).filter([](const QUrl& url, ...) {
+    return QPromise<bool>([&](auto resolve, auto reject) {
+        // resolve(true) if `url` is reachable, else resolve(false)
+    });
+});
+
+// 'output' resolves as soon as all promises returned by
+// 'filterer' are fulfilled or at least one is rejected.
+
+// 'output' type: QPromise<QList<QUrl>>
+output.then([](const QList<QUrl>& res) {
+    // 'res' contains only reachable URLs
+});
+```
+
+> **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 `filterer`.
+
+See also: [`QtPromise::filter`](../helpers/filter.md)