Re: [boost] Re: string_algo Formal Review

From: Pavol Droba (droba_at_[hidden])
Date: 2003-10-22 09:53:12

On Wed, Oct 22, 2003 at 09:40:17AM -0400, David Abrahams wrote:
> Pavol Droba <droba_at_[hidden]> writes:
> 
> > On Tue, Oct 21, 2003 at 04:37:06PM -0400, David Abrahams wrote:
> >> Pavol Droba <droba_at_[hidden]> writes:
> >
> > [snip]
> >  
> >> You can define a shorthand which associates template parameter names
> >> (e.g. InputIterator) with specific concept requirements (e.g. "must
> >> be an input iterator).  I think the standard does this, in fact.
> >
> > This is already done for iterators. I will change it for containers too.
> >
> >
> >> You can also make some blanket statements about exceptions, like the
> >> standard does.
> >
> > string_algo library does not throw any exceptions on its own. Only inherited
> > types used by algorithms can do it. But, given the fact that most algorithms
> > are templated, it is not possibly to exactly specify which exception
> > can be thrown.
> >
> > So wouldn't it be enought to mention this as a one paragraph in docs?
> 
> Probably not quite enough.  It may be important to note that certain
> functions give the strong or nothrow guarantee.  If you don't know how
> to decide which those are, see
> http://www.boost.org/more/generic_exception_safety.html.  If you are
> still unsure, please ask for help.
>

Thanks for the link, I knew that there is something like that laying somewhere
around, but somehow I could not find it :).

I haven't done a proper exception safety inspection of the lib. But as far
as I understand the concepts in this document, the library satisfies (or it is 
very close to) the "basic" exception guarantie. If somebody with an experience with
this can give me a hand, I'll be very glad.

Question is, if there is a requirement, that the "strong" guarantie should be fullfiled.
Obviosly this only applies to mutating algorithms and it is not fulfilled.
Such a guarantie could bring a heavy degradation of performance.

 
> >> That leaves you with only preconditions and postconditions, and
> >> exceptions to the blanket statements about exceptions <g> where
> >> appropriate.
> >
> > Is the formal specification of pre/post conditions realy so vital
> > for the usage of the library? 
> 
> Normally, yes.
> 
> > Informal specification is given in paramter and result descriptions.
> 
> Can you give an example of an informal specification of
> pre/post-conditions which ought to be enough?
> 
> I should point out that originality is not a virtue when it comes to
> documentation conventions.  Even if your informal description does in
> fact give all the neccessary information, following the formula set
> out by the standard and some Boost libraries helps reviewers to
> evaluate that you have done so, and will help users familiar with
> those conventions to grasp your library's semantics.

Ok, I will not argue any more about the need of these specifications. 
I understand the reasons for them, just I have underestimated their importance.

They will be incorporated in docs. However, I don't think that I would be able to 
fix the docs before the review finishes. Therefore, I'd like to ask you to
try to review the algorithms with the current state of docs, with the help of code and examples,
and if there are some vital uncertenities, I will try to give an explanation from case to case.

Regards,

Pavol.