Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eramongodb merged 6 commits into from
Sep 17, 2025
Merged

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

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9d7c6a0
CXX-2745 add aliases and deprecations for v1 renames
eramongodb Sep 17, 2025
8d24fd9
Remove `v_noabi::types::value::type() const` due to GCC compatibility
eramongodb Sep 17, 2025
7362532
Fix include directive substitution typo
eramongodb Sep 17, 2025
796373a
Revert "Remove `v_noabi::types::value::type() const` due to GCC compa…
eramongodb Sep 17, 2025
ab3e030
Add v_noabi:: qualifier to ctor param decl
eramongodb Sep 17, 2025
5f210c7
Fix typos
eramongodb Sep 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::document::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.
Expand Down Expand Up @@ -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::document::element`.

### Removed

Expand All @@ -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
Expand Down
2 changes: 2 additions & 0 deletions src/bsoncxx/include/bsoncxx/docs/top.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/bsoncxx/include/bsoncxx/docs/v_noabi.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down
4 changes: 4 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/array/element.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
18 changes: 18 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/document/element.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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
Expand Down
7 changes: 7 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/oid.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down
19 changes: 19 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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
///
6 changes: 6 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
///
11 changes: 9 additions & 2 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
///
43 changes: 42 additions & 1 deletion src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/value.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
Expand Down Expand Up @@ -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):
Expand Down Expand Up @@ -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::view.
Copy link
Collaborator

@kevinAlbs kevinAlbs Sep 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
/// To support incremental migration to @ref bsoncxx::v1::types::view.
/// To support incremental migration to @ref bsoncxx::v1::types::value.

Are the added type, type_id and get_<type> methods intended for feature parity with bsoncxx::v1::types::value? I expect this may not strictly be needed to ease migration since existing applications would not have calls to these methods.

Copy link
Contributor Author

@eramongodb eramongodb Sep 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not for feature parity, but for name parity, so that when root namespace redeclarations are updated from v_noabi to v1, the required changes can be minimized in advance by downstream users without forced-breaking-changes:

bsoncxx::types::view v; // Syntax is the same for v_noabi and v1.
v.type_view();          // Syntax is the same for v_noabi and v1.

When bsoncxx::types::view is updated from v_noabi::types::view to v1::types::view, code which have already been incrementally updated (as part of a API minor version release) to use the new names will not be broken by the redeclaration release (as part of a API major version release) to the same extent as if the v_noabi new-name equivalents were not available.

///
v_noabi::type type_id() const {
return this->view().type_id();
}

///
/// Get a view over the bson_value owned by this object.
///
Expand All @@ -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")
};

///
Expand Down Expand Up @@ -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
///
11 changes: 9 additions & 2 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/view-fwd.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,12 @@ class view;

} // namespace bson_value

using bson_value::view;
///
/// Equivalent to @ref bsoncxx::v_noabi::types::bson_value::view.
///
/// To support incremental migration to @ref bsoncxx::v1::types::view.
///
using view = v_noabi::types::bson_value::view;

} // namespace types
} // namespace v_noabi
Expand All @@ -41,7 +46,7 @@ using v_noabi::types::bson_value::view;

} // namespace bson_value

using bson_value::view;
using v_noabi::types::view;

} // namespace types
} // namespace bsoncxx
Expand All @@ -52,6 +57,8 @@ using bson_value::view;
/// @file
/// Declares @ref bsoncxx::v_noabi::types::bson_value::view.
///
/// @deprecated Use @ref bsoncxx/types/view-fwd.hpp instead (renamed).
///
/// @par Includes
/// - @ref bsoncxx/v1/types/view-fwd.hpp
///
15 changes: 15 additions & 0 deletions src/bsoncxx/include/bsoncxx/v_noabi/bsoncxx/types/bson_value/view.hpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,8 @@ namespace bson_value {
///
/// A non-owning variant that can contain any BSON type.
///
/// @deprecated Use @ref bsoncxx::v_noabi::types::view instead (renamed).
///
/// @warning
/// Calling the wrong get_<type> method will cause an exception
/// to be thrown.
Expand Down Expand Up @@ -128,10 +130,21 @@ class view {
///
/// 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 _id;
}

///
/// Equivalent to @ref type() const.
///
/// To support incremental migration to @ref bsoncxx::v1::types::view.
///
v_noabi::type type_id() const {
return _id;
}

#pragma push_macro("X")
#undef X
#define X(_name, _value) BSONCXX_ABI_EXPORT_CDECL(v_noabi::types::b_##_name const&) get_##_name() const;
Expand Down Expand Up @@ -240,6 +253,8 @@ using v_noabi::types::bson_value::operator!=;
/// @file
/// Provides @ref bsoncxx::v_noabi::types::bson_value::view.
///
/// @deprecated Use @ref bsoncxx/types/view.hpp instead (renamed).
///
/// @par Includes
/// - @ref bsoncxx/v1/types/view.hpp
///
Loading