[Boost-commit] svn:boost r62447 - sandbox/SOC/2010/bit_masks/lib/integer/doc

Subject: [Boost-commit] svn:boost r62447 - sandbox/SOC/2010/bit_masks/lib/integer/doc
From: bbartmanboost_at_[hidden]
Date: 2010-06-05 11:54:22

Author: bbartman
Date: 2010-06-05 11:54:21 EDT (Sat, 05 Jun 2010)
New Revision: 62447
URL: http://svn.boost.org/trac/boost/changeset/62447

Log:
completed basic work for documentation for all of the mask types excluding the compound_mask type which may not be needed.
Text files modified: 
   sandbox/SOC/2010/bit_masks/lib/integer/doc/bits_mask.qbk     |   112 +++++++++++++++++++++++++++++++++++++-- 
   sandbox/SOC/2010/bit_masks/lib/integer/doc/high_bits.qbk     |     4                                         
   sandbox/SOC/2010/bit_masks/lib/integer/doc/integral_mask.qbk |    40 ++++++-------                           
   sandbox/SOC/2010/bit_masks/lib/integer/doc/low_bits.qbk      |     6 +-                                      
   sandbox/SOC/2010/bit_masks/lib/integer/doc/main.qbk          |    16 +++-                                    
   5 files changed, 139 insertions(+), 39 deletions(-)

Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bits_mask.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bits_mask.qbk	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bits_mask.qbk	2010-06-05 11:54:21 EDT (Sat, 05 Jun 2010)
@@ -1,19 +1,43 @@
 [c++]
 [section:bits_mask bits_mask]
 [h3 Description]
+The `bits_mask` template provides an extention to the `low_bits_mask` template,
+by incorporating an `Offset` with the template. The `offest` is always relative
+to the right most bit, or bit 0. For a basic view of how `bits_mask` works
+consider the following examples:
 
+``
+typedef bits_mask<int, 10, 3> mask;
+// mask::value has the following binary value
+// 0000 0000  0000 0000  0001 1100  0000 0000
+``
+For simplicity there is a defualt parameter for `Width` giving it a value
+of `1`. This makes writing of normally left or right shift masks simple and 
+staticly checkable. For example,
+
+``
+// If one would need to create a mask for checking the 11th bit within an
+// integer it can be done simple with the following mask
+typedef bits_mask<int,11> mask;
+// this creates a mask at the 11th bit within an integer.
+``
+
+The `bits_mask` template is located in the <boost/integer/bits_mask.hpp> header
+file.
 
 [h3 Template Signature]
 `bits_mask` has the following template signature:
 ``
-template <typename T, unsigned int Offset, unsigned int Width>
+template <typename T, unsigned int Offset, unsigned int Width = 1 >
 struct bits_mask;
 ``
 
 [table
     [[Parameter][Description]]
-    [[][ ]]
-    [[][ ]]
+    [[`T`][ Is an integral type which the mask is to be created over. ]]
+    [[`Offset`][ This is the number of bits which is used for a left shift of
+the `width`. ]]
+    [[`Width`][ This is the width of the mask in bits. ]]
 ]
 
 [h3 Interface]
@@ -25,21 +49,95 @@
     [[`N::value`][Returns the `value` associated with `N`. ]]
     [[`N::value_type`][Returns `T` which is the type associated with `value` inside `N`. ]]
     [[`N::type`][ Returns the current types type. ]]
+    [[`N::width`][ Returns the integral value associated with the `width` template parameter. ]]
+    [[`N::offset`][ Returns the integral value associated with the `Offset` template parameter. ]]
     [[`operator T()`][ Run time support function. All this function does is
-return the value associated with the type. With the c++0x feature constexper
+return the value associated with the type. With the c++0x feature `constexper`
 this function will be made fasters and more effieient.]]
 ]
+[h3 Preconditions]
+Preconditions associated with the `bits_mask` template. There are two types 
+of precondtions ones which are only documented and ones which are both enforced
+and documented. Preconditions will specify which are which within the 
+documentation. All of the preconditions will document how they are enforced when
+they are enforced.
 
+[table
+    [[Precondition][Reasoning][Enforcement]]
+    [
+        [`(Offset + Width) < ( bit_width<T>::value - 1)`]
+        [It will cause overflow if the width plus the offset is greater then
+total width of the type in bits. ]
+        [ Enforced by `BOOST_STATIC_ASSERT`. ]
+    ]
+    [
+        [`Width > 0`]
+        [ This would create an empty mask, which won't do anything. ]
+        [ Enfoced by the domain of the `Width` template parameter which is an
+`unsigned int`, which prevents the value from being negative, and by
+`BOOST_STATIC_ASSERT`, which prevents the value from being zero. ]
+    ]
+    [
+        [ `T` must satisfy the `is_integral` type trait.]
+        [ The `bits_mask` template has only been tested with integral types. ]
+        [ This is only a documented precondition. ]
+    ]
+]
 
 [h3 Examples]
-Examples and use cases related to the `TYPENAME` type.
+Examples and use cases related to the `bits_mask` template.
+
+Example:
+
+Single bit mask using the default parameter for width.
+``
+typedef bits_mask< int, 0 > mask;
+// mask in this case has the following value
+// 0000 0000  0000 0000  0000 0000  0000 0001
+
+int some_bit_value = 0xdeadbeef;
+
+// now testing to see if the zero bit is set in some_bit_value
+if(some_bit_value & mask() ) {
+    ...
+    true case
+    ...
+} else {
+    ...
+    false case
+    ...
+}
+``
 
+Here is another case where the `bits_mask` template is used used similar to a
+bit field. The goal in this case would be to extract a single value from
+within an integral storage type, which may be storing one or more values.
 
-Exaple:
 ``
-    EXAMPLE
+typedef bits_mask<int,10,3> mask;
+// binary value of mask
+// 0000 0000  0000 0000  0001 1111  1111 1000
+
+// this will then be used to retrieve a value within an integer.
+int some_bit_value = 0xdeadbeef;
+// binary value of some_bit_value
+// 1101 1110  1010 1011  1011 1110  1110 1111
+
+// now to extract the value from within some_bit_value
+int new_int_value = ( some_bit_value & mask() ) >> mask::offset;
+
+// basic operations taking place.
+// 1101 1110  1010 1011  1011 1110  1110 1111 <- some_bit_value
+// 0000 0000  0000 0000  0001 1111  1111 1000 <- mask::value
+
+// preforming bitwise and operator.
+
+// 0000 0000  0000 0000  0001 1110  1110 1000 <- result of bitwise and operator
+// preform right shift operation.
+// 0000 0000  0000 0000  0000 0011  1101 1101 <- value of new_int_value. 
 ``
 
+
 The implicit cast operator allows for simplicity, clairity of code. In the
 above example `mask()` could be replaced with `mask::value` to achieve the same
 result. The same applies to all other bitwise operators.

Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/high_bits.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/high_bits.qbk	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/high_bits.qbk	2010-06-05 11:54:21 EDT (Sat, 05 Jun 2010)
@@ -37,7 +37,7 @@
     [[`N::type`][ Returns the current types type. ]]
     [[`N::width`][ Returns the integral value associated with the `width` template parameter. ]]
     [[`operator T()`][ Run time support function. All this function does is
-return the value associated with the type. With the c++0x feature constexper
+return the value associated with the type. With the c++0x feature `constexper`
 this function will be made fasters and more effieient.]]
 ]
 
@@ -46,7 +46,7 @@
 Examples and use cases related to the `high_bits_mask` template.
 
 
-Exaple:
+Example:
 ``
 typedef high_bits_mask<int,4> mask;
 

Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/integral_mask.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/integral_mask.qbk	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/integral_mask.qbk	2010-06-05 11:54:21 EDT (Sat, 05 Jun 2010)
@@ -33,37 +33,33 @@
     [[`N::type`][ Returns the current types type (using N as an example,
 `N::type` is equivalent to `integral_mask<int,16>` )]]
     [[`operator T()`][ Run time support function. All this function does is
-return the value associated with the type. With the c++0x feature constexper
+return the value associated with the type. With the c++0x feature `constexper`
 this function will be made fasters and more effieient.]]
 ]
 
 
 [h3 Examples]
-Examples and use cases related to the `integral_mask` type.
+Examples and use cases related to the `integral_mask` template.
 
-Exaple:
+Example:
 ``
-#include <boost/integer/integral_mask.hpp>
-using namespace boost;
+int bits = 255;
+
+typedef integral_mask<int, 16> mask;
+// mask has the folling binary value
+// 0000 0000  0000 0000  0000 0000  0001 0110
+
+// bits has binary value of:
+// 0000 0000  0000 0000  0000 0000  0010 0101
+    
+// the following is a bitwise and operation
+// which is done to bits using the integral_mask type
+int new_bits = bits & mask();
+
+// Resulting value of new_bits:
+// 0000 0000  0000 0000  0000 0000  0000 0100
 
-int main() {
-    int bits = 255;
 
-    typedef integral_mask<int, 16> mask;
-    // mask has the folling binary value
-    // 0000 0000  0000 0000  0000 0000  0001 0110
-
-    // bits has binary value of:
-    // 0000 0000  0000 0000  0000 0000  0010 0101
-        
-    // the following is a bitwise and operation
-    // which is done to bits using the integral_mask type
-    int new_bits = bits & mask();
-
-    // Resulting value of new_bits:
-    // 0000 0000  0000 0000  0000 0000  0000 0100
-    return 0;
-}
 ``
 The implicit cast operator allows for simplicity, clairity of code. In the
 above example `mask()` could be replaced with `mask::value` to achieve the same

Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/low_bits.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/low_bits.qbk	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/low_bits.qbk	2010-06-05 11:54:21 EDT (Sat, 05 Jun 2010)
@@ -15,7 +15,7 @@
 header file.
 
 [h3 Template Signature]
-`TYPENME` has the following template signature:
+`low_bits_mask` has the following template signature:
 ``
 template <typename T, unsigned int Width>
 struct low_bits_mask;
@@ -38,7 +38,7 @@
     [[`N::type`][ Returns the current types type. ]]
     [[`N::width`][ Returns the integral value associated with the `width` template parameter. ]]
     [[`operator T()`][ Run time support function. All this function does is
-return the value associated with the type. With the c++0x feature constexper
+return the value associated with the type. With the c++0x feature `constexper`
 this function will be made fasters and more effieient.]]
 ]
 
@@ -47,7 +47,7 @@
 Examples and use cases related to the `low_bits_mask` template.
 
 
-Exaple:
+Example:
 ``
 typedef low_bits_mask<int,4> mask;
 

Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/main.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/main.qbk	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/main.qbk	2010-06-05 11:54:21 EDT (Sat, 05 Jun 2010)
@@ -19,17 +19,17 @@
    [
       [`integral_mask` type]
       [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/integral_mask.hpp <boost/integer/integral_mask.hpp>]]]
-      [ Header contains `integral_mask` type. ]
+      [ Header contains `integral_mask` template. ]
    ]
    [
       [`high_bits_mask` type]
       [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/high_bits_mask.hpp <boost/integer/high_bits_mask.hpp>]]]
-      [ Header contains `high_bits_mask` type. ]
+      [ Header contains `high_bits_mask` template. ]
    ]
    [
       [`low_bits_mask` type]
       [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/low_bits_mask.hpp <boost/integer/low_bits_mask.hpp>]]]
-      [ Header contains `low_bits_mask` type. ]
+      [ Header contains `low_bits_mask` template. ]
    ]
 
    [
@@ -38,14 +38,19 @@
       [ Header contains includes for `high_bits_mask` and `low_bits_mask`. ]
    ]
    [
+      [ `bits_mask` type and `low_bits_mask` type ]
+      [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/bits_mask.hpp <boost/integer/bits_mask.hpp>]]]
+      [ Header contains `bits_mask` template. ]
+   ]
+   [
       [`compound_mask` type]
       [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/compound_mask.hpp <boost/integer/compound_mask.hpp>]]]
-      [ Header contains `compound_mask` type. ]
+      [ Header contains `compound_mask` meta-function. ]
    ]
    [
       [`bit_mask_group` type]
       [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/bit_masks/boost/integer/bit_mask_group.hpp <boost/integer/bit_mask_group.hpp>]]]
-      [ Header contains `bit_mask_group` type. ]
+      [ Header contains `bit_mask_group` meta-function/container. ]
    ]
 ]
 
@@ -90,3 +95,4 @@
 [include:integral_mask integral_mask.qbk]
 [include:high_bits_mask high_bits.qbk]
 [include:low_bits_mask low_bits.qbk]
+[include:bits_mask bits_mask.qbk]