[Boost-commit] svn:boost r62516 - in sandbox/SOC/2010/bits_and_ints/libs/integer/doc: . html html/boost_integer

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]