Since the results package has seen "stable" use for quite a while now,
it's as good time a time as any to release 1.0 and migrate it out of
stew, thus signalling API stability of some sort.
Part of that "stabilization" is underway in the nim-results [issue
tracker](https://github.com/arnetheduck/nim-results/issues/30).
We already have `mapConvert` and `mapCast` - this completes the API with
corresponding `Err` versions similar to `mapErr`.
The `Convert` / `Cast` operators are of somewhat dubious value - ie
they exist as "efficiency" shortcuts for `map` for the case that the
mapping should be done as a simple cast / conversion - an alternative
would be to deprecate these features and aim for some other, more
generic version that involves a type conversion library such as
https://github.com/status-im/nim-stew/pull/34, though this inherently,
and perhaps rightly, would be limited to "error-free" conversions.
Regardless, these helpers provide balance to the existing API.
Nim emits `ProveField` warnings with `if` on case object discriminator.
Replace with `case` instead to avoid those warnings.
Note we currently have `ProveField` disabled but it keeps showing up
sometimes when compiling with `nim c` instead of `make`.
This set of helpers allows treating Result and Opt as collections of 0
or 1 item, allowing iterating over them and checking "membership" - such
integration is useful in generic code which can then be generalised to
handle more complex cases - the integration is most useful with Opt.
One design tradeoff here is the "explicitness" of `items` vs `values`
for `Result` - technically error and value are "equal" and therefore we
shouldn't give preference to the value, but there exists a convenience
argument to treat the value as the "default" and therefore define
`items` / `contains` for `Result` as well - this PR chooses the more
conservative and explicit approach - a more liberal version can easily
be added later should motivating examples emerge.
Add `optError`, `optValue`, to convert back and forth between Opt and Result
These conversions end up being more common than others since "trivial" success/fail-style API often use Opt while combining such API into combined operations tends to prefer richer error reporting.
These two helpers complete `valueOr` and `errorOr` to cover `void` cases
where no value should be returned or `Result[void, E]` /
`Result[T, void]` is being used - they can be used for a convient
early-return style in side-effectful proc:s:
```nim
v.update().isOkOr:
echo "update failed: ", error
```
* `Result` refresh
* add full support for `Result[T, void]` (aka `Opt[T]` aka `Option[T]`)
* expand tests
* add `flatten`, `filter` of `Option` fame
* add `tryError` that raises a regular exception when result holds a
value
* fix `$` to print `ok`/`err` in lower-case, like the functions that
created the result
* add `orErr` that collapses all errors to a single value of a
potentially different type - useful when translating errors between
layers
* `capture` should work with `CatchableError`
* remove `Defect`-dependent tests
* Update stew/results.nim
* avoid redundant error message when converting error to string
* avoid multiple evaluation in `valueOr`
* add `unsafeError` to match `unsafeGet`
* let `valueOr` evaluate a block
* add `errorOr` to mirror `valueOr`
It turned out that Nim's Option type is broken for `not nil` and
`requiresInit` types. It will report an udesired warning due to
the way `none` is defined. The `Result` type doesn't suffer from
this problem, so I've transitioned some APIs in NBC to use the
new `results.Opt[T]` type (alias of `Result[T, void]`).
Perhaps we should renamed `Result` to `Res` to make the naming
more consistent and to allow the code to more easily fit in the
80 character per-line budget.
