CXX-1817 Rename get_utf8() to get_string() to make it more user-friendly #721
Conversation
Codecov Report
@@ Coverage Diff @@
## master #721 +/- ##
==========================================
- Coverage 94.28% 93.01% -1.27%
==========================================
Files 357 357
Lines 18655 19142 +487
==========================================
+ Hits 17588 17805 +217
- Misses 1067 1337 +270
Continue to review full report at Codecov.
|
| @@ -646,12 +647,15 @@ core& core::concatenate(const bsoncxx::document::view& view) { | |||
|
|
|||
| core& core::append(const bsoncxx::types::bson_value::view& value) { | |||
| switch (static_cast<int>(value.type())) { | |||
| // CXX-1817; deprecation warning suppressed for get_utf8() | |||
| BSONCXX_DEPRECATED types::b_utf8 get_utf8() const; | ||
|
|
||
| /// | ||
| /// Getter for elements of the b_utf8, or string, type. This function acts as a |
There was a problem hiding this comment.
The spirit of the requested change is to make it easier for users to find out how to get strings from BSON documents.
There are other types / enums with utf8 in the name:
- The bsoncxx::b_utf8 struct
- The k_utf8 value in the bsoncxx::type enum (generated by including src/bsoncxx/enums/type.hpp)
- The k_need_element_type_k_utf8 and k_cannot_append_utf8 error codes (also generated by including src/bsoncxx/enums/type.hpp)
We could deprecate (1) in favor of a newly named bsoncxx::b_string struct. But I'm not aware of a portable C++11 way to deprecate enum values for (2) and (3).
I think we should do one of two things:
- Deprecate the
b_utf8struct for a newb_stringequivalent. And add*_k_stringequivalents for the error codes and enum value. Otherwise we'll haveelement::get_utf8()deprecated, but users will still be required to use types / error codes withutf8. The error codes and enum value would need to be equal to avoid a backwards breaking change - Leave
get_utf8()undeprecated and just haveget_stringas an alias.
I have a slight preference for (2). My rationale is that it is extra work for users to move from deprecated to undeprecated API. Having the get_string helper still makes it easier for new users to find the API they want. And we can always choose to deprecate it later if need be.
Happy to chat about this further in slack/zoom.
There was a problem hiding this comment.
After discussion, we'll do option 1, but as follow-up work in CXX-2109.
Most of the changes include switching most calls to
get_utf8()withget_string().There are instances where
BSONCXX_SUPPRESS_DEPRECATION_WARNINGS_BEGIN(and its corresponding closing macro) were used on calls toget_utf8()(orget_##name()) in order to not trigger the deprecation warnings/errors on Evergreen.