[Boost-commit] svn:boost r63113 - in sandbox/SOC/2010/bit_masks: boost/integer boost/integer/details boost/integer/details/bft lib/integer/test lib/integer/test/bft_testing/compile_fail

Subject: [Boost-commit] svn:boost r63113 - in sandbox/SOC/2010/bit_masks: boost/integer boost/integer/details boost/integer/details/bft lib/integer/test lib/integer/test/bft_testing/compile_fail
From: bbartmanboost_at_[hidden]
Date: 2010-06-19 15:35:06

Author: bbartman
Date: 2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
New Revision: 63113
URL: http://svn.boost.org/trac/boost/changeset/63113

Log:
working on adding preconditions and additional documentation for the bitfield tuple
Text files modified: 
   sandbox/SOC/2010/bit_masks/boost/integer/bitfield_tuple.hpp                                    |   282 +++++++++++++++++++++++++++++++++++++-- 
   sandbox/SOC/2010/bit_masks/boost/integer/details/bft/arg_parse_impl.hpp                        |     3                                         
   sandbox/SOC/2010/bit_masks/boost/integer/details/member.hpp                                    |     4                                         
   sandbox/SOC/2010/bit_masks/lib/integer/test/Jamfile.v2                                         |     1                                         
   sandbox/SOC/2010/bit_masks/lib/integer/test/bft_testing/compile_fail/member_width_to_large.cpp |    16 ++                                      
   sandbox/SOC/2010/bit_masks/lib/integer/test/bitfield_tuple_test.cpp                            |    28 ---                                     
   6 files changed, 284 insertions(+), 50 deletions(-)

Modified: sandbox/SOC/2010/bit_masks/boost/integer/bitfield_tuple.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/bitfield_tuple.hpp	(original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/bitfield_tuple.hpp	2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
@@ -21,6 +21,242 @@
 
 namespace boost {
 
+/** bitfield_tuple
+ *  Description
+ *  This is a type which provides access to bitfields stored within integers
+ *  or other integral types (see future work, for extensions). This is a pseudo
+ *  variadic type. It currently only takes up to 10 parameters but I will be 
+ *  extending that to be adjustable via macro similar to the MPL. Each of the 
+ *  template parameters must be supplied as either a storage template or a 
+ *  member template. For example, if one wanted to declare a bitfield_tuple
+ *  that was the size of one byte and contained two boolean bitfields and 
+ *  two integers they would do the following,
+ *  
+ *  #include <boost/integer/bitfield_tuple.hpp>
+ *  #include <boost/assert.hpp>
+ *  struct bool_one;
+ *  struct bool_two;
+ *  struct int_one;
+ *  struct int_two;
+ *
+ *  typedef bitfield_tuple<
+ *      storage<char>,
+ *      member<bool,bool_one,1>,
+ *      member<bool,bool_two,1>,
+ *      member<int,int_one,2>,
+ *      member<int,int_two,2>
+ *  >                       example_type;
+ *
+ *  int main() {
+ *      example_type temp;
+ *      temp.get<bool_one>() = false; // assigns false to the first bitfield.
+ *      temp.get<bool_two>() = true;  // assigns false to the second bitfield.
+ *      temp.get<2>()        = -1;    // assigns -1 to the first integer 
+ *                                    // bitfield.
+ *
+ *      BOOST_ASSERT(( temp.get<2>()  == -1 )); // this passes the assert and 
+ *                                              // does not exit the program
+ *  }
+ *
+ *  Storage and Members 
+ *  The storage type can be specified anywhere with in the template parameters.
+ *  Here is an example of how one may wish to specify storage,
+ *  
+ *  typedef bitfield_tuple<
+ *      member<bool,bool_one,1>,
+ *      storage<char>,
+ *      member<bool,bool_one,1>,
+ *      member<int,int_one,2>,
+ *      member<int,int_two,2>
+ *  >                       example_2_type;
+ *  
+ *  The example_2_type above creates the same internal structure and
+ *  functionality as example_type in the first example. All the storage template
+ *  does is specify the type your internal storage takes and may be returned as.
+ *
+ *  storage template signature
+ *  template <typename StorageType> storage;
+ *
+ *  Members 
+ *  Unlike storage the order of member types the order in which they are  
+ *  specified and the order in which they are stored within the bitfield_tuple.
+ *  The template parameters for member are the same as specifying a regular 
+ *  bitfield in C or C++, so, the first parameter is the type, second is the 
+ *  name of that variable in this case its a tag class or something of that 
+ *  nature  and third is the width of the bitfield in bits. For example,
+ *
+ *  member<bool, bool_one,1>
+ *
+ *  specifies that the type stored within 1 bit is of type bool and is 
+ *  accessible from within a bitfield_tuple by using the supplied name bool_one 
+ *  or the index at which it was specified relative to the number of other 
+ *  members specified ahead of it and not counting the storage type. This means 
+ *  that the fields specified are accessible by either an unsigned integral 
+ *  constant or by the name provided in side the member template.
+ *
+ *
+ *
+ *  Interface overview
+ *
+ *  bft is a bitfield tuple like those mentioned in previous examples. 
+ *
+ *  Public Typedefs
+ *      bft::members      - This is an mpl::vector which contains 
+ *                          bitfield_elements. A bitfield_element is an internal
+ *                          type used to specify information about the bitfields
+ *                          which make up the bitfield_tuple. The reason that 
+ *                          this is public, is for the boost.fusion extension of
+ *                          this data structure.
+ *
+ *      bft::storage_type - The type specified inside the storage template.
+ *
+ *      bft::bits_used    - This is an integral_constant type that specifies
+ *                          the total number of bits used by all bitfields.
+ *
+ *
+ *  bitfield_tuple internal Class templates
+ *      bit_ref           - Template is a reference type which takes one
+ *                          parameter which is expected to be of type 
+ *                          bitfield_element and creates a proxy reference type
+ *                          to the element specified by the bitfield_element.
+ *
+ *      bit_ref interface
+ *          public typedefs
+ *              return_type - The type which is to be returned from a specified
+ *                            bitfield.
+ *              bitfield_type - this is of type boost::integer::bitfield located
+ *                              within the boost.vault. The bitfield type is
+ *                              used to deal with more complicated issues such
+ *                              as endianness within the internal storage type.
+ *
+ *          constructors
+ *              bit_ref( bit_ref<MaskInfo> const&);
+ *              bit_ref( storage_type& ref);
+ *          private constructors
+ *              bit_ref();
+ *
+ *          functions
+ *              operator return_type() // implicit conversion operator
+ *              bit_ref<MaskInfo> const& operator=(return_type const& rhs);
+ *
+ *
+ *      const_bit_ref   - Similar to the bit_ref class template how ever this
+ *                        is a const representation a reference.
+ *          The only difference between const_bit_ref and bit_ref is that
+ *          const_bit_ref does not define an assignment operator.
+ *
+ *
+ *  bitfield_tuple constructors
+ *  
+ *      bitfield_tuple() - Default constructor.
+ *
+ *      bitfield_tuple (storage_type const& x); - Construction over the 
+ *          storage_type. This provides a means of constructing a bitfield
+ *          tuple over an initial storage type.
+ *
+ *      bitfield_tuple( bitfield_tuple<T0..T9> const& x); - Copy constructor.
+ *
+ *  Future work - Constructors - Incomplete and Possible Extensions
+ *
+ *      bitfield_tuple( ... ); - Member Wise Constructor -
+ *          Description: a constructor which will take as many values as there 
+ *          are members and put each one of those values into the tuple in 
+ *          the same order that the bitfields are specified.
+ *
+ *
+ *      template <typename T> bitfield_tuple(T const& x);
+ *          - Bitfield_tuple which have the same members but storage is 
+ *          in a different place within the template parameters.
+ *          Just haven't gotten around to implementing it, yet.
+ *
+ *  Bitfield_tuple assignment operators
+ *
+ *      bitfield_tuple<T0..T9> const& operator=( storage_type const& new_value);
+ *          storage type assignment. Allows for the user to assign a perticular
+ *          value to the tuples internal storage.
+ *
+ *      bitfield_tuple<T0..T9> const& operator=(_self const& x);
+ *          copy assignment operator.
+ *
+ *
+ *  bitfield_tuple Member Functions.
+ *
+ *      Rationale for creation of data member function.
+ *      This is the only way I was able to make the boost.fusion extension 
+ *      work for this data structure. Thats the reason that data returns
+ *      a reference instead of a copy of the integer value.
+ *
+ *      storage_type const& data() const; 
+ *          - returns a const reference to the data inside of the 
+ *          bitfield_tuple.
+ *
+ *      storage_type& data(); 
+ *          - returns a reference to the data inside of the bitfield_tuple.
+ *          
+ *  get function
+ *      - The get function returns a bit_ref or const_bit_ref which is 
+ *      convertible to the type specified in the first template parameter of the
+ *      member type, that corresponds to the bit field being accessed. For
+ *      example, using example_type from the first example, if the get function
+ *      is called in the following manner, temp.get<bool_one>(), the return type
+ *      for get in this case is a bit_ref type thats convertible to bool and 
+ *      information retrieving data or storing data in the correct bitfield.
+ *
+ *      bit_ref<typename> get<typenam>(); // access by name.
+ *      const_bit_ref<typename> get<typenam>() const; // access by name.
+ *
+ *      bit_ref<typename> get<size_t>(); // access by index.
+ *      const_bit_ref<typename> get<size_t>() const; // access by index.
+ *
+ *
+ *  All get functions provide constant time run time access to the bitfield to
+ *  which they correspond.
+ *
+ *  Currently they get function WILL NOT throw if the value provided exceeds the
+ *  capacity of of the number of bits being used to store a particular value.
+ *
+ *  If an invalid name or index is provided to a get function it will result in 
+ *  look up failure.
+ *
+ *
+ *  Enforced preconditions of the bitfield_tuple template
+ *
+ *      All of these preconditions listed here result in static assertions if 
+ *  the bitfield_tuple template is instantiated. 
+ *
+ *  1) The storage policy must not be specified more then once within the 
+ *      template parameters of bitfield_tuple template.
+ *
+ *  2) A member can not have the same name type as another member.
+ *
+ *  3) The width of a member can not be 0.
+ *  
+ *  4) The width of a member can not exceed the width of its return type.
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ *  future work/plans/thoughts
+ *  1) Switch to optionally deduced internal type.
+ *  2) Switch the internal storage to an array which will allow the user
+ *      to store as many fields as the which to, with out the constraint of
+ *      being limited to an integral type. 
+ */
 template <  typename T0,
             typename T1 = mpl::void_,
             typename T2 = mpl::void_,
@@ -42,7 +278,6 @@
     typedef bitfield_tuple<T0,T1,T2,T3,T4,T5,T6,T7,T8,T9>  _self;
 
 public:
-    typedef typename _base::processed_args          processed_args;
     typedef typename _base::field_vector            members;
     typedef typename _base::storage_type            storage_type;
     typedef typename _base::offset                  bits_used;
@@ -53,15 +288,17 @@
      */
     template <typename MaskInfo>
     struct bit_ref {
-
-        typedef typename MaskInfo::return_type                  return_type;       
+    private:
         typedef bit_ref<MaskInfo>                               _self;
         typedef typename make_unsigned<
             storage_type
         >::type                                           unsigned_storage_type;
+    public:
+        typedef typename MaskInfo::return_type                  return_type;
 
-        /** Internals bitfield type for extracting individual fields from 
-         *  within the storage_type.
+        /** Internals.
+         *  bitfield type for extracting individual fields from within the
+         *  storage_type.
          */
         typedef typename integer::bitfield<
             unsigned_storage_type,
@@ -71,11 +308,8 @@
         >                                                       bitfield_type;
 
 
-        /** Reference constructor.
-         *  Because the bit_ref is an abstraction of a reference then it also
-         *  must behave like a reference type.
-         */
-        bit_ref(storage_type& ref, int = 0)
+        /** Reference constructor. */
+        bit_ref(storage_type& ref)
             :_ref( *reinterpret_cast<unsigned_storage_type*>(&ref) )
         { }
 
@@ -117,12 +351,13 @@
      */
     template <typename MaskInfo>
     struct const_bit_ref {
-
-        typedef typename MaskInfo::return_type             return_type;       
+    private:
         typedef bit_ref<MaskInfo>                               _self;
         typedef typename make_unsigned<
             storage_type
         >::type const                                     unsigned_storage_type;
+    public:
+        typedef typename MaskInfo::return_type             return_type;       
 
         /** Internals bitfield type for extracting individual fields from 
          *  within the storage_type.
@@ -132,13 +367,10 @@
             MaskInfo::offset::value,
             MaskInfo::offset::value + MaskInfo::field_width::value - 1,
             return_type
-        >                                                       bitfield_type;
+        >                                                   bitfield_type;
 
 
-        /** Reference constructor.
-         *  Because the bit_ref is an abstraction of a reference then it also
-         *  must behave like a reference type.
-         */
+        /** Reference constructor. */
         const_bit_ref(storage_type const& ref)
             :_ref( *reinterpret_cast<unsigned_storage_type*>(&ref) )
         { }
@@ -188,17 +420,25 @@
      *      TODO: The signature of this will need to change possibly to
      *      use enable_if or some form of internal dispatching.
      *  XXX
-     *  TODO: look into the creation of a member wise constructor.
      */
     template <typename T>  bitfield_tuple(T const& x);
 
+     // TODO: look into the creation of a member wise constructor.
 
 
-    /** Assignment Operator.
-     * Provides assignment from this type to another.
+    /** Assignment from an integer
+     *  Allows for the user to assign a type which they wish for this type to
+     *  access.
+     */
+    _self const& operator=( storage_type const& new_value) {
+        _data = new_value;
+    }
+
+    /** Copy Assignment Operator.
+     *  Provides assignment from this type to another.
      */
     _self const& operator=(_self const& x) {
-        this->_data = x._data;
+        _data = x._data;
     }
 
     /** Internal storage accessors

Modified: sandbox/SOC/2010/bit_masks/boost/integer/details/bft/arg_parse_impl.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/details/bft/arg_parse_impl.hpp	(original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/details/bft/arg_parse_impl.hpp	2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
@@ -99,7 +99,6 @@
  *  Documented and enforced preconditions
  *      1. The user must not supply the same name for more then 1 parameter
  *      (This may result in additional overhead during compile time ).
- *      Currently not enforced, will take more time then I have at the moment.
  */
 template <  typename StoragePolicy,
             typename FieldVector,
@@ -133,6 +132,8 @@
             >::type
         >::value            
     ));
+
+
     typedef member< ReturnType, NameType, FieldWidth > param;
 
     // typedef 

Modified: sandbox/SOC/2010/bit_masks/boost/integer/details/member.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/details/member.hpp	(original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/details/member.hpp	2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
@@ -10,6 +10,9 @@
 #include <boost/type_traits.hpp>
 #include <boost/static_assert.hpp>
 #include <boost/mpl/size_t.hpp>
+#include <boost/integer/bit_width.hpp>
+
+
 namespace boost {
 
 
@@ -26,6 +29,7 @@
 template <typename ReturnType, typename Name, std::size_t FieldWidth>
 struct member {
     BOOST_STATIC_ASSERT(( FieldWidth != 0 ));
+    BOOST_STATIC_ASSERT(( FieldWidth <= bit_width<ReturnType>::value ));
     typedef ReturnType return_type;
     typedef Name name_type;
     BOOST_STATIC_CONSTANT(std::size_t, field_width  = FieldWidth);

Modified: sandbox/SOC/2010/bit_masks/lib/integer/test/Jamfile.v2
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/test/Jamfile.v2	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/test/Jamfile.v2	2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
@@ -26,6 +26,7 @@
         [ run compound_mask_test.cpp ]
         [ run bit_mask_group_test.cpp ]
         [ compile-fail bft_testing/compile_fail/member_precond_width_zero.cpp ]
+        [ compile-fail bft_testing/compile_fail/member_width_to_large.cpp ]
         [ compile-fail bft_testing/compile_fail/bft_no_storage_type.cpp ]
         [ compile-fail bft_testing/compile_fail/non_pod_storage_type.cpp ]
         [ compile-fail bft_testing/compile_fail/bft_storage_width_acceded.cpp ]

Modified: sandbox/SOC/2010/bit_masks/lib/integer/test/bft_testing/compile_fail/member_width_to_large.cpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/test/bft_testing/compile_fail/member_width_to_large.cpp	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/test/bft_testing/compile_fail/member_width_to_large.cpp	2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
@@ -0,0 +1,16 @@
+//  Copyright 2010 Brian Bartman.
+//  Distributed under the Boost Software License, Version 1.0.
+//  (See accompanying file LICENSE_1_0.txt or copy at 
+//  http://www.boost.org/LICENSE_1_0.txt)
+
+
+#include <boost/integer/details/member.hpp>
+
+using namespace boost;
+
+// this fails because the type in side member is to large for the return type.
+struct pink;
+
+int main() {
+    typedef member<int, pink, 33>::type failure;
+}

Modified: sandbox/SOC/2010/bit_masks/lib/integer/test/bitfield_tuple_test.cpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/test/bitfield_tuple_test.cpp	(original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/test/bitfield_tuple_test.cpp	2010-06-19 15:35:04 EDT (Sat, 19 Jun 2010)
@@ -51,34 +51,6 @@
 
     }
 
-    // testing for parsing of aruments passed into template parameters.    
-    {
-    
-    typedef bitfield_tuple< storage<int>, member<int,red,3> > bft;
-    typedef bft::processed_args pa;
-
-    // checking for storage type.
-    BOOST_MPL_ASSERT((
-        is_same<
-            pa::storage_policy,
-            storage<int>
-        >
-    ));
-
-    BOOST_MPL_ASSERT((
-        is_same<
-            mpl::front< pa::field_vector >::type,
-            details::bitfield_element<
-                int,
-                red,
-                mpl::size_t<0>,
-                mpl::size_t<3> 
-            > 
-        >
-    ));
-
-    }
-
     // bitfield_tuple runtime tests.
     {
         // default constructor.