Re: [boost] Boost.Integer makeover

Subject: Re: [boost] Boost.Integer makeover
From: Stewart, Robert (Robert.Stewart_at_[hidden])
Date: 2009-11-27 10:21:34

John Maddock wrote:
>
> Boost.Integer has had a quick makeover in Trunk - starting
> from the "last
> known good" release - and then fixing all outstanding issues
> filed since
> that release.  New-look docs are visible here:
> https://svn.boost.org/svn/boost/trunk/libs/integer/doc/html/index.html

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.

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

_________________________________
Standard Integer Types

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

________________
Rationale

s/resorting to/resulting in/
s/As always, the intension/The intention/

________________
Exact-width integer types

"if an implementation provides integer types with widths of 8, 16, 32, or 64 bits, it shall define the corresponding typedef names"

Sounds like text from a standard and its application to cstdint.hpp isn't clear.  I think the following is clear, assuming I inferred the right meaning:

However, if a platform supports integer types with widths of 8, 16, 32, 64, or any combination thereof, <boost/cstdint.hpp> provides the corresponding typedefs.

________________
Minimum-width integer types

s/int_least32_t denotes a signed integer type with a width of at least 32/int_least32_t denotes the smallest signed integer type with a width of at least 32/

s/Required minimum-width integer types/The following minimum-width integer types are provided for all platforms/

s/The types:/The following types are available only if, after including <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined:/
s/Are available only if, after inclusion of <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined.//

________________
Fastest minimum-width integer types

s/Required fastest minimum-width integer types/The following fastest minimum-width integer types are provided for all platforms/

s/The types:/The following types are available only if, after including <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined:/
s/Are available only if, after inclusion of <boost/cstdint.hpp>, the macro BOOST_NO_INT64_T is not defined.//

________________
Greatest-width integer types

s/These types are required/These types are provided for all platforms/
("Required" implies the reader must do something rather than that the library always does it, at least when I read it in these contexts.)

_________________________________
Integer Traits

________________
Synopsis

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

________________
Description

s/In general, it/The primary specialization/
s/Note: A flag is_integral/Note: The is_integral flag/
s/nonetheless/while/
s/cannot be provided for that user-defined class/are not provided for that user-defined class, unless boost::integer_traits is also specialized/

_________________________________
Integer Type Selection

(Throughout this section, s/class member/nested type/ to clarify that the "member" is a type.)

________________
Easiest-to-Manipulate Types

"Unsigned integral types can be used, as well as signed integral types, despite the name. The output type is given as the class member fast."

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

s/conditionalized/customized/

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

s/smallest built-in signed integral type/smallest, built-in, signed integral type/g
s/smallest built-in unsigned integral type/smallest, built-in, unsigned integral type/g
s/0 - V/0-V/ or s/V-0/V - 0/

_________________________________
Integer Masks

________________
Table 2. Members of the `boost::high_bit_mask_t` Class Template

s/smallest unsigned built-in type/smallest, unsigned, built-in type/
s/quick-to-manipulate/easiest-to-manipulate/
s/A least constant of the desired bit-masking value/A least constant with the value 2<sup>Bit</sup>/

________________
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.)

s/The bit amount/Bits/
s/largest unsigned built-in integral type/largest, unsigned, built-in integral type/

________________
Table 3. Members of the [^boost::low_bits_mask_t] Class Template

s/smallest unsigned built-in type/smallest, unsigned, built-in type/
s/quick-to-manipulate/easiest-to-manipulate/

_________________________________
Compile time log2 Calculation

s/Compile time log2 Calculation/Compile Time log2 Calculation/ or s/Compile time log2 Calculation/Compile-time log2 Calculation/

________________
Usage

s/truncated base-two logarithm/truncated, base-two logarithm/

________________
Example

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

________________
Rationale

s/statically (i.e. at compile-time) available/available statically (i.e. at compile-time)/

_________________________________
Compile time min/max calculation

________________
Usage

In "signed or unsigned (long) parameters," the formatting of "signed" and "unsigned (long)" differ and are confusing.

_____
Rob Stewart                           robert.stewart_at_[hidden]
Software Engineer, Core Software      using std::disclaimer;
Susquehanna International Group, LLP  http://www.sig.com

IMPORTANT: The information contained in this email and/or its attachments is confidential. If you are not the intended recipient, please notify the sender immediately by reply and immediately delete this message and all its attachments. Any review, use, reproduction, disclosure or dissemination of this message or any attachment by an unintended recipient is strictly prohibited. Neither this message nor any attachment is intended as or should be construed as an offer, solicitation or recommendation to buy or sell any security or other financial instrument. Neither the sender, his or her employer nor any of their respective affiliates makes any warranties as to the completeness or accuracy of any of the information contained herein or that this message or any of its attachments is free of viruses.