|I am against std::string::insert because this function may alter the original positions of the characters.|
In the general case, what are you against? Is it mutable containers? Design by contract? Not just insertion into strings, specifically?
It feels like I've been beating this point to death lately, but the assertion
"This API is not understood by most programmers so it should be avoided" is terrible for two main reasons:
1. You have no data regarding what "most programmers" understand, so your premise is a fabrication; and
2. If a particular programmer doesn't fully understand the semantics of the API, then they are welcome to go look it up
before attempting to reason about a unit which they do not understand.
Iterator invalidation is a common topic which any C++ programmer familiar with the standard library should understand. Further, the iterator invalidation rules are expressed clearly as pre- and post- conditions in the reference documentation; as is usual, if you disregard the applicable design contract your code is wrong.