[SERVER-45118] Documentation for BSONElement::numberInt() and BSONElement::numberLong() should be improved Created: 12/Dec/19  Updated: 29/Oct/23  Resolved: 15/Jan/20

Status: Closed
Project: Core Server
Component/s: Internal Code
Affects Version/s: None
Fix Version/s: 4.3.3

Type: Improvement Priority: Major - P3
Reporter: David Storch Assignee: David Storch
Resolution: Fixed Votes: 0
Labels: qexec-team
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Backwards Compatibility: Fully Compatible
Sprint: Query 2020-01-27
Participants:

 Description   

As of this writing, the comments appear like so:

    /** Retrieve int value for the element safely.  Zero returned if not a number. */
    int numberInt() const;
    /** Retrieve long value for the element safely.  Zero returned if not a number.
     *  Behavior is not defined for double values that are NaNs, or too large/small
     *  to be represented by long longs */
    long long numberLong() const;

There are a few problems with this:

  1. The documentation for numberLong() elaborates about undefined behavior for NaN and large doubles, but we don't have the same documentation for numberInt().
  2. While we're at it, we should be explicit that calling this on +/-infinity is also UB.
  3. It's unclear what's meant by "safely" in these comments. In fact, these operations are unsafe to perform on an arbitrary BSONElement due to the possibility of undefined behavior. That's why we have a separate function called BSONElement::safeNumberLong(). I recommend that we delete the word "safely".
  4. The sentence "Zero returned if not a number" is confusing, since it doesn't disambiguate between NaN and non-numeric BSON types. We should say "Zero is returned if the BSON type is non-numeric. Results in undefined behavior if the BSON type is numeric but the value is NaN, +/-Infinity, ...".


 Comments   
Comment by Githook User [ 15/Jan/20 ]

Author:

{'name': 'David Storch', 'email': 'david.storch@mongodb.com', 'username': 'dstorch'}

Message: SERVER-45118 Improve comments for BSONElement::numberInt() and BSONElement::numberLong().
Branch: master
https://github.com/mongodb/mongo/commit/2149c69b419c26042b98229f5c289511ca0bad26

Generated at Thu Feb 08 05:07:56 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.