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.
For serialization and parsing, distinguishing enums with numeric values
from enums with associated strings for each value is useful. This adds
foundational helpers to allow such distinction.
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
```
* Add API call from a (slight) future 1.6 branch with when guards to
deactivate as per claim here
https://github.com/status-im/nim-codex/pull/346#issuecomment-1432073926
that this (or something very near it) is where it belongs.
* I also cannot find any `shims/parse` import. See discussion here:
https://github.com/status-im/nim-stew/pull/173
So, rename module to match upstream Nim stdlib.
If anyone complains, re-create `parse.nim` that simply does import
& re-export parseutils & self-deprecates.
The lock file breaks devel testing - CI updates are needed as well as a
strategy for handling "nim important packages" builds (which build with
a version of Nim different from that in the lock file)
Jacek Sieka
andri lim
tersec
Etan Kissling
diegomrsantos
c-blake
Eugene Kabanov
Miran
Jordan Hrycaj
Bung
Zahary Karadjov
Tanguy
Lorenzo Delgado