Re: Ready to add dlw_oprs.zip?

From: Daryle Walker (darylew_at_[hidden])
Date: 2000-12-19 23:55:54

on 12/18/00 11:37 AM, Aleksey Gurtovoy at alexy_at_[hidden] wrote:

> I also think that we're 'almost there', though there are a few issues I
> would like to resolve before the new version goes public. My overall comment
> is that both code and documentation look really good, good work Daryle!
> 
> BTW, comments are listed in the order I looked at things, not in the order
> of their significance ;)

I just put up a new version (16) in the vault, based on some of these
comments, and some more from Dave.

> 1) it might sound as nit-picking, but there is a difference between  'class
> 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...

I did change that first reference, but not most of the others.  (Some
references were completely reworded.)

> 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 define
> operators in namespace scope in terms of a minimal number of class'
> fundamental operators."

Fixed.

> 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 account
> the fact that comparison operators are currently classified as "arithmetic
> operators" too, and there are a lot of applications for them outside of any
> "numeric" stuff... hmm.. I am starting to think that these should be really
> moved to a separate category (in docs). Dave?

Cleaned up some the instances of "numeric."

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

Fixed.

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

I don't understand what is wrong with "simply"?  I reworded that sentence
anyway.

> 6) sentence "The requirements for the types used to instantiate the simple
> operator templates are specified in terms of expressions which must be valid
> 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 next
> subsection - 'Simple Arithmetic Operators'. Probably we should just remove
> the second appearance.

Fixed.

> 7) an important issue - template names; currently they are inconsistent in
> sense that some of them do follow the standard's  terminology and operators'
> 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. The list of the names I'm
> concerned about with some comments:
> 
> * 'totaly_ordered' - isn't plain 'comparable' a better choice?

I renamed it "totally_comparable."  It matches the '*comparable' naming
scheme its components use.  I use totally because the new operators are
technically only valid if the type has a total ordering.  Some types don't
have this.  For instance, the IEC 559 used for floating-point for a lot of
architectures isn't totally ordered, since NaN values don't rank with
anything, not even themselves.  In those cases, (x < y) -> !(x >= y) is
wrong.

> * 'bitwise_combinable' - IMO should be called 'bitwise', and the current
> '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 guess so.  I did the change and renamed the old "bitwise" to
"bit_manipulative."

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

OK.

> * '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'.

OK.  (I used "negateable.")

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

I used Dave's other suggestion of "unit_steppable."

[SNIP idempotent]
> 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.

Too bad we don't have template typedefs, to make any transitions easier.  If
we do rename "less_than_comparable" to "relational," we could rename the
other '*comparable' templates too.  ("equality_comparable" to "equitable"?
"totally_comparable" to the familiar-looking "totally_ordered"?)

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

It shows up on my stuff (iCab and IE5, for Mac).  I guess the IE5.5/Win guys
forgot to incorporate the code from the Mac version.

> * a paragraph symbol (which is a part of  the reference to wording of the
> 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.

Fixed.

> 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 guess it could be split up.  But I don't know whether we should do it now
or for the next release.  I have a related problem that I'll mention in my
response to Dave about version 16.

-- 
Daryle Walker
Mac, Internet, and Video Game Junkie
darylew AT mac DOT com