[CDRIVER-1916] bson_iter_init_find() and bson_iter_init_find_case() should return false only when iterator is successfully exhausted and key not found Created: 11/Nov/16  Updated: 13/Jan/17  Resolved: 13/Jan/17

Status: Closed
Project: C Driver
Component/s: libbson
Affects Version/s: None
Fix Version/s: 1.6.0

Type: Improvement Priority: Major - P3
Reporter: J Rassi Assignee: A. Jesse Jiryu Davis
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to CXX-1066 Audit all libmongoc and libbson calls... Closed

 Description   

bson_iter_init_find() and bson_iter_init_find_case() are currently documented to return false in either of the following two circumstances:

  1. Iterator initialization fails.
  2. The iterator was successfully exhausted and the requested key was not found.

Because of this ambiguity, it is not currently clear whether or not a consumer of this API should propagate an error up the call stack when it receives a false return value from one of these two functions.

Instead, these API functions should BSON_ASSERT() that iterator initialization was successful, and their documentation should be updated to reflect that they will never return an error.

See also my comment at CXX-1066 for further discussion.



 Comments   
Comment by A. Jesse Jiryu Davis [ 13/Jan/17 ]

After discussion w/ David we're saying it's not worth changing the function to abort if the bson_t is invalid. It is reasonable to require users to pass a valid bson_t to the function if they want unambiguous behavior. The documentation already accurately describes the (ambiguous) behavior:

This function is identical to (bson_iter_init() && bson_iter_find()).

Users who need to distinguish between bson_iter_init failing vs. bson_iter_find failing can call them separately.

So there's nothing to do here.

Comment by David Golden [ 13/Jan/17 ]

I believe what we want is this:

  • BSON_ASSERT() that iterator initialization was successful
  • Return a boolean with the result of the find
  • Update docs to reflect that
Comment by A. Jesse Jiryu Davis [ 13/Jan/17 ]

david.golden or rassi would you be willing to write in this ticket what doc change is required for this ticket to be closed, please?

Generated at Wed Feb 07 21:13:36 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.