feat: introduce `first_opt()`, `first_key_opt()`, `last_opt()`, `last_key_opt()` and `search_opt()`

[simPod]

I'd like to modify search operations over iterables by wrapping the result in Option.

Currently, it is not possible to use these functions to find null value since null represents "no result".

This applies to all first*, last* and search functions.

WDYT?

[azjezz]

I like the idea of returning an Option, but i dislike having this type of BC, what about adding new functions that result in an Option? e.g first_opt<T>(iterable<T> $i): Option<T> vs first<T>(iterable<T> $I): null|T?

_opt suffix is one way to go about this ( this is a popular choice in the rust community, e.g: https://docs.rs/chrono/latest/chrono/struct.Date.html#method.and_hms_micro VS https://docs.rs/chrono/latest/chrono/struct.Date.html#method.and_hms_micro_opt), but i'm open to suggestions if you have any, maybe we can find a more suitable naming convention for those functions.

cc @veewee this might interest you.

[simPod]

I'll go for it. Thanks for input.

[veewee]

@azjezz

The migration path might be better this way indeed. However you'll probably end up to something that looks like this in the long run, which might be something we'dd want to avoid?

• v3 -> deprecate old API in favour for _opt
• v4 -> remove old API
• v5 -> Recreate original function without the _opt suffix and deprecate the _opt suffix functions
• v6 -> remove the _opt functions again

[azjezz]

@veewee personally i would like to keep both, i don't see why we need to deprecate/remove the old behaviour.

[coveralls]

Pull Request Test Coverage Report for Build 8953186695

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 18 of 18 (100.0%) changed or added relevant lines in 5 files are covered.
• No unchanged relevant lines lost coverage.
• Overall coverage increased (+0.01%) to 98.792%

---

Totals
Change from base Build 8832169884:	0.01%
Covered Lines:	4415
Relevant Lines:	4469

---

💛 - Coveralls