Re: [boost] string_algo Formal Review

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

Hi Beman,

On Tue, Oct 21, 2003 at 09:05:54AM -0400, Beman Dawes wrote:
> At 12:28 PM 10/20/2003, Pavol Droba wrote:
> 
> >...
> >iterator_range is merely an utility to make some tasks of in the library
> >easier. I don't know why do you pay so much attention to it. ...
> 
> Because in the current underspecified documentation iterator_range appears 
> to take any sequence denoted by an iterator range and turn it into a 
> container which can then be used in the algorithms which take ContainerT 
> arguments. This makes the algorithm interfaces look flexible enough that 
> iterator range interfaces (like the current STL) are unnecessary.

This is very true. But it is said in the docs, that it is only a little bit limited 
container ( lacks construction, destruction and swap method ). Container interface
defined in the standard does not contain any mutable operation. It only 
defines a certain way how to access values contained in a container.

> Take trim_left as an example. The template parameter is ContainerT, which 
> isn't further defined. From the name, it would be easy to assume the 
> requirements were very general, such as the "Container Requirements" table 
> 65 in 23.1. It would be easy to jump to the conclusion that these 
> requirements could be met by iterator_range.
 
> But by reading the code, we find that trim_left works by calling 
> ContainerT::erase. That means the actual requirement is tighter; the 
> container has to be mutable and must support erase. There are lots of 
> useful cases, including C arrays and the pseudo-container produced by 
> iterator_range, which don't meet that requirement.
> 
> Seen in that light, the trim_left style is more limited than the 
> traditional STL style which specifies ranges as a pair of iterators. The 
> library seems to acknowledge this by actually implementing trim_left and 
> other algorithms as wrappers around traditional STL style interfaces in 
> namespace detail.

Sure it is, but it is much more convinient to use. If you need an "unlimited"
variant, please look at the copy version whith outputs the result to an 
output-iterator (unfortunately for trim, due to problems with overloading, it
exists only in generic variant provided in the namespace string_algo).
 
> >Don't you think, that there is a time to look beyon the STL? Look the 
> >list
> >for so-much wanted container_traits and now being-developed
> >container_algo(s).
> >I personaly think, that the STL interface is obsolete and should be
> >replaced with something more simplier to use. Therefor the string_algo
> >library abandons the STL like interface completely in the favor of new,
> >container-oriented one.
> 
> The problem is that the proposed container-oriented interface won't handle 
> many common sequences, such a C arrays. It won't handle operations on a 
> sequence which is a portion of a longer sequence. The STL interface will 
> handle these cases. So no, I don't think "the STL interface is obsolete."
>

Actualy you are not quite right. I dare to say, that the current string_algo
interface have the same power as the original STL one. If you can have a look into
examples and tests (which are also a very estinguishing example of the usage),
you could have seen how to use algorithms with C-arrays and others.
>From your reasonning, I see, that the documentation is underdefined in this respect.

So I try to bring some light to it.

iterator_range can wrap ANY iterator pair, satisfying at least input_iterator requirements.
It provides complete interface needed by container_traits. This implies, that you 
can use it everywhere where this interface is sufficient. 

You cannot use it when there is a need for the transformation of the container ( like Container::erase ).
But you can used everywhere where just begin() and end() is needed. This is sufficient for
all STL algorithms.

In the previous paragraph you have picked a wrong example. It is obvoius that mutating variant
of an algorithm (like trim) will not work very well with just a range. If you have an input,
which cannot be modified (or lacks an interface for it) you can use the copy version. For every
algorithm there is variant which outputs the result to an output-iterator this variant is
always able to accept an iterator_range of a c-array. See the container traits documentation
for the list of supported types.

Also there is a bunch of examples showing varoius usage scenarious for every facility
used in the library. Set of tests can also be inspirating. 

 
> >But I don't understand your point about the implementaion of algorithms
> >being in the detail namespace. What's wrong with it, and what additional
> >documentation do you request?
> >
> >Even in the STL specification, the definitions of the algorithms
> >are quite vaque in the terms of the implementation.
> 
> The issue isn't implementation, it is the lack of requirements on types 
> specified as template parameters, and the lack of preconditions, exceptions 
> thrown, postconditions, and other firm specifications for functions.
> 
> Without that fundamental documentation, it doesn't seem possible to 
> evaluate the proposal.
> 

I will add specific concept checking and also I will try to negotiate additions
to the ConceptCheck library. This should solve most of your issues.
Preconditions and posconditions are not easily defined, and given tha fact that the library
is still under review process, the big effort put the precise specification could be wasted,
because of some proposed changes.

I understand your requirements and I agree that they are underspecified in the documentation,
but I see your opition very unfair and unjust.

There are libraries in the Boost, which lack these specifications completely (like Regex, sorry John:) )
and yet, they are part of boost and nobody find this issue a problem.

As an author of the library, I find many issues as granted, because I don't have a user view.
A part of the review process should be finding of these deficiencies and updated them. Adding few chapters,
to docs is an easy task compared to whole library development. So please let me explain any issues,
you have questions about, but don't reject the library straight away, just bacause of some misunderstanding.

Regards,

Pavol.