[boost] [string algo review] exception specification

From: Pavol Droba (droba_at_[hidden])
Date: 2003-10-23 16:12:17

There was a request to specify exception specifications for the library.
This topic is currently missing in the library documentation, I will try
to summarize what can be done in this respect.

I have looked into the standard and into the documentation of some algorithm oriented 
libraries to have some inspiration.
On my suprise I have found, that none of these actualy contains any documentaion
about this topic.

On the second thought, there are probably resons for it. An algorithm has no internal
state, so its integrity as a component is always preserved.
Algorithms can only provide exception guaranitie for arguments they work with.
In other words, this guarantie is always relative.

Following rules define exception guaranties for the string_algo lib:

1. The library alway manages the external components only through operations
   defined for them (i.e. it can never access their internal state, if no operation allows it).
   If all such operations provide "basic exception guarantie", naturaly this
   guarantie is preserved by an algorithm

2. None of the algorithms in this library throws an exception on its own, therefore
   if all operations used by a particular algorithm provide "no-throw" guarantie,
   this guarantie is preserved.

3. "Strong" guarantie is always preserved for constant and pass-by-value arguments.
   (this is obvious, but important to mention)

These definitions are sound, but does not provide many hints, what level of
guarantie is given for a particular algorithm.

Here are some more concrete rules:

Mutating algorithms...

- Any _copy variant, creating a copy of the input has "strong" guarantie.
  This is an implication of #2, because such a variant has all the arguments const,
  or pass-by-value. It is not possible to make no-throw guarantie, because
  there is always a need for allocation.

- Any _copy variant, copying the result to the output iterator, gives "strong"
  of "nothrow" guarantie, only if the ouput iterator used for result has
  "nothrow" guarantie for all its operations.

  If the output iterator satisfies this requirement, "strong" guarantie is given.
  (this is implication of #3)
  Most of algorithms can also provide "nothrow" guarantie for common types
  used for arguments.

- inplace variant, by default provides "basic" guarantie, under conditions of #1.
  "nothrow" guarantie follows #2. Many algorithms (like trim, erase and etc.)
  can provide this guarantie, when standard container and iterator types are used.

Non mutating algorithms (f.e predicates)...

- All of these have "strong" guarantie specified in #3.

So this is the summary. It would be possible to specify for each algorithm a table
with specific requirements to give the specific guarantie. It would be quite chalenging
to do it properly, but the question is if it would be usable at all?

If requested, I can provide an example of such a table for one algorithm.

Regards,

Pavol