Re: [boost] [range] irange is not very eloquent

Subject: Re: [boost] [range] irange is not very eloquent
From: Neil Groves (neil_at_[hidden])
Date: 2010-04-28 08:10:19

>> You have not commented nothing related to the name.

> >>
> >>
> > The name is irange. I normally prefer long names but it was a frequent
> > review comment that my names were excessively long. Amusingly the make_
> > prefix you suggested was the target for much negative commentary. The
> > integer range is probably going to be frequently used and we will soon
> > recognize it. Having to type integer_range is lengthy and upon reading
> can
> > easily be mistaken for iterator_range.
>
> Unfortunately I didn't spent enough time during the review. I really think
> "irange" is a bad name.
>

Ok, sorry. I think "make_iterator_range" is bad too. I think that whatever
name I chose someone somewhere will take a strong dislike to it. This was my
experience during the review process. Some names were definitely changed for
the better because of the vigorous debate, but at some point as the
maintainer you have to pick one. I'd like to please everyone, but this is
not possible.

>
> >> I'm afraid, but I don't find integer_range in iterator_range section.
> >>
> >>
> > There isn't an integer_range and this is why you can't find the
> > documentation! I think you are misreading the code or docs. It is exactly
> > the ease of this misreading that is the reason the name is 'irange' and
> not
> > 'iterator_range'.
>
> Then you need to change the prototypes in the documentation See below [1]
> ***integer_range***
>
> template<class Integer>
> [1] ***integer_range***< range_detail::integer_iterator<Integer> >
> irange(Integer first, Integer  last);
>
>
It most certainly does need to be corrected in the documentation. Sorry for
the confusion. It was I that misread the documentation not you. It is
evidence to support avoiding a name that is similar to iterator_range. I
acknowledge that I may be more error-prone to this than others, but I'm
maintaining the library!

> > Actually I need to properly document my return ranges. This was part of
> the
> > review feedback. The return types are not mere implementation details as
> I
> > originally intended. User of the library do need to know them sometimes.
> I
> > also need to better document the Range Return Categorys in the Range
> > Adaptors documentation.
>
> My preceding comment wasn't about  range return types, but about a detail
> implementation on the doc.
>
>
I was hoping to avoid wasting your time reviewing the Range Return
Categories etc. I thought that by acknowledging the areas that I knew to be
deficient and that I am working on would lead to greater efficiency. I had
not expressed my intent clearly enough in the previous email. I am also
intending to add considerably to the acknowledgement section since this has
yet to be updated for the Boost.RangeEx work.

> >> integer_range< ??? > var = irange(0,5);
> >>
> >> I was wondering if irange can be used with integral types as char and
> bool?
> >> For example,
> >>
> >> integer_range< ??? > lower_case = irange('a','z'+1);
>
> Could you comment the above?
>
>
You could use it like that for char I think, although I have yet to test
this case. I could add a test soon. I don't understand why anyone would want
to use it for bool, but there is a lot I don't understand.

> >> >From the Boost.Iterator doc. counting_iterator is a model of a random
> >> access iterator if the integral type provide the needed functions. So
> what
> >> is the difference between counting_range and irange functions?
>
> Could you answer the preceding question?
>
>
counting_range is typically used to wrap another range and add counting to
it. Indeed it can also be used to count integers because of the flexibility
of the Boost.Iterator counting_iterator, but only in steps of +1. There is
therefore the potential to use both for the same purpose. I recommend using
the simpler of the two solutions which is the irange when counting integer
values. The irange solution has broader compiler support due to its inherent
simplicity, and can handle steps of various sizes.

> > I hope to add to the documentation after the release anyhow. I think the
> > documentation would benefit from several tutorials.
>
> Why these tutorials have not been written before releasing the new
> Boost.Range library?
>
>
The simple answer is that a full tutorial is not part of any release
criteria. I consider the library to be extremely useful as it is right now.
There could be more features. There could be better documentation. The
benefit to getting this out to users right now is in my opinion
considerable. The defect count and defect resolution have been my
priorities. I believe this to be in a very good state of correctness. The
tutorials that get written will be all the better for the initial feedback
hence it probably results in a better product.

I have spent an enormous amount of time developing, testing and improving
compile compatibility. Additionally I spent considerable time testing
backward compatibility. The result was a pretty smooth merge of a lot of new
functionality. This was prioritised over documentation additions. I am even
today working on the documentation. The documentation will have all of the
corrections in for the release if I keep to my schedule. I'm not
intentionally shipping defects, I'm merely shipping while knowing full well
that improvements can be made. The committed state of the documentation
needs some work and this is being done.

I completely understand why someone might wonder what the heck has taken me
so long. I am astounded at the amount of time it has taken. Now that we have
a version under version control it will be far easier to include
contributions from others and scale our efforts. This is another good
argument for release.

It is a good sign (I hope) that the audience wants more!

Best,
> Vicente
>
>
Thank you for your feedback today and in the past.

Regards,
Neil Groves