amass/qtpromise
1
0
Fork 0
mirror of https://github.com/simonbrunel/qtpromise.git synced 2025-01-23 04:14:38 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Make docs formatting consistent (no explicit word wrap)

Browse Source
This commit is contained in:
Simon Brunel 2019-02-23 14:32:02 +01:00
parent 700098ef7b
commit 63acdfaab9
11 changed files with 25 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
docs/qtpromise/exceptions/canceled.md
View File

@ -6,9 +6,7 @@ title: QPromiseCanceledException
*Since: 0.1.0* *Since: 0.1.0*
This exception is thrown for promise created from a [`QFuture`](../qtconcurrent.md) This exception is thrown for promise created from a [`QFuture`](../qtconcurrent.md) which has been canceled (e.g. using [`QFuture::cancel()`](http://doc.qt.io/qt-5/qfuture.html#cancel)), for example:
which has been canceled (e.g. using [`QFuture::cancel()`](http://doc.qt.io/qt-5/qfuture.html#cancel)).
Note that QtPromise doesn't support promise cancelation yet. For example:
```cpp ```cpp
auto output = qPromise(future) auto output = qPromise(future)
@ -17,3 +15,6 @@ auto output = qPromise(future)
}); });
``` ```
::: tip NOTE
QtPromise doesn't support promise cancelation (yet?)
:::

3
docs/qtpromise/exceptions/timeout.md
View File

@ -6,8 +6,7 @@ title: QPromiseTimeoutException
*Since: 0.2.0* *Since: 0.2.0*
This is the default exception thrown when reaching the time limit when using This is the default exception thrown when reaching the time limit when using the [`QPromise::timeout()`](../qpromise/timeout.md) method, for example:
the [`QPromise::timeout()`](../qpromise/timeout.md) method, for example:
```cpp ```cpp
QPromise<int> input = {...} QPromise<int> input = {...}

3
docs/qtpromise/exceptions/undefined.md
View File

@ -6,8 +6,7 @@ title: QPromiseUndefinedException
*Since: 0.5.0* *Since: 0.5.0*
This exception is thrown when rejecting a promise with no explicit reason, for This exception is thrown when rejecting a promise with no explicit reason, for example:
example:
```cpp ```cpp
QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReject<int>& reject) { QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReject<int>& reject) {

9
docs/qtpromise/helpers/attempt.md
View File

@ -13,14 +13,9 @@ QtPromise::attempt(Functor functor, Args...) -> QPromise<R>
// - Functor: Function(Args...) -> R | QPromise<R> // - Functor: Function(Args...) -> R | QPromise<R>
``` ```
Calls `functor` immediately and returns a promise fulfilled with the value returned by Calls `functor` immediately and returns a promise fulfilled with the value returned by `functor`. Any synchronous exceptions will be turned into rejections on the returned promise. This is a convenient method that can be used instead of handling both synchronous and asynchronous exception flows.
`functor`. Any synchronous exceptions will be turned into rejections on the returned
promise. This is a convenient method that can be used instead of handling both synchronous
and asynchronous exception flows.
The type `R` of the `output` promise depends on the type returned by the `functor` function. The type `R` of the `output` promise depends on the type returned by the `functor` function. If `functor` returns a promise (or `QFuture`), the `output` promise is delayed and will be resolved by the returned promise.
If `functor` returns a promise (or `QFuture`), the `output` promise is delayed and will be
resolved by the returned promise.
```cpp ```cpp
QPromise<QByteArray> download(const QUrl& url); QPromise<QByteArray> download(const QUrl& url);

8
docs/qtpromise/helpers/each.md
View File

@ -14,13 +14,9 @@ QtPromise::each(Sequence<T> values, Functor functor) -> QPromise<Sequence<T>>
// - Functor: Function(T value, int index) -> void | QPromise<void> // - Functor: Function(T value, int index) -> void | QPromise<void>
``` ```
Calls the given `functor` on each element in `values` then resolves to the original sequence Calls the given `functor` on each element in `values` then resolves to the original sequence unmodified. If `functor` throws, `output` is rejected with the new exception.
unmodified. If `functor` throws, `output` is rejected with the new exception.
If `functor` 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.
If `functor` 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 ```cpp
auto output = QtPromise::each(QVector<QUrl>{ auto output = QtPromise::each(QVector<QUrl>{

12
docs/qtpromise/helpers/filter.md
View File

@ -14,14 +14,9 @@ QtPromise::filter(Sequence<T> values, Filterer filterer) -> QPromise<Sequence<T>
// - Filterer: Function(T value, int index) -> bool // - Filterer: Function(T value, int index) -> bool
``` ```
Iterates over `values` and [filters the sequence](https://en.wikipedia.org/wiki/Filter_%28higher-order_function%29) 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.
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 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.
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 ```cpp
auto output = QtPromise::filter(QVector{ auto output = QtPromise::filter(QVector{
@ -45,8 +40,7 @@ output.then([](const QVector<QUrl>& res) {
``` ```
::: tip NOTE ::: tip NOTE
The order of the output sequence values is guarantee to be the same as the original 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`.
sequence, regardless of completion order of the promises returned by `filterer`.
::: :::
See also: [`QPromise<T>::filter`](../qpromise/filter.md) See also: [`QPromise<T>::filter`](../qpromise/filter.md)

11
docs/qtpromise/helpers/map.md
View File

@ -14,13 +14,9 @@ QtPromise::map(Sequence<T> values, Mapper mapper) -> QPromise<QVector<R>>
// - Mapper: Function(T value, int index) -> R | QPromise<R> // - 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) 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.
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 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.
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 ```cpp
auto output = QtPromise::map(QVector{ auto output = QtPromise::map(QVector{
@ -44,8 +40,7 @@ output.then([](const QVector<QByteArray>& res) {
``` ```
::: tip NOTE ::: tip NOTE
The order of the output sequence values is guarantee to be the same as the original 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`.
sequence, regardless of completion order of the promises returned by `mapper`.
::: :::
See also: [`QPromise<T>::map`](../qpromise/map.md) See also: [`QPromise<T>::map`](../qpromise/map.md)

4
docs/qtpromise/qpromise/constructor.md
View File

@ -40,9 +40,7 @@ QPromise<int> promise([](const auto& resolve, const auto& reject) {
*Since: 0.5.0* *Since: 0.5.0*
While not recommended because it makes tracking errors more difficult, it's also While not recommended because it makes tracking errors more difficult, it's also possible to reject a promise without explicit reason, in which case, a built-in [`QPromiseUndefinedException`](../exceptions/undefined.md) is thrown:
possible to reject a promise without explicit reason, in which case, a built-in
[`QPromiseUndefinedException`](../exceptions/undefined.md) is thrown:
```cpp ```cpp
QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReject<int>& reject) { QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReject<int>& reject) {

12
docs/qtpromise/qpromise/filter.md
View File

@ -18,14 +18,9 @@ QPromise<Sequence<T>>::filter(Filter filterer) -> QPromise<Sequence<T>>
This method only applies to promise with sequence value. This method only applies to promise with sequence value.
::: :::
Iterates over all the promise values (i.e. `Sequence<T>`) and [filters the sequence](https://en.wikipedia.org/wiki/Filter_%28higher-order_function%29) 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.
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 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.
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 ```cpp
QPromise<QList<QUrl>> input = {...} QPromise<QList<QUrl>> input = {...}
@ -48,8 +43,7 @@ output.then([](const QList<QUrl>& res) {
``` ```
::: tip NOTE ::: tip NOTE
The order of the output sequence values is guarantee to be the same as the original 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`.
sequence, regardless of completion order of the promises returned by `filterer`.
::: :::
See also: [`QtPromise::filter`](../helpers/filter.md) See also: [`QtPromise::filter`](../helpers/filter.md)

11
docs/qtpromise/qpromise/map.md
View File

@ -18,13 +18,9 @@ QPromise<Sequence<T>>::map(Mapper mapper) -> QPromise<QVector<R>>
This method only applies to promise with sequence value. This method only applies to promise with sequence value.
::: :::
Iterates over all the promise values (i.e. `Sequence<T>`) and [maps the sequence](https://en.wikipedia.org/wiki/Map_%28higher-order_function%29) 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.
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 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.
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 ```cpp
QPromise<QList<QUrl>> input = {...} QPromise<QList<QUrl>> input = {...}
@ -50,8 +46,7 @@ output.then([](const QVector<DownloadResult>& res) {
``` ```
::: tip NOTE ::: tip NOTE
The order of the output sequence values is guarantee to be the same as the original 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`.
sequence, regardless of completion order of the promises returned by `mapper`.
::: :::
This function is provided for convenience and is similar to: This function is provided for convenience and is similar to:

8
docs/qtpromise/qpromise/then.md
View File

@ -24,9 +24,7 @@ auto output = input.then([](int res) {
``` ```
::: tip NOTE ::: tip NOTE
`onRejected` handler is optional, in which case `output` will be rejected with `onRejected` handler is optional, in which case `output` will be rejected with the same reason as `input`. Also note that it's recommended to use the [`fail`](fail.md) shorthand to handle errors.
the same reason as `input`. Also note that it's recommended to use the
[`fail`](fail.md) shorthand to handle errors.
::: :::
The type `<R>` of the `output` promise depends on the return type of the `onFulfilled` handler: The type `<R>` of the `output` promise depends on the return type of the `onFulfilled` handler:
@ -44,9 +42,7 @@ output.then([](const QString& res) {
``` ```
::: tip NOTE ::: tip NOTE
Only `onFulfilled` can change the promise type, `onRejected` **must** return the Only `onFulfilled` can change the promise type, `onRejected` **must** return the same type as `onFulfilled`. That also means if `onFulfilled` is `nullptr`, `onRejected` must return the same type as the `input` promise.
same type as `onFulfilled`. That also means if `onFulfilled` is `nullptr`,
`onRejected` must return the same type as the `input` promise.
::: :::
```cpp ```cpp