Subject: [Boost-commit] svn:boost r62516 - in sandbox/SOC/2010/bits_and_ints/libs/integer/doc: . html html/boost_integer
From: muriloufg_at_[hidden]
Date: 2010-06-07 15:40:57
Author: murilov
Date: 2010-06-07 15:40:56 EDT (Mon, 07 Jun 2010)
New Revision: 62516
URL: http://svn.boost.org/trac/boost/changeset/62516
Log:
Documentation updated
Text files modified:
sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/boost_integer/history.html | 4
sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/index.html | 19 ++
sandbox/SOC/2010/bits_and_ints/libs/integer/doc/integer.qbk | 354 ++++++++++++++++++++++++++++++---------
3 files changed, 289 insertions(+), 88 deletions(-)
Modified: sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/boost_integer/history.html
==============================================================================
--- sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/boost_integer/history.html (original)
+++ sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/boost_integer/history.html 2010-06-07 15:40:56 EDT (Mon, 07 Jun 2010)
@@ -26,7 +26,7 @@
<a name="boost_integer.history"></a><a class="link" href="history.html" title="History"> History</a>
</h2></div></div></div>
<a name="boost_integer.history.1_42_0"></a><h5>
-<a name="id36189132"></a>
+<a name="id36193799"></a>
<a class="link" href="history.html#boost_integer.history.1_42_0">1.42.0</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" type="disc">
@@ -55,7 +55,7 @@
</li>
</ul></div>
<a name="boost_integer.history.1_32_0"></a><h5>
-<a name="id36189241"></a>
+<a name="id36193907"></a>
<a class="link" href="history.html#boost_integer.history.1_32_0">1.32.0</a>
</h5>
<div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
Modified: sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/index.html
==============================================================================
--- sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/index.html (original)
+++ sandbox/SOC/2010/bits_and_ints/libs/integer/doc/html/index.html 2010-06-07 15:40:56 EDT (Mon, 07 Jun 2010)
@@ -233,12 +233,29 @@
</p>
</td>
</tr>
+<tr>
+<td>
+ <p>
+ <a class="link" href="boost_integer/bits_and_ints.html" title="Bits and Ints">Binary integral algorithms</a>.
+ </p>
+ </td>
+<td>
+ <p>
+ <code class="literal"><boost/integer/bits_and_ints.hpp></code>
+ </p>
+ </td>
+<td>
+ <p>
+ Integer algorithms and utilities.
+ </p>
+ </td>
+</tr>
</tbody>
</table></div>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
-<td align="left"><p><small>Last revised: May 06, 2010 at 18:27:06 GMT</small></p></td>
+<td align="left"><p><small>Last revised: June 07, 2010 at 19:39:34 GMT</small></p></td>
<td align="right"><div class="copyright-footer"></div></td>
</tr></table>
<hr>
Modified: sandbox/SOC/2010/bits_and_ints/libs/integer/doc/integer.qbk
==============================================================================
--- sandbox/SOC/2010/bits_and_ints/libs/integer/doc/integer.qbk (original)
+++ sandbox/SOC/2010/bits_and_ints/libs/integer/doc/integer.qbk 2010-06-07 15:40:56 EDT (Mon, 07 Jun 2010)
@@ -66,6 +66,11 @@
[Templates for finding the extrema of two numbers:
Use to find a bound based on a minimum or maximum value. Useful for generic programming. ]
]
+ [
+ [[link boost_integer.bits_and_ints Binary integral algorithms].]
+ [[^[@../../../../boost/integer/bits_and_ints.hpp <boost/integer/bits_and_ints.hpp>]]]
+ [Integer algorithms and utilities. ]
+ ]
]
[endsect]
@@ -720,125 +725,304 @@
[endsect]
[section:bits_and_ints Bits and Ints]
-Bla bla bla
+The intent of this library is to extend Boost.Integer with fast integer algorithms and utilities. This library can be included via [@../../../../boost/integer/bits_and_ints.hpp <boost/integer/bits_and_ints.hpp>].
-df
-f
+[section:sign_extend Sign Extending]
-ds
-f
-asdf
+Sign extension is automatic for built-in types, such as chars and ints. But suppose you have a signed two's complement number, x, that is stored
+using only b bits. Moreover, suppose you want to convert x to an int, which has more than b bits. A simple copy will work if x is positive, but if
+negative, the sign must be extended. For example, if we have only 4 bits to store a number, then -3 is represented as 1101 in binary. If we have
+8 bits, then -3 is 11111101. The most-significant bit of the 4-bit representation is replicated sinistrally to fill in the destination when we
+convert to a representation with more bits; this is sign extending.
+
+[section Run-time version]
+The run-time version can be included via [@../../../../boost/integer/sign_extend.hpp <boost/integer/sign_extend.hpp>].
+
+ template <typename Type>
+ inline typename enable_if<is_integral<Type>, Type>::type
+ sign_extend(Type data, std::size_t bits);
+
+[h4 Parameters]
-fsd
-f
-das
-d
-f
-a
-sf
-dsa
-fda
-f
-samefs
-daf
-asdffsa
-f
-AddendSize1f
-ads
-fsa
-f
-samefsfsa
-f
-asdffsa
-df
-sf
-sa
-fas
-f
-asf
-as
-f
-samefsfas
-f
+[table
+ [[Parameter][Description]]
+ [[`data`][ The data to be extended. ]]
+ [[`bits`][ The amount of bits in wich data is represented. ]]
+]
-fsa
-df
-dsafas
-f
+[h4 Return]
+`data` sign-extended to `sizeof(Type)` bytes. The return type is `Type`.
+[endsect]
-asdffsadsa
+[section Compile-time version]
+The compile-time version can be included via [@../../../../boost/integer/static_sign_extend.hpp <boost/integer/static_sign_extend.hpp>].
+The result will be in `value` member.
+ template<typename Type, Type data, std::size_t Bits,
+ class Enable = ``['implementation-defined]``>
+ struct static_sign_extend
+ {
+ static const Type value = ``['implementation-defined]``;
+ };
-s
-a
-s
-dfa
-dsf
-dsfa
-f
+[h4 Template Parameters]
+[table
+ [[Parameter][Description]]
+ [[`Type`][ The data type. ]]
+ [[`data`][ The data to be extended. ]]
+ [[`Bits`][ The amount of bits in wich data is represented. ]]
+]
+[endsect]
-adsf
+[section Examples]
+[h4 Run-time version]
+
+ #include <boost/integer/sign_extend.hpp>
+ #include <iostream>
-asdf
-d
-fsasf
-d
-f
-sda
+ int main()
+ {
+ // data is represented in 24-bits
+ int data = 0xFFFFFF; // -1 in 24-bits
+ int result = boost::sign_extend(data, 24);
+ std::cout << result << std::endl; // -1
+ }
+
+[h4 Compile-time version]
+
+ #include <boost/integer/static_sign_extend.hpp>
+ #include <iostream>
-fasd
+ int main()
+ {
+ // 0xFFFFF is -1 in 20-bits
+ int result = boost::static_sign_extend<int, 0xFFFFF, 20>::value;
-dasf
+ std::cout << result << std::endl; // -1
+ }
+
+[endsect]
-dsf
-dsaasdf
+[endsect]
+[section:bit_reversal Bit Reversal]
+The bit reversal functions reverts the bits of integral types.
+[section Run-time version]
+The run-time version can be included via [@../../../../boost/integer/bit_reversal.hpp <boost/integer/bit_reversal.hpp>].
+For valid types T, the function `bit_reversal` will be:
+
+ template <typename T>
+ inline T bit_reversal(T data);
+
+[h4 Parameters]
-asdf
+[table
+ [[Parameter][Description]]
+ [[`data`][ The data to be reversed. The type of data *must* be an integral type and it's size *must* be 8, 16, 32 or 64-bits, otherwise, bit_reversal(data) will result in an error. ]]
+]
-dsa
-dfs
-dsafsd
-afterd
+[h4 Return]
+`data` with its bits reversed.
+[endsect]
+[section Compile-time version]
+The compile-time version can be included via [@../../../../boost/integer/static_bit_reversal.hpp <boost/integer/static_bit_reversal.hpp>].
+The result will be in `value` member.
+
+ template <typename T, T data, class Enable = ``['implementation-defined]``>
+ struct static_bit_reversal {
+ static const Type value = ``['implementation-defined]``;
+ };
+
+[h4 Template Parameters]
+
+[table
+ [[Parameter][Description]]
+ [[`T`][ The data type. ]]
+ [[`data`][ The data to be reversed. ]]
+]
+[endsect]
-sdfa
+[section Examples]
+[h4 Run-time version]
+
+ #include <boost/integer/bit_reversal.hpp>
+ #include <iostream>
+
+ int main()
+ {
+ // data = 0101 0101
+ uint8_t data = 0x55;
+
+ uint8_t result = boost::bit_reversal(data);
+
+ // will print 0xaa (1010 1010)
+ std::cout << std::hex << result << std::endl; // -1
+ }
+
+[h4 Compile-time version]
+
+ #include <boost/integer/static_bit_reversal.hpp>
+ #include <iostream>
+
+ int main()
+ {
+ // 0x30A5 == 0011 0000 1010 0101
+ uint16_t result = boost::static_sign_extend<uint16_t, 0x30A5>::value;
+
+ // will print 0x5A0B
+ std::cout << std::hex << result << std::endl;
+ }
+
+[endsect]
+[endsect]
-sdf
-d
-fsasfd
-asdffsadfs
+[section:same_sign Same Sign]
+These functions check if wheter the sign of two integers are equal.
+
+[section Run-time version]
+The run-time version can be included via [@../../../../boost/integer/same_sign.hpp <boost/integer/same_sign.hpp>].
+For valid types T, the function `bit_reversal` will be:
+ template <typename T>
+ inline bool same_sign(T first, T second);
+
+[h4 Parameters]
-dfsa
-fds
-fds
-afds
-f
+[table
+ [[Parameter][Description]]
+ [[`first`, `second`][ The two integral values to be compared. The type of data *must* be an integral type. `first` and `second` must have the same type. ]]
+]
+[h4 Return]
+`false`: if the signs of first and second are different
-dsafsd
+`true`: if the signs are equal
-dsf
-dfs
-a
-daf
-fds
+[endsect]
-fds
+[section Compile-time version]
+The compile-time version can be included via [@../../../../boost/integer/same_sign.hpp <boost/integer/same_sign.hpp>].
+The result will be in `value` member.
+
+ template <typename T, T first, T second, class Enable = ``['implementation-defined]``>
+ struct static_same_sign
+ {
+ static const bool value = ``['implementation-defined]``;
+ };
-dsafsd
+[h4 Template Parameters]
+[table
+ [[Parameter][Description]]
+ [[`T`][ The data type. ]]
+ [[`first`, `second`][ The two integral values to be compared. ]]
+]
+[endsect]
-[section:sign_extend Sign Extending functions]
-EEEEEE
+[section Examples]
+[h4 Run-time version]
+
+ #include <boost/integer/same_sign.hpp>
+ #include <iostream>
+
+ int main()
+ {
+ int first = -1, second = -2, third = 1;
+
+ bool result = boost::same_sign(first, second);
+ std::cout << result << std::endl; // true
+
+ result = boost::same_sign(first, third);
+ std::cout << result << std::endl; // false
+ }
+
+[h4 Compile-time version]
+
+ #include <boost/integer/same_sign.hpp>
+ #include <iostream>
+
+ int main()
+ {
+ bool result = boost::static_same_sign<int, 2, 10>::value;
+ std::cout << result << std::endl; //true
+
+ result = boost::static_same_sign<int, 10, -2>::value;
+ std::cout << result << std::endl; // false
+ }
+
+[endsect]
+[endsect]
+
+[section:sign Sign function]
+The `sign` function check the signal of integrals.
+
+[section Run-time version]
+The run-time version can be included via [@../../../../boost/integer/sign.hpp <boost/integer/sign.hpp>].
+For valid types T, the function `sign` will be:
+
+ template <typename T>
+ int sign(T data);
+
+[h4 Parameters]
+
+[table
+ [[Parameter][Description]]
+ [[`data`][ The data to be checked. The type of data *must* be an integral otherwise, sign(data) will result in an error. ]]
+]
+
+[h4 Return]
+[table
+ [[Value][Description]]
+ [[`-1`][ `data` is negative. ]]
+ [[`0`][ `data` is equal to zero. ]]
+ [[`1`][ `data` is positive. ]]
+]
+
+[endsect]
+
+[section Examples]
+[h4 Run-time version]
+
+ #include <boost/integer/sign.hpp>
+ #include <iostream>
+
+ int main()
+ {
+ int first = -100, second = 340, third = 0;
+
+ int result = boost::sign(first);
+ std::cout << result << std::endl; // -1
+
+ result = boost::sign(second);
+ std::cout << result << std::endl; // 1
+
+ result = boost::sing(third);
+ std::cout << result << std::endl; // 0
+ }
+
+[endsect]
+[endsect]
+
+[section:bin_utils Binary Utilities]
+The header [@../../../../boost/integer/bin_utils.hpp <boost/integer/bin_utils.hpp>] cotains some metafunctions to handle binary data.
+All the metafunctions have an member varible named `value` where will be the result.
+
+[table
+ [[Metafuntion][Parameters][Description]]
+ [[set_bit][`typename T`, `T data`, `unsigned char pos`][ Sets the bit `pos` active in `data`. ]]
+ [[clear_bit][`typename T`, `T data`, `unsigned char pos`][ Sets the bit `pos` inactive in `data`. ]]
+ [[test_bit][`typename T`, `T data`, `unsigned char pos`][ Test if the bit `pos` in `data` is active or not. ]]
+ [[flip_bit][`typename T`, `T data`, `unsigned char pos`][ Invert the value of the bit `pos` in `data`. ]]
+ [[modify_bit][`typename T`, `T data`, `unsigned char pos`, `bool state`][ Sets the bit `pos` in `data` active if `state` is `true` or inactive if `state` is `false`. ]]
+]
[endsect]
[endsect]