CXX-2745 add aliases and deprecations for v1 renames (#1463)

Author: eramongodb

CHANGELOG.md

@@ -9,6 +9,16 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
 
 ## 4.2.0 [Unreleased]
 
+### Added
+
+* To support incremental migration, the following entities are defined as equivalent to their renamed counterparts.
+  - `bsoncxx::types::id`: equivalent to `bsoncxx::type`.
+  - `bsoncxx::types::binary_subtype`: equivalent to `bsoncxx::binary_sub_type`.
+  - `bsoncxx::types::view`: equivalent to `bsoncxx::types::bson_value::view`.
+  - `bsoncxx::types::value`: equivalent to `bsoncxx::types::bson_value::value`.
+  - `type_view()` in `bsoncxx::document::element` and `bsoncxx::array::element`: equivalent to `get_value()`.
+  - `type_value()` in `bsoncxx::document::element` and `bsoncxx::array::element`: equivalent to `get_owning_value()`.
+
 ### Fixed
 
 - CMake option `ENABLE_TESTS` (`OFF` by default) is no longer overwritten by the auto-downloaded C Driver (`ON` by default) during CMake configuration.
@@ -46,6 +56,13 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
       return instance;
     }
     ```
+- These following entities will be renamed (and removed) in an upcoming major release. To support incremental migration, both old and new names are still provided.
+  - `bsoncxx::type` -> `bsoncxx::types::id`.
+  - `bsoncxx::binary_sub_type` -> `bsoncxx::types::binary_subtype`.
+  - `bsoncxx::types::bson_value::view` -> `bsoncxx::types::view`
+  - `bsoncxx::types::bson_value::value` -> `bsoncxx::types::value`
+  - `get_value()` -> `type_view()` in `bsoncxx::document::element` and `bsoncxx::array::element`.
+  - `get_owning_value()` -> `type_value()` in `bsoncxx::document::element` and `bsoncxx::array::element`.
 
 ### Removed
 
@@ -69,7 +86,6 @@ Changes prior to 3.9.0 are documented as [release notes on GitHub](https://githu
 - Static pkg-config files are updated to depend on the static (not shared) libbson / libmongoc packages.
 - Fix build if macros `GCC`/`GNU`/`Clang`/`MSVC` are already defined.
 
-
 ## 4.1.0
 
 ### Fixed

src/bsoncxx/include/bsoncxx/docs/top.hpp

@@ -88,6 +88,8 @@
 /// @namespace bsoncxx::types::bson_value
 /// Declares entities representing any BSON value type.
 ///
+/// @deprecated Use @ref bsoncxx::types instead (renamed).
+///
 
 ///
 /// @namespace bsoncxx::vector

src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp

@@ -95,6 +95,8 @@
 /// @dir bsoncxx/v_noabi/bsoncxx/types/bson_value
 /// Provides headers declaring entities in @ref bsoncxx::v_noabi::types::bson_value.
 ///
+/// @deprecated Use @ref bsoncxx/types/view.hpp or @ref bsoncxx/types/value.hpp instead.
+///
 
 ///
 /// @dir bsoncxx/v_noabi/bsoncxx/vector
@@ -153,6 +155,8 @@
 /// @namespace bsoncxx::v_noabi::types::bson_value
 /// Declares entities representing any BSON value type.
 ///
+/// @deprecated Use @ref bsoncxx::v_noabi::types instead (renamed).
+///
 
 ///
 /// @namespace bsoncxx::v_noabi::vector

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/element.hpp

@@ -73,6 +73,10 @@ class element : private v_noabi::document::element {
 
     using v_noabi::document::element::get_owning_value;
 
+    using v_noabi::document::element::type_view;
+
+    using v_noabi::document::element::type_value;
+
     using v_noabi::document::element::operator[];
 
     friend bool operator==(element const& lhs, v_noabi::types::bson_value::view const& rhs);

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/document/element.hpp

@@ -155,6 +155,8 @@ class element {
     /// Getter for a types::bson_value::view variant wrapper of the value portion of the
     /// element.
     ///
+    /// @deprecated Use @ref type_view() const instead (renamed).
+    ///
     /// @return the element's value.
     ///
     BSONCXX_ABI_EXPORT_CDECL(v_noabi::types::bson_value::view) get_value() const;
@@ -163,10 +165,26 @@ class element {
     /// Getter for a types::bson_value::value variant wrapper of the value portion of
     /// the element. The returned object will make a copy of the buffer from this object.
     ///
+    /// @deprecated Use @ref type_value() const instead (renamed).
+    ///
     /// @return an owning version of the element's value.
     ///
     BSONCXX_ABI_EXPORT_CDECL(v_noabi::types::bson_value::value) get_owning_value() const;
 
+    ///
+    /// Equivalent to @ref get_value() const.
+    ///
+    /// To support incremental migration to @ref bsoncxx::v1::element::view::type_view() const.
+    ///
+    BSONCXX_ABI_EXPORT_CDECL(v_noabi::types::bson_value::view) type_view() const;
+
+    ///
+    /// Equivalent to @ref get_owning_value() const.
+    ///
+    /// To support incremental migration to @ref bsoncxx::v1::element::view::type_value() const.
+    ///
+    BSONCXX_ABI_EXPORT_CDECL(v_noabi::types::bson_value::value) type_value() const;
+
     ///
     /// If this element is a document, finds the first element of the document
     /// with the provided key. If there is no such element, an invalid

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/oid.hpp

@@ -122,6 +122,13 @@ class oid {
         return reinterpret_cast<char const*>(_oid.bytes());
     }
 
+    ///
+    /// Equivalent to [`bson_oid_compare`](https://mongoc.org/libbson/current/bson_oid_compare.html).
+    ///
+    int compare(oid const& other) const {
+        return _oid.compare(other._oid);
+    }
+
     ///
     /// @relates bsoncxx::v_noabi::oid
     ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types-fwd.hpp

@@ -33,6 +33,20 @@ namespace bsoncxx {
 namespace v_noabi {
 namespace types {
 
+///
+/// Equivalent to @ref bsoncxx::v_noabi::type.
+///
+/// To support incremental migration to @ref bsoncxx::v1::types::id.
+///
+using id = v_noabi::type;
+
+///
+/// Equivalent to @ref bsoncxx::v_noabi::binary_sub_type.
+///
+/// To support incremental migration to @ref bsoncxx::v1::types::binary_subtype.
+///
+using binary_subtype = v_noabi::binary_sub_type;
+
 struct b_double;
 struct b_string;
 struct b_document;
@@ -69,6 +83,9 @@ using v_noabi::type;
 namespace bsoncxx {
 namespace types {
 
+using v_noabi::types::binary_subtype;
+using v_noabi::types::id;
+
 using v_noabi::types::b_array;
 using v_noabi::types::b_binary;
 using v_noabi::types::b_bool;
@@ -100,6 +117,8 @@ using v_noabi::types::b_undefined;
 /// @file
 /// Declares entities used to represent BSON types.
 ///
+/// @deprecated Use @ref bsoncxx/types/id-fwd.hpp or @ref bsoncxx/types/view-fwd.hpp instead.
+///
 /// @par Includes
 /// - @ref bsoncxx/v1/types/view-fwd.hpp
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types.hpp

@@ -42,6 +42,8 @@ namespace v_noabi {
 ///
 /// @showenumvalues
 ///
+/// @deprecated Use @ref bsoncxx::v_noabi::types::id instead (renamed).
+///
 enum class type : std::uint8_t {
     k_double = 0x01,     ///< 64-bit binary floating point.
     k_string = 0x02,     ///< UTF-8 string.
@@ -71,6 +73,8 @@ enum class type : std::uint8_t {
 ///
 /// @showenumvalues
 ///
+/// @deprecated Use @ref bsoncxx::v_noabi::types::binary_subtype instead (renamed).
+///
 enum class binary_sub_type : std::uint8_t {
     k_binary = 0x00,            ///< Generic binary subtype.
     k_function = 0x01,          ///< Function.
@@ -1105,6 +1109,8 @@ using v_noabi::types::operator!=;
 /// @file
 /// Provides entities used to represent BSON types.
 ///
+/// @deprecated Use @ref bsoncxx/types/id.hpp or @ref bsoncxx/types/view.hpp instead.
+///
 /// @par Includes
 /// - @ref bsoncxx/v1/types/view.hpp
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value-fwd.hpp

@@ -27,7 +27,12 @@ class value;
 
 } // namespace bson_value
 
-using bson_value::value;
+///
+/// Equivalent to @ref bsoncxx::v_noabi::types::bson_value::value.
+///
+/// To support incremental migration to @ref bsoncxx::v1::types::value.
+///
+using value = bson_value::value;
 
 } // namespace types
 } // namespace v_noabi
@@ -41,7 +46,7 @@ using v_noabi::types::bson_value::value;
 
 } // namespace bson_value
 
-using bson_value::value;
+using v_noabi::types::value;
 
 } // namespace types
 } // namespace bsoncxx
@@ -52,6 +57,8 @@ using bson_value::value;
 /// @file
 /// Declares @ref bsoncxx::v_noabi::types::bson_value::value.
 ///
+/// @deprecated Use @ref bsoncxx/types/value-fwd.hpp instead (renamed).
+///
 /// @par Includes
 /// - @ref bsoncxx/v1/types/value-fwd.hpp
 ///

src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp

@@ -49,6 +49,8 @@ namespace bson_value {
 /// For accessors into this type and to extract the various BSON types out,
 /// please use bson_value::view.
 ///
+/// @deprecated Use @ref bsoncxx::v_noabi::types::value instead (renamed).
+///
 /// @see
 /// - @ref bsoncxx::v_noabi::types::bson_value::view
 ///
@@ -254,7 +256,7 @@ class value {
     /// @throws bsoncxx::v_noabi::exception if the type's value is not k_maxkey, k_minkey, or
     /// k_undefined.
     ///
-    /* explicit(false) */ BSONCXX_ABI_EXPORT_CDECL() value(type const id);
+    /* explicit(false) */ BSONCXX_ABI_EXPORT_CDECL() value(v_noabi::type const id);
 
     ///
     /// Constructs one of the following BSON values (each specified by the parenthesized type):
@@ -297,6 +299,24 @@ class value {
         return _value;
     }
 
+    ///
+    /// Returns the type of the underlying BSON value stored in this object.
+    ///
+    /// @deprecated Use @ref type_id() const instead (renamed).
+    ///
+    v_noabi::type type() const {
+        return this->view().type();
+    }
+
+    ///
+    /// Equivalent to @ref type() const.
+    ///
+    /// To support incremental migration to @ref bsoncxx::v1::types::value.
+    ///
+    v_noabi::type type_id() const {
+        return this->view().type_id();
+    }
+
     ///
     /// Get a view over the bson_value owned by this object.
     ///
@@ -310,6 +330,25 @@ class value {
     /* explicit(false) */ operator v_noabi::types::bson_value::view() const noexcept {
         return _value.view();
     }
+
+#pragma push_macro("X")
+#undef X
+#define X(_name, _value)                                   \
+    v_noabi::types::b_##_name const& get_##_name() const { \
+        return this->view().get_##_name();                 \
+    }
+
+    ///
+    /// Return the underlying BSON type value.
+    ///
+    /// @warning
+    ///   Calling the wrong get_<type> method will cause an exception to be thrown.
+    ///
+    /// @{
+    BSONCXX_V1_TYPES_XMACRO(X)
+    /// @}
+    ///
+#pragma pop_macro("X")
 };
 
 ///
@@ -400,6 +439,8 @@ using v_noabi::types::bson_value::operator!=;
 /// @file
 /// Provides @ref bsoncxx::v_noabi::types::bson_value::value.
 ///
+/// @deprecated Use @ref bsoncxx/types/value.hpp instead (renamed).
+///
 /// @par Includes
 /// - @ref bsoncxx/v1/types/value.hpp
 ///