CXX-3232 add bsoncxx v1 declarations

[eramongodb]

Resolves CXX-3232. Followup to #1318, #1401, and #1402.

This is 2 out of an estimated 7 major PRs which in total are expected to resolve CXX-2745 and CXX-3320.

• Top-Level Dependencies (CXX-3239)
• bsoncxx v1 Interfaces (CXX-3232) (<-- you are here)
• bsoncxx v1 Implementations (CXX-3233)
• bsoncxx v_noabi Refactor (CXX-3234)
• mongocxx v1 Interfaces (CXX-3236)
• mongocxx v1 Implementations (CXX-3237)
• mongocxx v_noabi Refactor (CXX-3238)

This PR introduces the very first set of v1 ABI exported symbols. 🎉

... only because MSVC complains otherwise. The rest will come as planned in CXX-3233 (impls).

---

Due to the volume of changes relative to the equivalent v_noabi interfaces, the bulk of relative changelog (v_noabi -> v1) and rationale for design decisions are documented inline as GitHub comments (coincidentally, exactly 100 comments in total).

In summary, notable changes include:

• General Notes
  • Nearly all preconditions are now documented and well-defined to instead throw an exception or yield an "invalid" state.
  • Narrowing casts and discarded return values are now thoroughly accounted for as new error codes.
  • All potentially-thrown exceptions are now documented and include the list of error codes which may be thrown.
• v1::error v1::<class>::errc
  • All exceptions thrown by library components have a corresponding error code enumeration declared in v1::error v1::<class>::errc with corresponding error category v1::<class>::error_category.
  • Error conditions source_errc and type_errc are provided as the primary user-facing error code query mechanism when component-specific error codes are not necessary.
• v1::types::b_*
  • All types are now consistently non-aggregate for list-initialization consistency.
  • All "single underlying value" types now consistently support implicit conversion to said value.
  • Multi-argument constructors are no longer explicit (always favored over value).
• v1::types::view
  • This type is now semitrivial (no user-provided non-default special member functions).
  • Conversion to this type is now favored over conversion to value when applicable.
• v1::types::value
  • All (non-default) constructors are now explicit (b_* is always favored) so either b_* or view (cheap) is always preferred to value (expensive) when applicable.
  • v1::types::id constructors are removed in favor of b_* and converting constructors.
  • "Inline PIMPL" avoids redundant allocation while preserving encapsulation.
• v1::element::view
  • The "invalid" state is now clarified and thoroughly documented.
  • "Inline PIMPL" leaves room for an alternative bool-based approach to "missing field" diagnostics (CXX-2120).
  • Although not semitrivial, the class is still nothrow copyable.
  • Equality comparison is defined as "same field in same BSON binary data". Relational comparison is also possible but deferred for now. Reverted.
• v1::document::view
  • Now supports an "invalid" state without underlying BSON binary data.
• v1::array::view
  • Now (nearly) completely defined in terms of v1::document::view.
  • API is extended for better parity with v1::document::view (CXX-2118).
• v1::document::value
  • Now default-constructible (CXX-939), equivalent to an "invalid" a default-initialized v1::document::view with no allocation.
  • deleter_type is now a std::function<T> instead of a function pointer.
  • Customization points for to_bson and from_bson are now properly constrained.
• v1::array::value
  • Now (nearly) completely defined in terms of v1::document::value.
  • API is extended for better parity with v1::document::view (CXX-2118).

[kevinAlbs]

The bsoncxx ABI v1 interfaces look well researched, and I really like the efforts towards better defining expected exceptions / minimizing preconditions.

[eramongodb]

Suggestions applied. Open questions following first round of review include:

• Should compile-time constants be defined as enum constants (not exported in the ABI) instead of static constexpr variables (exported in the ABI due to pre-C++17 compatibility requirements)?
• Should v1::document::value::view() return an "empty doc" view instead of an invalid view without otherwise changing its allocation behavior (_data.get() == nullptr)? Feedback: no.
• Should v1::document::value continue to support implicit assignment from a v1::document::view (currently requires doc = value{view};)? Feedback: no.

[kevinAlbs]

(Sorry I thought I posted comments as a review before). Latest changes LGTM with a request to restore a view constructor accepting a length (for safer migration). I support removing __cdecl.

[vector-of-bool]

LGTM, the only remaining comments are relatively small things.

[eramongodb]

@vector-of-bool re-requesting review to confirm the applied changes (moving error codes and categories into class members) and response to latest feedback are in line with expectations.

[vector-of-bool]

LGTM, with one last (lengthy and rambling) remark about datetime encoding.