v1: hint (CXX-3237, CXX-3238)

[eramongodb]

Resolves CXX-3237 and CXX-3238 for the v1::hint component.

---

To document/explain why v_noabi::hint is not refactored in terms of v1::hint (and similar classes with "transitive view accessors" in upcoming PRs): attempting to do so exposes violations of the "The caller must ensure that the returned object not outlive the hint object that it was created from" contract for the .to_value() accessor in collection test code (which is nevertheless "fixed" by this PR, even though the behavior continues to be supported):

bsoncxx::v_noabi::types::view t;

{
  hint h{"abc"};    // Stored as a view.
  t = h.to_value(); // Copied as a view.
} // `h` is destroyed, but the view of the "abc" string literal remains valid.

CHECK(t == bsoncxx::v_noabi::types::b_string{"abc"}); // OK...? :(

Despite being within our rights given the existing public API documentation to enforce this lifetime requirement, it is likely too risky to enforce this behavior and potentially break users (by undefined behavior!) who are (knowingly or unknowingly) taking advantage of this "view outlives the intermediate object" behavior (by Hyrum's Law). Therefore, v_noabi::hint can only support v_noabi <-> v1 conversions (e.g. as done for v_noabi::options::data_key and v_noabi::options::tls). (Note: we could consider enforcing this postcondition by adding new k_invalid_<object> exceptions to the v_noabi API, but this is also likely to be an API breaking change too disruptive to justify in a non-major release.)

This "transitive view accessor" backward compatibility problem also applies to other classes with both view_or_value accessors (although only v_noabi::hint publically documents that the hint object must outlive the maybe-views returned by the class). Such classes will also only implement v_noabi <-> v1 conversion support only without an implementation refactor.

[kevinAlbs]

even though the behavior continues to be supported

Good catch. I agree with preserving the behavior (despite documentation) to avoid potentially breaking existing code.

[kevinAlbs]

Suggested change

	/// @return Hint, as a types::view. The caller must ensure that the returned object

To match return type.

[eramongodb]

Updated both code and docs to consistently use bsoncxx::v_noabi::types::view.

[kevinAlbs]

Suggested change

	/// @return Hint, as a types::view. The caller must ensure that the returned object

To match return type.