Create a new `__capacity_aware_iterator` iterator type which wraps an
existing iterator, takes its container as a template parameter, and
encodes the maximum amount of elements the container can hold. The main
objective is to prevent iterator mixups between different containers
(e.g. `vector`).
We haven't yet decided what we want the `optional::iterator` type to be
in the end, so let's make it experimental for now so that we don't
commit to an ABI yet.
Resolves#171345
Implements [proposed resolution for
LWG4308](https://cplusplus.github.io/LWG/issue4308) and removes
`const_iterator` from `optional<T&>`, which was missed.
- Constrains iterator to only be available if T is not an lvalue
reference, or if it is T&, that T is an object type and is not an
unbounded array
- Add a partial specialization for `__optional_iterator` for `T&`, which
only has the `iterator` type.
- Correct a static assert message as a drive-by
- Move the libcxx specific iterator test into the standard test because
the standard now specifies when the iterator should be available
Resolves#148131
- Unlock `std::optional<T&>` implementation
- Allow instantiations of `optional<T(&)(...)>` and `optional<T(&)[]>`
but disables `value_or()` and `optional::iterator` + all `iterator`
related functions
- Update documentation
- Update tests
Resolves#105430
- Implement all required pieces of P3168R2
- Leverage existing `wrap_iter` and `bounded_iter` classes to implement
the `optional` regular and hardened iterator type, respectively
- Update documentation to match
