Examples

Example 1: std::string::insert (precondition error). When trying to insert a new character into a string at a specific position pos, a caller should check for invalid values of pos that would violate a documented parameter requirement; for example, pos > size(). The insert function can't perform its work successfully if it doesn't have a valid starting point.

Example 2: std::string::append (postcondition error). When appending a character to a string, failure to allocate a new buffer if the existing one is full prevents the operation from performing its documented function and achieving its documented postconditions, and is therefore an error.

Example 3: Inability to produce a return value (postcondition error). For a value-returning function, producing a valid return object is a postcondition. If the return value can't be correctly created (e.g., if the function returns a double, but there exists no double value with the mathematical properties requested of a result), that is an error.

Example 4: std::string::find_first_of (not an error in the context of string). When searching for a character in a string, failure to find the character is a legitimate outcome and not an error. At least, it is not an error as far the general-purpose string class is concerned; if the owner of the given string assumed the character would be present and its absence is thus an error according to a higher-level invariant, that higher-level calling code would then appropriately report an error with respect to its invariant.

Example 5: Different error conditions in the same function. In spite of the increased reliability of disks nowadays, writing to disk has traditionally remained subject to expected errors. If you design a File class, in the same function File::Write( const char* buffer, size_t size ), which requires that buffer is non-null and that the file be opened for writing, you might decide to do the following:

• If buffer is NULL: Report an error on the precondition violation.

• If the File is read-only: Report an error on the precondition violation.

• If the write does not succeed: Report an error on the postcondition violation, because the function cannot do the work it promises to do.

Example 6: Different status for the same condition. The same condition can be a valid precondition for one function and not for another; the choice depends on the function's author, who is specifying his interface's semantics. In particular, std::vector provides two ways to perform indexed access: operator[], which is not bounds-checked, and at, which is. Both require a precondition that the argument is not out of range. Because operator[] is not required to validate its argument or to be safe to call with an invalid argument, it must document that the caller has sole responsibility for ensuring that the argument is in the valid range; this function is inherently less safe. On the other hand, at is documented to behave safely even in the presence of an invalid argument, and to report an error (by throwing std::out_of_range) if the argument is found to be out of range.