Folks, 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 I'd really appreciate it if: * Folks can read through the docs looking for the usual SNAFU's * Test the code on whatever exotic compilers/platforms you may have available. Some random thoughts that occurred to me while doing this: * I don't see the point of the static-min-max templates - there are 4 of them when 1 would probably do (template <class T, T val1, T val2> static_min_max), but in any case the implementation is almost too trivial for a separate template to make sense? * I haven't added mpl-compatible templates yet as per https://svn.boost.org/trac/boost/ticket/1224, is there demand for this? Cheers, John.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, November 26, 2009 1:36 PM To: boost@lists.boost.org Subject: [boost] Boost.Integer makeover
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
I'd really appreciate it if:
* Folks can read through the docs looking for the usual SNAFU's.
Looks excellent. I spotted, just cosmetically glancing through, 1 // to manipulate as possible, it's size may be greater than should be 'its', as ever ! ;-) 2 Copyright � 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, John Maddock Table�2.�Members of the `boost::high_bit_mask_t` Class Template Table�3.�Members of the [^boost::low_bits_mask_t] Class Template has some unprintable (by Firefox) chars. (But other Quickbook, eg Units show the (c) sign OK. 3 The class templates in this header are an extension of the integer type selection class templates. The new class templates provide the same sized types, but also convienent masks to use when extracting the highest or all the significant bits when the containing built-in type contains more bits. This prevents contaimination of values by the higher, unused bits. typos in convienent and contaimination (we haven't quite got the spilling chicker to work with Quickbook) Paul PS I'll try to get my draft Prototype in a comment-worthy state and post to sandbox.
2009/11/26 Paul A. Bristow <pbristow@hetp.u-net.com>:
Copyright � 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, John Maddock Table�2.�Members of the `boost::high_bit_mask_t` Class Template Table�3.�Members of the [^boost::low_bits_mask_t] Class Template
That's because subversion sets the character encoding to UTF-8 in the http header which overrides the character encoding in the file. It'll be fine elsewhere. I don't know if it's possible to stop subversion from doing that. Although ideally, we should use character entities for all anything that isn't ascii. Daniel
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of Daniel James Sent: Thursday, November 26, 2009 2:24 PM To: boost@lists.boost.org Subject: Re: [boost] Boost.Integer makeover
2009/11/26 Paul A. Bristow <pbristow@hetp.u-net.com>:
Copyright � 2001 -2009 Beman Dawes, Daryle Walker, Gennaro Prota, John Maddock Table�2.�Members of the `boost::high_bit_mask_t` Class Template Table�3.�Members of the [^boost::low_bits_mask_t] Class Template
That's because subversion sets the character encoding to UTF-8 in the http header which overrides the character encoding in the file. It'll be fine elsewhere. I don't know if it's possible to stop subversion from doing that. Although ideally, we should use character entities for all anything that isn't ascii.
So does this mean that a release using a zip from Sourceforge will display OK. The symbols used above are trivial and not important, but does it mean that some more significant symbols like math and greek say will not display right? I don't remember this being a problem with the Math development, but perhaps we never used SVN to move html files? Not a problem with pdf I presume. Or should we use a different way of specifying symbols to avoid this? Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
2009/11/26 Paul A. Bristow <pbristow@hetp.u-net.com>:
So does this mean that a release using a zip from Sourceforge will display OK.
Yes.
The symbols used above are trivial and not important, but does it mean that some more significant symbols like math and greek say will not display right?
The html is encoded as ISO-8859-1, which is mostly for Western European languages. Every that isn't in that character (such as greek characters) will use character entities and will be fine.
I don't remember this being a problem with the Math development, but perhaps we never used SVN to move html files?
It's the same there: http://svn.boost.org/svn/boost/trunk/libs/math/doc/html/index.html
Not a problem with pdf I presume.
Right.
Or should we use a different way of specifying symbols to avoid this?
Setting chunker.output.encoding to US-ASCII might fix this. I'll try it later. http://docbook.sourceforge.net/release/xsl/current/doc/html/chunker.output.e... Daniel
2009/11/26 Daniel James <daniel_james@fmail.co.uk>:
2009/11/26 Paul A. Bristow <pbristow@hetp.u-net.com>:
Or should we use a different way of specifying symbols to avoid this?
Setting chunker.output.encoding to US-ASCII might fix this. I'll try it later.
OK, I've changed html.xsl to do that. I'm not sure if it's a good idea, we'll see how it goes. https://svn.boost.org/trac/boost/changeset/57964/ Daniel
Setting chunker.output.encoding to US-ASCII might fix this. I'll try it later.
OK, I've changed html.xsl to do that. I'm not sure if it's a good idea, we'll see how it goes.
That gets it, thanks! Of course changes only come into effect once the docs are regenerated and checked in... John.
That's because subversion sets the character encoding to UTF-8 in the http header which overrides the character encoding in the file. It'll be fine elsewhere. I don't know if it's possible to stop subversion from doing that. Although ideally, we should use character entities for all anything that isn't ascii.
So does this mean that a release using a zip from Sourceforge will display OK.
Yes.
The symbols used above are trivial and not important, but does it mean that some more significant symbols like math and greek say will not display right?
I don't remember this being a problem with the Math development, but perhaps we never used SVN to move html files?
We did, but same issues there with any non-UTF-8 character that's not encoded as a HTML entitity (all the special math symbols are).
Not a problem with pdf I presume.
Or should we use a different way of specifying symbols to avoid this?
Probably not, it's an SVN SNAFU rather than a real issue. TLA overloading yours, John.
3 The class templates in this header are an extension of the integer type selection class templates. The new class templates provide the same sized types, but also convienent masks to use when extracting the highest or all the significant bits when the containing built-in type contains more bits. This prevents contaimination of values by the higher, unused bits.
typos in convienent and contaimination
Thanks, fixed.
(we haven't quite got the spilling chicker to work with Quickbook)
Sigh, MS Word crashes every time I try to open a .qbk document in it :-( John.
-----Original Message----- From: boost-bounces@lists.boost.org [mailto:boost-bounces@lists.boost.org] On Behalf Of John Maddock Sent: Thursday, November 26, 2009 3:45 PM To: boost@lists.boost.org Subject: Re: [boost] Boost.Integer makeover
(we haven't quite got the spilling chicker to work with Quickbook)
Sigh, MS Word crashes every time I try to open a .qbk document in it :-(
My favourite text editor is TextPad and I use it's syntax coloring (I find this VERY useful - and have tasteful coloring of course), but the many of strange words and symbols drive the spelling checker into hyperdrive, so its spelling checker is not fully useful until you have added new words to the dictionary. Does anyone know how to do better? Paul --- Paul A. Bristow Prizet Farmhouse Kendal, UK LA8 8AB +44 1539 561830, mobile +44 7714330204 pbristow@hetp.u-net.com
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
I'd really appreciate it if:
* Folks can read through the docs looking for the usual SNAFU's * Test the code on whatever exotic compilers/platforms you may have available.
I don't know if this helps, but my compilation problems related to integer.hpp I encountered over the last couple of days are gone now. :-P Regards Hartmut ------------------- Meet me at BoostCon http://boostcon.com
I don't know if this helps, but my compilation problems related to integer.hpp I encountered over the last couple of days are gone now. :-P
Good. Though that may have been more related to new SNAFU's introduced by yours truly though :-(
Ooops. What did I break? I'm not aware of having done anything to integer.hpp except for fixing somebody else's SNAFU of doing a global search and replace... Regards Hartmut ------------------- Meet me at BoostCon http://boostcon.com
I don't know if this helps, but my compilation problems related to integer.hpp I encountered over the last couple of days are gone now. :-P
Good. Though that may have been more related to new SNAFU's introduced by yours truly though :-(
Ooops. What did I break? I'm not aware of having done anything to integer.hpp except for fixing somebody else's SNAFU of doing a global search and replace...
Ah no! *You* didn't break anything, that was me! Back in the day when folks wrote real letters, "yours truly" refers to the sender of a communication. Regards, John.
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@sig.com 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.
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.
John Maddock wrote:
Actually, these are "bag" traits classes with three members:
::least ::fast ::exact
I'll update the table to make this more explicit. It will be nice to have some mPL compliant meta-function that return a ::type cause it is cumbersome to define a meta-function just to be able to use integer traits in a MPL lambda
-- ___________________________________________ Joel Falcou - Assistant Professor PARALL Team - LRI - Universite Paris Sud XI Tel : (+33)1 69 15 66 35
Actually, these are "bag" traits classes with three members:
::least ::fast ::exact
I'll update the table to make this more explicit. It will be nice to have some mPL compliant meta-function that return a ::type cause it is cumbersome to define a meta-function just to be able to use integer traits in a MPL lambda
That's the subject of a bug report: https://svn.boost.org/trac/boost/ticket/1224 I just haven't gotten around to it yet, as I wasn't sure there was any demand... looks like there is though? John.
John, Thanks for staying on top of these foundational libraries; keeping things shipshape is not a glamorous job, but it's oh-so-necessary. -- Dave Abrahams BoostPro Computing http://www.boostpro.com
John Maddock wrote:
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 ;-)
That's not quite true. There may be an extension type that can be employed.
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."
If your understanding of the behavior is accurate, that sounds good.
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...
I suggested adding "type" because "fast" matches the name in other traits for the same purpose. Thus, "type" because that's the norm for such things, and "fast" because it is consistent with the other "bag" traits. I understand your concern about adding a type, but there are signed and unsigned variants for other purposes, so it seems odd that this one doesn't follow.
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.
Yeah, I missed that.
Many thanks, I've applied the other suggestions BTW - a big help - thanks!
You're welcome. _____ Rob Stewart robert.stewart@sig.com 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.
John Maddock wrote:
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 :-(
I've used the compile-time log2 to determine the smallest integer type in which I can store any value of an enumeration. It's not easy to use, though; I'd prefer something that returned ceil(log2(n)) rather than floor(log2(n)). I can't make any sense of the existing example. I've used the bit masks too, though I can't remember what for right now. The point of low_bit_mask_t is to avoid code like this, which doesn't work when n==32 and sizeof(int)==4: uint32_t mask = (1<<n)-1; (As the docs say: "When Bits is the exact size of a built-in unsigned type, the implementation has to change to prevent undefined behaviour."). The high_bit_mask_t is less useful. I don't see a good use for it. I don't think I've ever used min/max, either. John Bytheway
On Sunday 29 November 2009 12:38:40 John Bytheway wrote:
I've used the compile-time log2 to determine the smallest integer type in which I can store any value of an enumeration. It's not easy to use, though; I'd prefer something that returned ceil(log2(n)) rather than floor(log2(n)). I can't make any sense of the existing example.
Here's what I use (if it can go into boost, that'd be one less thing I'd have to maintain): template <boost::static_log2_argument_type num> struct static_log2_ceil { BOOST_STATIC_CONSTANT( boost::static_log2_result_type, value = static_log2<num-1>::value+1 ); }; // Handle the case of static_log2 not allowing 0 template <> struct static_log2_ceil<1> { BOOST_STATIC_CONSTANT( boost::static_log2_result_type, value = 0 ); }; // Asking for log2(0) is an error template <> struct static_log2_ceil<0> {}; If this is useful to you, could you please create a trac ticket and attach the implementation as a patch? Regards, Ravi
John Bytheway wrote:
I've used the bit masks too, though I can't remember what for right now.
I've remembered; it was for a vEB tree (http://en.wikipedia.org/wiki/Van_Emde_Boas_tree). John Bytheway
participants (9)
-
Daniel James -
Dave Abrahams -
Hartmut Kaiser -
joel falcou -
John Bytheway -
John Maddock -
Paul A. Bristow -
Ravi -
Stewart, Robert