Re: [boost] Boost.Integer makeover

Subject: Re: [boost] Boost.Integer makeover
From: John Maddock (john_at_[hidden])
Date: 2009-11-28 12:08:52

> The main overview section doesn't include an introduction for the purpose 
> of the library.  The table there doesn't serve the purpose as well since 
> it is the text of the third column of each row that, in aggregate, 
> documents the purpose.
>
> I suggest the following:
>
> Boost.Integer provides integer type support, particularly helpful in 
> generic programming.  It provides standard C99 integer types, such as 
> might be found in <stdint.h>, without requiring that header.  It provides 
> the means to select an integer type based upon its properties, like the 
> number of bits or the maximum supported value, as well as compile-time bit 
> mask selection.  There is a std::numeric_limits derivate that provides 
> constant expressions for min and max.  Finally, it provides two 
> compile-time algorithms: determining the highest power of two in a 
> compile-time value; and computing min and max of constant expressions.

Added, thanks.

> (Why are some headers in boost/integer and others in boost?  That's 
> awkward.)

Sigh, no idea, I agree though.

> Overview
>
> s/specifications are/specifications for these types are/
> s/The 64-bit types...in the C++ standard./The 64-bit types required by the 
> C standard are used as models.  If <stdint.h> is available on a given 
> platform, those typedefs are used as the definitions for the boost 
> namespace typedefs.  Otherwise, or if long long is not provided, 
> <boost/cstdint.hpp> provides its own definitions.

Not quite, if there's no long long then boost/cstdint.hpp can hardly provide 
it's own definitions ;-)

Updated to, hopefully, make this clearer:

"The specifications for these types are based on the ISO/IEC 9899:1999 C 
Language standard header <stdint.h>.
The 64-bit types required by the C standard are ['not required] in the boost 
header,
and may not be supplied for all platforms/compilers, because [^long long] is 
not [yet] included in the C++ standard."

> integer_traits has all private members.  Should it have been declared a 
> struct?

Oops, or at least have a "public:" inserted somewhere...

> Integer Type Selection

> These are not doc comments: I would think adding uint_fast_t would be less 
> confusing, though using int_fast_t with unsigned types must probably 
> continue to work for backward compatibility.  The output type ought also 
> to be accessible as "type."

Will change to use ::type.  I'm not convinced about adding yet another 
trait, when this one will do though...

> Sized Types
>
> This is not a doc comment: The output type ought to be accessible as 
> "type," though you'd probably need to retain "least" for backward 
> compatibility.

Actually, these are "bag" traits classes with three members:

::least
::fast
::exact

I'll update the table to make this more explicit.

> Group Bit-Mask Class Template
>
> s/lowest bits of a certain amount/lowest Bits bits/
>
> (I couldn't figure out what the original phrasing meant and took a guess.)

Me neither :-(

Changed to use the definition - 2^Bits - 1.

> Example
>
> What in the world is "is_it_what" supposed to convey?  The name is 
> nonsensical to me.

Me too, I've removed the example.  Frankly I'm not sure if anyone is 
actually using the integer-masks, compile-time log2 or min/max functions, I 
don't really see the point, and the examples given don't help much :-(

Many thanks, I've applied the other suggestions BTW - a big help - thanks!

John.