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/... 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/... 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/... 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