Consider the following:

  class SomeApi {
    /*
      Add name value pair to the underlying object.
      Adding multiple pairs with the same name does not 
      guarantee which one is added. 
    */
    void add(std::string& name, std::string& value);
  };

If you take the documentation at face value, that says it results in undefined behavior to add multiple items like so:

SomeApi instance;
instance.add("bob", "apple");
instance.add("bob", "banana");

That may be valid, but what if, as a developer, you have intimate knowledge of what the actual underlying data structure is?


Pop quiz time:

The documentation above is valid for which data structure:

a. std::map
b. std::vector
c. std::set



The actual underlying in this example above is a vector, so of course it's perfectly fine to add whatever I want and as much as I want. Even if it was another container with a different paradigm, the behavior is still well defined. It overwrites the last value.

Turns out the header was just outdated, some annoying technical debt left over from a previous iteration.

Sometimes you can't trust a header. Go to source if you have it.