Re: [boost] [Range] No Reply?

From: Thorsten Ottosen (nesotto_at_[hidden])
Date: 2005-07-30 07:58:27

David Abrahams <dave <at> boost-consulting.com> writes:

> 
> 
> Sorry it took me so long to reply.  Among other things, I've been
> sick.

No worries...good thing thing yuo're back.

> Thorsten Ottosen <nesotto <at> cs.aau.dk> writes:
> 
> > David Abrahams <dave <at> boost-consulting.com> writes:
> > so you propose an extra bullet like
> >
> > *Models*
> >
> > - all standard containers
> > - std::pair<iterator,iterator> where iterator is an XXX iterator
> > - builtin arrays
> >
> >
> > for each concept?
> 
> Yes, that would be very helpful, but no, that's not what I'm asking
> for.   It's not enough.  The concept definition that the
> implementation relies upon is that
> 
>    boost::begin(v)
> 
> is valid, etc., not that
> 
>    begin(v)
> 
> is valid.  If you tell people the requirement is the latter, and then
> you tell them that standard containers are models of Range, they 
> say:
> 
>    You're lying.  There's no begin(v) for a std::vector v.
> 
> or they say:
> 
>    Okay, there must be a begin(v) for a std::vector v, since you tell
>    me it's a model of the concept.  I'll write an algorithm that
>    requires a Range argument, and then I'll use begin(v) on it.  Works
>    great... until I pass a std::vector!  Okay, that's broken, but
>    maybe I'll fix it by writing a begin overload in my own namespace.
>    Now begin(v) is valid... it still doesn't work!  What is wrong?!

right. I need to change the concept requierment. Thanks for
spelling it out for me.
 
> You snipped the following context
> ----
> >>> And then I asked that you post a link (both to the page with the
> >>> boost::begin documentation and to the page in the main docs that links
> >>> to it), but I have yet to see a reply.
> ----
> >
> >> Go to the boost web page. Follow the link in the left column to CVS.
> >> There will be a link to CVSWeb.  Browse.
> >
> > 
http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/rang
e.html
> 
> I have looked at every instance of the word "begin" on that page and
> there is NOWHERE a description of a library-provided function called
> "begin."  I am talking about an entry that tells you:
> 
>     - what header it appears in
>     - what its effects are
>     - what it returns
>     - what it throws
>     etc.
> 
> Standard function documentation.  I'm having a hard time believing
> that you really don't understand that this is required.

right. I can provide cross links to the page which explains which
header it is in.

The requiement should be that no function can throw.

The return value is explained, perhaps a bit vague. But I'm not always
sure having double information is a good idea. I mean, the intro
on that page explains that a range encapsulates two
iterators. The docs for "begin(a)" then says that is called "Beginning of
range". The semantics section then further says "Returns an iterator pointing 
to the first element in the Range.". Futhermore I give post-conditions and
invariants.

> You snipped the following context
> ----
> >>>>> 2. swappable range:

> > please just tell me how you would write it. I'll add your definition
> > to the docs.
> 
> What you have now at
> 
http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/rang
e.html
> seems fine.

So you would just remove the range terminology page?

> > maybe it should just be called Synopsis & Reference?
> 
> Maybe.  The change looks good.  I think just "Reference" would be
> perfect actually.

Ok.

> > yeah. would the "models" bullet help?
> 
> Yes, but as I described above, it's not enough.
> 
> The reference needs a lot of work:
> 
> > Overview
> > 
> > Four types of objects are currently supported by the library:
> > 
> >     * standard-like containers
> >     * std::pair<iterator,iterator>
> >     * null terminated strings (this includes char[],wchar_t[], char*, and 
wchar_t*)
> >     * built-in arrays
> 
> You don't say what "supported" means. 

that is an unfortunate vague language. 

> I assume you mean "can model
> Range." 

yes. 

> But what you've written leads me to conclude that if I write
> a model of Range, it will be unsupported.

http://cvs.sourceforge.net/viewcvs.py/*checkout*/boost/boost/libs/range/doc/boos
t_range.html#minimal_interface

explains how to extend the lib. It only lacks a discussion about
providing these functions in namespace boost or in namespace Foo to
take advantage of ADL.
 
> > Even though the behavior of the primary templates 
> 
> What "primary templates?"  That term refers to a template definition
> that is not an explicit or partial specialization.

right.

I don't see any conflict. I think this use is consistent with
Daveed's book.

> > are exactly such that standard containers will be supported by
> > default, 
> 
> What does "by default" mean?

"out of the box"..."without adding extra oveloads"

> > the requirements 
> 
> Of what?

of a range

It should be added. 

> > are much lower than the standard container requirements. For
> > example, the utility class iterator_range implements the minimal
> > interface required to make the class 
> 
> Which class? [*I* can figure out what you mean, but the language here
> is confusing.  Others will have a harder time]

would "it" be better? And perhaps "a model of Forward Range" ?
 
> > a Forward Range.
> >
> > 
> > Please also see Range concepts for more details.
> 
> At this point, if I didn't already understand this library from its
> implementation, I would be lost, and a pointer to "Range concepts"
> sure wouldn't help.

Ok. What do you suggest then. Could you point to an introduction that
captures all the good points?

Thanks for the feedback

Thorsten