More C++ Idioms/Function Poisoning

= Function poisoning =

Intent
Hide or prohibit the usage of certain functions, favoring better alternatives.

Motivation
Often, when interacting with libraries that have a C or pre-C++11 interface, since modern C++ is more expressive, it would be very convenient to hide (from people that are working on a project), all (or just many) functions that allocate memory and return a raw pointer (like a ), and replace them with something more RAII-friendly (like a  ).

Solution and Sample Code
Guideline for banning a function:

A function  is a strict replacement of a function   of a library L if:
 * provides clear benefits over  (like putting the deleter in a destructor instead of manual call)
 * can act as a drop-in replacement for, which means:
 * it can interact with the library L without writing more than one line of glue code that has no particular drawbacks
 * updating  to   in the codebase is a trivial operation (use Change All Occurences or a simple find-and-replace)
 * the cost of removing  is not too high
 * does not have any drawback compared to, which means:
 * it does not add any measurable runtime overhead compared to
 * it does not add any new dependency
 * it cannot be less type-safe, exception-safe or thread-safe
 * it cannot introduce new kinds of programming errors
 * does not reduce readability or hides intent compared to, which means:
 * there is no need to document what  does since it should do the same of , only the benefits if those are not clear to everyone

Therefore, if  is a strict replacement of , one can ban   in a codebase.

Known Uses
Replace a function which cannot be removed (for example if it is part of an external library) with a function with improved functionality.

Related Idioms

 * Interface Class