Boost logo

Boost :

From: David Abrahams (abrahams_at_[hidden])
Date: 2000-12-19 06:25:10

----- Original Message -----
From: "Aleksey Gurtovoy" <alexy_at_[hidden]>

> 1) it might sound as nit-picking, but there is a difference between
> templates' and 'template classes' terms, and IMO the following (first)
> sentence of the documentation should really use the former term ('class
> templates'): "The header <boost/operators.hpp> supplies several sets of
> template classes (in namespace boost)." BTW, some other boost libraries'
> docs (e.g. one of type_traits), also use the 'template classes' phrase in
> (IMO) wrong contexts...

Alexy is right, here.

> 2) "These templates define many global operators in terms of a minimal
> number of fundamental operators." (the second sentence) The word 'global'
> here makes me nervous ;). May be this one is better "These templates
> operators in namespace scope in terms of a minimal number of class'
> fundamental operators."

That should be "at namespace scope", but yes, I agree. Also, dropping "many"
as you have is appropriate.

> 3) as Dave already mentioned, characterizing a potential argument type of
> (arithmetic) operator templates as a "numeric" (in particular, in the
> 'Arithmetic Operators' section) is incorrect, especially taking into
> the fact that comparison operators are currently classified as "arithmetic
> operators" too, and there are a lot of applications for them outside of
> "numeric" stuff... hmm.. I am starting to think that these should be
> moved to a separate category (in docs). Dave?

I'm open to suggestions, though I don't mind classifying them according to
their application to built-in types.

> 4) "built-in numeric types" ('Arithmetic Operators' section, the second
> sentence) should be "built-in arithmetic" or "standard arithmetic"


> 5) a mistype error - "Composite operator templates >>simply<< list what
> other templates..."

Yeah, that should be rephrased anyway: "For composite operator templates,
only their components are listed. The requirements of composite operator
templates can be inferred from the requirements of the listed components"

> 6) sentence "The requirements for the types used to instantiate the simple
> operator templates are specified in terms of expressions which must be
> and by the return type of the expression." is repeated two times - first
> time at the end of the last paragraph of introduction text of the
> 'Arithmetic Operators' section, and second time at the beginning of the
> subsection - 'Simple Arithmetic Operators'. Probably we should just remove
> the second appearance.

I agree.

> 7) an important issue - template names; currently they are inconsistent in
> sense that some of them do follow the standard's terminology and
> classification, and some of them don't or/and even use the standard naming
> of operators categories to describe something different; for example,
> 'additive' and 'mutliplicative' match the standard terminology one-to-one,
> and 'totaly_ordered' IMO doesn't even come close.

Do you mean that the name doesn't reflect the standard mathematical meaning
of "total ordering"?

> The list of the names I'm
> concerned about with some comments:
> * 'totaly_ordered' - isn't plain 'comparable' a better choice?

No, I don't think so. IMO, the name should be /more/ specialized that
"less_than_comparable", not less.

> * 'bitwise_combinable' - IMO should be called 'bitwise', and the
> 'bitwise' should be renamed to something else or removed, because it
> doesn't match the standard definition (5.11-5.13); IMO having a misguiding
> name is much worse than a hypothetical inconvenience (two lines of code
> instead of one) in rare cases.

I agree with this. It doesn't make sense to me to factor out and expose
every possible combination of operators in the interface.

> * 'bidirectionally_shiftable' - again, just plain 'shiftable' (5.8)
> should be good enough and more standard.

I'm not sure. I think the same argument as the one against "comparable"
applies here.

> * 'logically_invertable' - operator ! is actually called 'logical
> negation operator' (5.3.1 para 8), so it'll be more correct to call the
> corresponding operator class template 'logically_negateable' or just plain
> 'negateable'.

Yes, that's a much better name, though please drop the first 'e':

> * 'unit_changeable' - Dave's 'bidirectional' make much more sense to

I'm fond of unit_steppable, and Daryle seems to have chosen that one as
well. I'm afraid "bidirectional" is a bit too general.

> * 'idempotent' - well, there are no standard term for this (at least
> one that I know about :), and probably it is technically correct, but for
> it just seem to stand out against all others.

Actually, if is to be
believed, then "idempotent" is almost totally inappropriate. I'm glad you
pointed this out. Can you come up with a better name?

> Also a question to all, highlighted by the recent discussion of the
> 'LessThanComparable' concept's requirements ;) - what about renaming the
> 'less_than_comparable' class template to something else, which will match
> the standard definition more closely, and deprecating the old name??
> 'relational' (5.9 [expr.rel]) is not bad IMO.

In what way does the current one not match the standard definition? I'm not
sure what problem you're trying to fix here.

> 8) HTML formatting issues:
> * quote of Matt Austern in the 'Note for Users of Older Versions' is
> emphased in any way ("", or whatever) as such (at least not on IE5.5)

I've mentioned this to Daryle in the past. We do need to restore the &quot;

> * a paragraph symbol (which is a part of the reference to wording of
> standard in the same note) is cute :), but the standard format of a
> reference to the standard ;) is "Section 10.5 paragraph 5" and I think we
> better stick to it.

That's probably best.

> One last meta comment: I am also sharing Dave's concerns about library's
> grow (given that just recently I citied the library as an example of
> appropriate layering/splitting into parts :). I think that splitting it to
> at least three parts (both code and documentation) - basic arithmetic
> operators, iterator adapters and grouped operators, should be done before
> the release. If nobody else, I'll volunteer :).

I accept! ;-). Give Daryle a chance to finish all the changes he feels he
needs to make, then go for it.


Boost list run by bdawes at, gregod at, cpdaniel at, john at