Boost logo

Boost-Commit :

Subject: [Boost-commit] svn:boost r63553 - in sandbox/SOC/2010/bit_masks: boost/integer lib/integer/doc/bft_doc/appendices/implementation
From: bbartmanboost_at_[hidden]
Date: 2010-07-03 14:28:28


Author: bbartman
Date: 2010-07-03 14:28:28 EDT (Sat, 03 Jul 2010)
New Revision: 63553
URL: http://svn.boost.org/trac/boost/changeset/63553

Log:
working on creating external docuemtation for bitfield_tuple class template

Added:
   sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/appendices/implementation/internal_class_reference.qbk (contents, props changed)
Text files modified:
   sandbox/SOC/2010/bit_masks/boost/integer/bitfield_tuple.hpp | 290 ----------------------------------------
   1 files changed, 0 insertions(+), 290 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-07-03 14:28:28 EDT (Sat, 03 Jul 2010)
@@ -26,297 +26,7 @@
 
 namespace boost {
 
-// TODO Move documentation into the correct place and redo with boostbook
-// formatting.
 
-/** 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;
- *
-
-Note: reference first example to talk about member because this gets confusing.
-
- * Members
- * Unlike the storage type the member types are stored in the bitfield_tuple
- * the same way as they are specified in the template parameters. 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 the bitfield_tuple by using the supplied name,
- * bool_one is this case, or by the index which it was specified in the
- * template parameters excluding the storage type parameter. This means that
- * the members 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
- * bitfield_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.
- *
- * bitfield_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
- * bitfield_ref( bitfield_ref<MaskInfo> const&);
- * bitfield_ref( storage_type& ref);
- * private constructors
- * bitfield_ref();
- *
- * functions
- * operator return_type() // implicit conversion operator
- * bitfield_ref<MaskInfo> const& operator=(return_type const& rhs);
- *
- *
- * const_bitfield_ref - Similar to the bitfield_ref class template how ever this
- * is a const representation a reference.
- * The only difference between const_bitfield_ref and bitfield_ref is that
- * const_bitfield_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 bitfield_ref or const_bitfield_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 bitfield_ref type thats convertible to bool and
- * information retrieving data or storing data in the correct bitfield.
- *
- * bitfield_ref<typename> get<typenam>(); // access by name.
- * const_bitfield_ref<typename> get<typenam>() const; // access by name.
- *
- * bitfield_ref<typename> get<size_t>(); // access by index.
- * const_bitfield_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 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.
- *
- * 5) The user must specify a storage type.
- *
- *
- * 6) The total width of the sum of all bit fields must not exceed the bit
- * width of the storage type.
- *
- *
- * bitfield_tuple boost.fusion extension
- *
- * The bitfield_tuple use boost.fusion to provide additional runtime
- * support. bitfield_tuple acts like an associative array, in terms of
- * boost.fusion extension support.
- *
- * The bitfield_tuple supports the following fusion functions and
- * meta-functions.
- *
- * begin
- * end
- * is_sequence
- * is_view
- * category_of
- * at
- * size
- * at_key
- * tag_of
- * and all intrinsic functions which are available because of the
- * implementation of the above functions.
- *
- *
- * bitfield_tuple fusion iterator support for functions and meta functions.
- *
- * deref
- * value_of
- * next
- * prior
- * distance
- * key_of
- * value_at_data
- * deref_data
- * advance
- *
- * Additional intrinsic functions are available for use with this iterator.
- *
- * The following is the category used to define the bitfield_tuple_iterators
- * iterator_facade category.
- *
- * struct bft_category
- * : boost::fusion::random_access_traversal_tag,
- * boost::fusion::associative_tag
- * { };
- *
- *
- * 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.
- * 3) Complete to_string member function.
- * I don't think I need this function.
- * 4) the type restrictions on storage may need to be relaxed.
- * 5) The if the storage type is a reference then possible allow for this type
- * to behave as reference to a bitfield_tuple instead of a bitfield type.
- * This would mean disabling the default constructor.
- *
- * 6) For second draft I would like to restructure the way the parsed
- * arguments are stored. Change from bitfield_elements to a pair
- * the first item being the key/name the second item being a bitfield.
- * Instead of returning a bitfield_ref class return a bitfield class.
- * this may be slightly more difficult then needed, because I need to store
- * both a const and non const version of a bitfield. But even I don't do
- * that I would like to change the way the reference class works.
- */
 template < BOOST_MAKE_BFT_TEMPLATE_PARAMS() >
 struct bitfield_tuple
     : protected details::bitfield_tuple_base<

Added: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/appendices/implementation/internal_class_reference.qbk
==============================================================================


Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk