|
|
Boost-Commit : |
Subject: [Boost-commit] svn:boost r64939 - in sandbox/SOC/2010/bit_masks: . boost/integer boost/integer/detail/bft lib/integer/doc lib/integer/doc/bft_doc/overview lib/integer/doc/bft_doc/reference/class_reference lib/integer/doc/bft_doc/users_guide lib/integer/doc/bft_doc/users_guide/getting_started
From: bbartmanboost_at_[hidden]
Date: 2010-08-21 16:08:14
Author: bbartman
Date: 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
New Revision: 64939
URL: http://svn.boost.org/trac/boost/changeset/64939
Log:
finished a large section of documentation
Added:
sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_width.qbk (contents, props changed)
Text files modified:
sandbox/SOC/2010/bit_masks/boost/integer/bits_mask.hpp | 2
sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/arg_parse_impl.hpp | 33 ++++++
sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/pointer_packing_policy.hpp | 4
sandbox/SOC/2010/bit_masks/boost/integer/high_bits_mask.hpp | 6
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/motivation.qbk | 12 ++
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/overview.qbk | 62 ++----------
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/align.qbk | 36 ++++++
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/bitfield_tuple.qbk | 8 +
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/custom.qbk | 199 +++++++++++++++++++++++++++++++++++++++
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/flag.qbk | 84 +++++++++++++---
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/member.qbk | 71 ++++++++++++--
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/padding.qbk | 39 ++++++-
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/pointer.qbk | 145 ++++++++++++++++++++++++++++
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/storage.qbk | 68 +++++++++++++
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/building.qbk | 4
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/dependencies.qbk | 169 +++++++++++----------------------
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/intallation.qbk | 4
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/testing.qbk | 17 ++
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/glossary.qbk | 5 +
sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/tutorial.qbk | 176 ++++++++++++++++++++++++++++++++---
sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_masks.qbk | 1
sandbox/SOC/2010/bit_masks/lib/integer/doc/bits_mask.qbk | 87 +++++++++-------
sandbox/SOC/2010/bit_masks/lib/integer/doc/high_bits.qbk | 38 ++++++-
sandbox/SOC/2010/bit_masks/lib/integer/doc/integral_mask.qbk | 9 +
sandbox/SOC/2010/bit_masks/lib/integer/doc/low_bits.qbk | 49 +++++++--
sandbox/SOC/2010/bit_masks/notes.txt | 196 ++++++++-------------------------------
26 files changed, 1068 insertions(+), 456 deletions(-)
Modified: sandbox/SOC/2010/bit_masks/boost/integer/bits_mask.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/bits_mask.hpp (original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/bits_mask.hpp 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -21,7 +21,7 @@
* Preconditions for bit_mask
* Pre-Conditions
*
- * 1. The width of the masked section must not be longer then the
+ * 1. The width + the offset of the masked section must not be longer then the
* mask itself.
*
* 2. Valid range for mask width is > 0.
Modified: sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/arg_parse_impl.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/arg_parse_impl.hpp (original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/arg_parse_impl.hpp 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -16,8 +16,6 @@
#include <boost/mpl/placeholders.hpp>
#include <boost/mpl/comparison.hpp>
#include <boost/mpl/logical.hpp>
-#include <boost/type_traits/add_pointer.hpp>
-
#include <boost/integer/bitfield_tuple/storage.hpp>
#include <boost/integer/bitfield_tuple/member.hpp>
@@ -323,6 +321,21 @@
{
// PRECONDITION: Value bits of the mask Can't be 0.
BOOST_STATIC_ASSERT(( Mask::value != 0 ));
+ // make sure that the name doesn't already exist.
+ BOOST_STATIC_ASSERT((
+ is_same<
+ typename mpl::find_if<
+ FieldVector,
+ detail::match_name<
+ mpl::_1,
+ Name
+ >
+ >::type,
+ typename mpl::end<
+ FieldVector
+ >::type
+ >::value
+ ));
typedef typename pointer_member::count_leading_zeros<
Mask
@@ -397,6 +410,22 @@
// PRECONDTION: type of mask::value_type must be the same size as a pointer.
BOOST_STATIC_ASSERT(( sizeof(typename Mask::value_type) == sizeof(void*) ));
+ // make sure that the name doesn't already exist.
+ BOOST_STATIC_ASSERT((
+ is_same<
+ typename mpl::find_if<
+ FieldVector,
+ detail::match_name<
+ mpl::_1,
+ Name
+ >
+ >::type,
+ typename mpl::end<
+ FieldVector
+ >::type
+ >::value
+ ));
+
typedef typename pointer_member::count_leading_zeros<
Mask>::type front_storage_space;
Modified: sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/pointer_packing_policy.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/pointer_packing_policy.hpp (original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/detail/bft/pointer_packing_policy.hpp 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -8,7 +8,7 @@
#define BOOST_BITFIELD_TUPLE_POINTER_PACKING_POLICY_HPP
#include <boost/integer/detail/bft/policy_creation_detail.hpp>
-namespace boost { namespace bitfields{ namespace detail {
+namespace boost { namespace bitfields { namespace detail {
template <
typename Mask,
@@ -17,7 +17,7 @@
typename Width
>
struct pointer_packing_policy {
- typedef Mask mask;
+ // typedef Mask mask;
typedef ValueType value_type;
template <typename StorageType>
Modified: sandbox/SOC/2010/bit_masks/boost/integer/high_bits_mask.hpp
==============================================================================
--- sandbox/SOC/2010/bit_masks/boost/integer/high_bits_mask.hpp (original)
+++ sandbox/SOC/2010/bit_masks/boost/integer/high_bits_mask.hpp 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -34,7 +34,7 @@
mpl::size_t<Width>
>::type::value))
));
- typedef integral_constant<T, val> type;
+ typedef integral_mask<T, val> type;
};
// long long specialization
template<unsigned int Width>
@@ -44,7 +44,7 @@
mpl::size_t<Width>
>::type::value)
));
- typedef integral_constant<long long, val> type;
+ typedef integral_mask<long long, val> type;
};
// unsigned long long specialization
template<unsigned int Width>
@@ -54,7 +54,7 @@
mpl::size_t<Width>
>::type::value)
));
- typedef integral_constant<unsigned long long, val> type;
+ typedef integral_mask<unsigned long long, val> type;
};
}
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/motivation.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/motivation.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/motivation.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -34,4 +34,16 @@
`struct foo` has a `sizeof` 4 bytes, while `example_type` is storing its data
within in a single byte. One can imagine the problems that arise from creating
a `union` of `struct foo` with a `char` type.
+
+
+One of the more advanced use cases for the bitfield_tuple is to create a simple
+method for storing bit stuff pointers and other integral types which may have
+additional bit which are not being used. Pointers which are aligned to
+DWORD boundaries have the last to bits always zero. Those last two bits can be
+used for storing a 2 bit integral type or two boolean values. Another use case
+for the bit stuffing abilities of this data structure is to allowing for bit
+stuffing of anything which may have always empty bits. For instance, if an
+integer is always an even number then the last bit is always going to be
+zero and that could be used for storing a boolean value.
+
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/overview.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/overview.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/overview/overview.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -33,7 +33,7 @@
storing the bitfields within is going to be an unsigned short. The
`member<unsigned int, red, 5>` member is used to specify a bitfield within the
`bitfield_tuple`. Here is how `member` works, and relates directly back to
-regular reconizable C++.
+regular recognizable C++.
[table
[
[`bitfield_tuple`]
@@ -125,56 +125,16 @@
without the hassle of doing the masking themselves.
-One might be wondering just what is the benefit of doing all of this extra work
-for something that seems much easier to do using conventional means? Well the
-`bitfield_tuple` is used to abstract the storage and retrieval of data into and
-out of an integral type, by doing so allows for the storage and retrieval
-of types with different endianness.
-
-[/
-
-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;
+There are many more complex examples to follow through out this documentation,
+but for the sake of brevity they are not listed within this section and are
+instead listed in the example section. Here is a brief description of the
+different things one can accomplish with the bitfield_tuple:
+
+* Bit stuffing pointers.
+* Bit stuffing into integral types.
+* Custom encoding and decoding of the storage of bits within an integral or
+integral like type.
+* Using non-POD types for storage.
-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
- BOOST_ASSERT(( temp.get<int_one>() == -1 )); // this passes the assert and
- // does not exit the program
-}
-``
-Within the above example the template `bitfield_tuple` is specified using
-multiple other templates which are used to describe different fields and
-the internal type in which the bitfields will reside. In the above example
-`storage<char>` means that the internal storage type used will be type
-`char`. The template member is used to specify a bitfield within the tuple.
-For instance, looking at `member<bool,bool_one,1>`, the first parameter is
-used to describe the type which the stored value will be returned as. The second
-parameter, `bool_one`, is a name type which can be used to retrieve the a
-bitfield from with in the `bitfield_tuple`. The third and final parameter is
-the width of the a bitfield in bits, the template `member<bool,bool_one,1>` will
-have a width of one.
-]
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/align.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/align.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/align.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -18,9 +18,19 @@
``
namespace boost { namespace bitfields {
template <std::size_t AlignTo> struct align;
-}} // end boost::bitfields
+}}
``
-
+[h4 Template Parameters]
+[table
+ [
+ [template Parameter]
+ [Explanation]
+ ]
+ [
+ [`AlignTo`]
+ [The value that the next bitfield's first bit should be a multiple of.]
+ ]
+]
[h4 Header file Locaton]
This header file is included with the <boost/integer/bitfield_tuple.hpp> header
@@ -30,5 +40,25 @@
``
[h4 Example]
``
-``
+#include <boost/integer/bitfield_tuple.hpp>
+using namespace boost::bitfields;
+struct i;
+struct red;
+struct green;
+struct blue;
+
+typedef bitfield_tuple<
+ storage<unsigned long long>,
+ member<unsigned int,red,5>,
+ member<unsigned int, green, 6>,
+ member<unsinged int, blue,5>,
+ align<32>,
+ member<int,i,32>
+> color_plus_int;
+``
+With in the above example the first 3 fields are the size of a short then the
+alignment is pushed up to the next boundary and a full sized integer is
+then stored at the end. This actually does make accessing slightly for the
+integer.
+
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/bitfield_tuple.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/bitfield_tuple.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/bitfield_tuple.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -47,7 +47,9 @@
[h5 Template Signature]
``
-tempate <typename... Args> struct bitfield_tuple;
+namespace boost { namespace bitfields {
+template <typename... Args> struct bitfield_tuple;
+}}
``
For additional information on creating specilizations over the
`bitfield_tuple`'s implementation documentation reguarding macros.
@@ -87,7 +89,7 @@
[h5 Template Members]
The `bitfield_reference` type is responsible for acting as the proxy reference
-type into the storage of a `bitfield_tuple`, This works similar to the proxy
+type into the storage of a `bitfield_tuple`. This works similar to the proxy
reference type supplied by `std::vector<bool>` specilization.
[note If one wishes to work with the reference direcrly please not that the
@@ -323,7 +325,7 @@
is because the `mpl::vector` doesn't support more then 50 parameters. Please see
documentation `BOOST_BFT_PARAM_COUNT` under macro reference section for
additional information regarding the `BOOST_BFT_PARAM_COUNT` macro. ]
- [ Enforced macro macro error message. ]
+ [ Enforced by macro error message. ]
]
[
[ Don't set `BOOST_MPL_LIMIT_VECTOR_SIZE` to be less then
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/custom.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/custom.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/custom.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -6,7 +6,11 @@
]
[section `struct custom`]
[h4 Description]
-
+The `custom` member is a template which is used to do to integers what `pointer`
+does to pointers. That being said, the custom class allows for semi-intrusive
+behavior with regards to the storage of `bitfield_tuple`. In the simplest use
+cases the `custom` member will only ever take three template parameters and
+will use the default policy which is supplied.
[h4 Template Signature]
``
@@ -19,9 +23,66 @@
class Policy = detail::custom_packing_policy
>
struct custom;
-}} // end boost::bitfields
+}}
``
+[h4 Template Parameters]
+[table
+ [
+ [template Parameter]
+ [Explanation]
+ ]
+ [
+ [`ReturnType`]
+ [The type that the value is to be returned from the get function as.You
+may supply a signed type for a member but please note that a singed bit will be
+stored within the width you specify, so if you don't need negative values you
+should not store them.]
+ ]
+ [
+ [`Name`]
+ [This is a type which is associated with the bitfield which is
+represented by this member template.]
+ ]
+ [
+ [`Mask`]
+ [ This is a mask which minimally defines the following two `typedef`s and
+static constant: `Mask::type`, `Mask::value_type`, and `Mask::value`. There are
+masking utilities which are included with `bitfield_tuple` which make using this
+parameter easier. ]
+ ]
+ [
+ [`Policy`]
+ [ See below in the `Policy` Section of this page. Default behavior is to
+apply the Mask to the incoming information and extract it, shift the new
+information to the correct location of the bitfield within the `bitfield_tuples`
+storage. The next step is to take the complement of the current shifted mask and
+& that with the storage, and | that with the shifted value then store that in the
+`bitfield_tuple`'s storage. The similar is done to get the information out of the
+`bitfield_tuple`'s storage. *For MOST cases this will NOT have to be used and the
+default case will work just fine.* ]
+ ]
+]
+
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ `Mask::value != 0` ]
+ [ The value associated with the mask can not be zero. ]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ `Name` must be unique. ]
+ [ The `Name` template parameter can only be supplied once per
+`bitfield_tuple`. ]
+ [ Enforced by static assert. ]
+ ]
+]
@@ -31,7 +92,139 @@
``
#include <boost/integer/details/bft/custom.hpp>
``
-[h4 Example]
+
+[h4 Examples]
+[h5 Using a `custom` member to store the 16 most significant bits of an integer]
``
+#include <boost/integer/bifield_tuple.hpp>
+
+using namespace boost::bitifields;
+typedef boost::high_bits_mask<unsigned int, 16> top16bits;
+struct int1;
+struct int2;
+typedef bitfield_tuple<
+ storage<unsigned int>,
+ custom<unsigned int, int1, top16bits>,
+ member<unsigned int, int2, 16>
+> two_different_halves;
+``
+`custom` members are accessed just the same as every other member within a
+`bitfield_tuple` by simply using the get function followed by its index or
+`Name`.
+
+[h4 How to Define a Policy For a Custom Member]
+As stated before, if the previous case works for you then this is unnecessary.
+Defining a policy is only necessary when you need to do custom packing of a type
+before it's stored and custom unpack before it's returned. Custom packing means
+that you are storing a mass of normally non contiguous bits in a contiguous
+manner and expanding them to be non-contiguous afterwards.
+
+
+The template signature of a policy, as seen above in the template parameters,
+table takes 4 arguments. Here is what to expect for each of those template
+arguments.
+``
+template <typename Mask, typename ValueType, typename Offset, typename Width>
+struct my_policy;
+``
+[h5 Policy Parameter Description]
+[table
+ [
+ [Parameter Name]
+ [Description]
+ ]
+ [
+ [`Mask`]
+ [ `Mask` is the template parameter which was supplied to the `custom`
+member as a `Mask`. ]
+ ]
+ [
+ [`ValueType`]
+ [ This is the type which was supplied to the `custom` template as the
+`ReturnType`.]
+ ]
+ [
+ [`Offset`]
+ [ This of type `mpl::size_t<`['Implementation Defined]`>` which is used
+to denote the number of bits from the least significant bit the field is
+supposed to be.]
+ ]
+ [
+ [`Width`]
+ [ This of type `mpl::size_t<`['Implementation Defined]`>`. The width is
+deduced from the mask supplied to the `bitfield_tuple` based on leading and
+trailing zeros within `Mask`. ]
+ ]
+]
+
+[h5 Policy Body]
+The body of the class template must contain the following `typedef` and
+member template.
+[table
+ [
+ [Type]
+ [Description]
+ ]
+ [
+ [`value_type`]
+ [ This is the ValueType which was supplied to the policy. If the
+`typedef` isn't the same as ValueType it could cause problems however there is
+nothing enforcing this. So if you attempt to specify a different type for
+value_type then ValueType do so at your own risk. ]
+ ]
+ [
+ [`template<typename StorageType> struct apply;`]
+ [ Because at the time the policy is being instantiated and kept for
+later use the type of the storage may not be known yet. It has to be passed in
+at a later time. The `StorageType` in the apply member template refers to the
+integral type which the `bitfield_tuple` is using for storing its bitfields. ]
+ ]
+
+]
+[tip I recommend that if you wish to specialize the policy you do so by
+having the `template<typename StorageType> struct apply;` inherit something
+which takes all five template parameters in scope: `Mask`, `ValueType`,
+`Offset`, `Width` and `StorageType` and then define the necessary
+two static functions there.
+]
+
+[h5 The `apply` member template]
+The apply member template is where the actual magic happens so to speak. The
+apply template defines two static functions. The two static functions
+are what is called to preform the actual storage and retrieval of the bitfield
+itself.
+
+[table
+ [
+ [Static Function]
+ [Description]
+ ]
+ [
+ [`static StorageType set(StorageType storage, ValueType value);`]
+ [ This function is used to set the value of the bitfield and store it
+inside of storage then return storage. The returned storage is set to the
+storage which `bitfield_tuple` uses.]
+ ]
+ [
+ [`static ValueType get(StorageType storage);`]
+ [ Retrieves the value of from `storage` which is the actual storage from
+within `bitfield_tuple` and returns the value of the bitfield.]
+ ]
+]
+
+[h5 Completed Policy Structure ]
+Example of what a completed policy will need to look like.
+``
+template <typename Mask, typename ValueType, typename Offset, typename Width>
+struct my_policy {
+
+ typedef ValueType value_type;
+
+ template <typename StorageType>
+ struct apply {
+ static ValueType get(StorageType storage);
+ static StorageType set(StorageType storage, ValueType value);
+ };
+};
``
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/flag.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/flag.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/flag.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -6,39 +6,85 @@
]
[section `struct flag`]
[h4 Description]
-`flag` is used to specify a boolean member of width one. For example,
-``
-struct red;
-
-typedef bitfield_tuple<
- flag<red>
-> bitfield_tuple_1;
-
-
-typedef btifield_tuple<
- member<bool,red,1>
-> bitfield_tuple_2;
-``
-the types `bitfield_tuple_1` and `bitfield_tuple_2` specify the same internal
-structure for their data. `flag<red>` has the same affect on a `bitfield_tuple`
-as `member<bool,red,1>` would have.
-
+`flag` is used to specify a boolean member of width one. This is a simplification
+of `member<bool,NameType,1>` and does the exact same thing.
[h4 Template Signature]
``
namespace boost { namespace bitfields {
template <typename Name> struct flag;
-}} // end boost::bitfields
+}}
``
+[h4 Template Parameters]
+[table
+ [[template Parameter][Explanation]]
+ [
+ [`Name`]
+ [ This is the name which can be used to access the template parameter
+using the get function. ]
+ ]
+]
+
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ `Name` must be unique. ]
+ [ The `Name` template parameter can only be supplied once per
+`bitfield_tuple`. ]
+ [ Enforced by static assert. ]
+ ]
+]
-[h4 Header file Locaton]
+[h4 Header File Location]
This header file is included with the <boost/integer/bitfield_tuple.hpp> header
file.
``
#include <boost/integer/details/bft/flag.hpp>
``
[h4 Example]
+This is the simplification which `flag` makes in comparison to writing the
+same thing using the `member` template.
+``
+struct b;
+
+typedef bitfield_tuple<
+ flag<b>
+> bitfield_tuple_1;
+
+
+typedef btifield_tuple<
+ member<bool,b,1>
+> bitfield_tuple_2;
``
+
+Example of how to use `flag` within the declaration of a `bitfield_tuple`
+template.
``
+#include <boost/integer/bitfield_tuple.hpp>
+
+using namespace boost::bitfields;
+
+struct b0;
+struct b1;
+struct b2;
+struct b3;
+struct something;
+
+typedef btifield_tuple<
+ flag<b0>,
+ flag<b1>,
+ flag<b2>,
+ flag<b3>,
+ member<unsigned int, something,4>
+> int_bool_size_char;
+``
+The above type is used to represent a char which is split between 4 `bool` values
+and a 4 bit `unsigned int`
+
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/member.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/member.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/member.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -5,16 +5,33 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section `struct member`]
+
[h4 Description]
-`member` us used for specifying different bitfields within a `bitfield_tuple`.
+`member` is used for specifying different bitfields within a `bitfield_tuple`. A
+`member` is meant to look like a bitfield when it is declared within a `class` or
+`struct`. A `member` is the most basic type of bitfield that can be used for a
+`bitfield_tuple`. When other templates used to specify a `bitfield_tuple` are
+noted as members, it means they have storage space as a bitfield within the
+`bitfield_tuple`.
+
+
+[h4 Template Signature]
+``
+namespace boost { namespace bitfields {
+template <typename ReturnType, typename NameType, std::size_t Width> struct member;
+}}
+``
+
+
+[h4 Template Parameters]
[table
[[template Parameter][Explanation]]
[
[`ReturnType`]
- [The type that the value is to be returnd from the get function as.You
+ [The type that the value is to be returned from the get function as.You
may supply a signed type for a member but please note that a singed bit will be
stored within the width you specify, so if you don't need negative values you
-shouldn't store them.]
+should not store them.]
]
[
[`NameType`]
@@ -29,13 +46,32 @@
]
]
-[h4 Template Signature]
-``
-namespace boost { namespace bitfields {
-template <typename ReturnType, typename NameType, std::size_t Width>
-struct member;
-}} // end boost::bitfields
-``
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ `Width != 0` ]
+ [ The `Width` template parameter must not be zero. ]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ `Width <= bit_width<ReturnType>::value` ]
+ [ The `Width` parameter of `member` must not exceed the width in bits
+of `ReturnType` template parameter.]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ `NameType` must be unique. ]
+ [ The `NameType` template parameter can only be supplied once per
+`bitfield_tuple`. ]
+ [ Enforced by static assert. ]
+ ]
+]
+
[h4 Header file Locaton]
@@ -46,5 +82,20 @@
``
[h4 Example]
``
+#include <boost/integer/bitfield_tuple.hpp>
+
+using namespace boost::bitfields;
+
+struct red;
+struct green;
+struct salmon;
+
+typedef bitfield_tuple<
+ member<char,red,4>,
+ member<unsigned char, green,5>,
+ member<int, salmon, 16>
+> color_tuple;
``
+The `member`s specified in `color_tuple` above are used to specify the different
+bitfields within the `bitfield_tuple`.
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/padding.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/padding.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/padding.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -6,20 +6,29 @@
]
[section `struct padding`]
[h4 Description]
-padding specifies a number of empty bits to be ignored. Another good way to think
-about this is as bit padding, it adds the number of bits in padding when
+`padding` specifies a number of empty bits to be ignored. Another good way to
+think about this is as bit padding, it adds the number of bits in padding when
specified. From an implementation stand point it adds `Bits` to the starting
the next starting position of the next bitfield specified in the template
-parameter list.
+parameter list. This class is used to give explicit control to the user
+when it comes to the internal storage of the bits within the `bitfield_tuple`.
[h4 Template Signature]
``
namespace boost { namespace bitfields {
template <std::size_t Bits> struct padding;
-}} // end boost::bitfields
+}}
``
-[h4 Header file Locaton]
+[h4 Template Parameters]
+
+[table
+ [[Parameter][Description]]
+ [[`Bits`][The amount of padding to add.]]
+]
+
+
+[h4 Header File Location]
This header file is included with the <boost/integer/bitfield_tuple.hpp> header
file.
``
@@ -27,5 +36,25 @@
``
[h4 Example]
``
+#include <boost\integer\bitfield_tuple.hpp>
+
+using namespace boost::bitfields;
+
+struct red;
+struct green;
+struct pink;
+struct blue;
+struct salmon;
+
+typedef bitfield_tuple<
+ storage<std::size_t>,
+ member<char,red,4>,
+ member<unsigned char, green,5>,
+ padding<3>,
+ member<int, salmon, 16>,
+ flag<blue>
+> tuple_with_padding;
``
+All the padding does in the above is shift the last two members over by 3 bits.
+
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/pointer.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/pointer.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/pointer.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -27,9 +27,62 @@
>
>
struct pointer;
-}} // end boost::bitfields
+}}
``
+[h4 Template Parameters]
+[table
+ [
+ [template Parameter]
+ [Explanation]
+ ]
+ [
+ [`ReturnType`]
+ [ This is the type which a pointer is being made to. ]
+ ]
+ [
+ [`Name`]
+ [ `Name` of the field which is can be used to access the field with the
+get function.]
+ ]
+ [
+ [`Mask`]
+ [ This is a mask which minimally defines the following two `typedef`s and
+static constant: `Mask::type`, `Mask::value_type`, and `Mask::value`. There are
+masking utilities which are included with `bitfield_tuple` which make using this
+parameter easier. The `Mask` is used to define the value bits of the pointer which
+are to be stored within the `bitfield_tuple`. The default value for this parameter
+is to define a `Mask` over an integral type which is the same size as a pointer, and
+leaves off the 2 least significant bits of the pointer. This is because on most
+32 and 64 bit architectures it is common for most allocation to be DWORD aligned,
+which makes the address divisible by 4. ]
+ ]
+]
+
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ `Mask::value != 0` ]
+ [ The value associated with the mask can not be zero. ]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ `sizeof(Mask::value_type) == sizeof(void*)` ]
+ [ The value type of the mask must be the same size as a pointer. ]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ `Name` must be unique. ]
+ [ The `Name` template parameter can only be supplied once per
+`bitfield_tuple`. ]
+ [ Enforced by static assert. ]
+ ]
+]
@@ -39,7 +92,95 @@
``
#include <boost/integer/details/bft/pointer.hpp>
``
-[h4 Example]
+[h4 Basic Example]
+Basic use case for stuffing the 2 least significant bits of a pointer.
+``
+#include <boost/integer/bitfield_tuple.hpp>
+
+using namespace boost::bitfields;
+
+struct ptr;
+struct b1;
+struct b2;
+
+typedef bitfield_tuple<
+ pointer<int, ptr>,
+ flag<b1>,
+ flag<b2>
+> bool_stuffed_ptr;
+
+
+
+int main() {
+ int* some_ptr = new int();
+ bool_stuffed_ptr bsp;
+ bsp.get<ptr>() = some_ptr;
+
+ // prints the value of the integer being pointed at.
+ std::cout << *bsp.get<ptr>() << std::endl;
+
+ return 0;
+}
+
+``
+The `bool_stuffed_ptr` type allows for a the `ptr` member to point to an integer
+which is DWORD aligned within memory and use the unused bits inside of it for
+storage of 2 additional boolean values. If a valid address has been stored for
+`ptr` the value returned from the get function will be dereferenceable just like
+a regular pointer.
+
+[h4 Mask Example]
+Example of how to define a the `Mask` parameter for differently aligned memory
+allocations. The following allocations are 8 byte aligned rather then 4 byte
+aligned, which leaves 3 bits instead of 2 bits.
``
+using namespace boost::bitfields;
+
+struct ptr;
+struct b1;
+struct b2;
+struct b3;
+
+typedef boost::high_bits_mask<
+ std::size_t,
+ bit_width<std::size_t>::value - 3
+> ptr_mask;
+
+typedef bitfield_tuple<
+ pointer<int, ptr, ptr_mask>,
+ flag<b1>,
+ flag<b2>,
+ flag<b3>
+> bool_stuffed_ptr;
``
+The `boost::high_bits_mask` defines a mask which starting at the most significant
+bit makes a contiguous section of 1 bits which are used to compose a mask.
+In the above example `high_bits_mask` is being used to create the following
+mask in binary (assuming a 32 bit architecture):
+[pre
+most significant bit least significant bit
+ 31 0
+ 1111 1111 1111 1111 1111 1111 1111 1000
+]
+
+
+[h5 Two Pointers and a 4 Bit Integer]
+The next example is how to on a 32 bit system to stuff two pointers to DWORD aligned
+memory and a 4 bit integer into a single `unsigned long long` type.
+``
+struct ptr1;
+struct ptr2;
+struct four_bit_int;
+
+typedef bitfield_tuple<
+ pointer<int, ptr1>,
+ pointer<int, ptr2>,
+ member<unsigned int,four_bit_int,4>
+> pointer_double_stuffed;
+``
+The `pointer` members are treated as bitfields and simply move around within
+the storage of the `bitfield_tuple` as a normal member would be. This can
+effect the access time but only by a shift operation to correctly place place
+the pointer to match the value bits of its mask.
+
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/storage.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/storage.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/reference/class_reference/storage.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -22,10 +22,45 @@
``
namespace boost { namespace bitfields {
template <typename StorageType> struct storage;
-}} // end boost::bitfields
+}}
``
+[h4 Template Parameters]
+[table
+ [
+ [template Parameter]
+ [Explanation]
+ ]
+ [
+ [`StorageType`]
+ [ The storage type to be used for storing data inside of the
+`bitfield_tuple`. ]
+ ]
+]
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ storage type can be supplied 0 or 1 times for the `bitfield_tuple`. ]
+ [ The `storage` not be specified more then once per inside of the template
+parameters for a single `bitfield_tuple`. ]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ Total width of all bitfields in a single `bitfield_tuple` can not
+exceed the width in bits of the storage type when the storage type is specified
+or 64 bits when a storage type is not specified if you system supports some form
+64 bit integer other wise the limit is set to 32 bits. ]
+ [ This is a limitation on the internal storage that `bitfield_tuple` uses
+to hold its bitfields. ]
+ [ Enforced by static assert. ]
+ ]
+]
[h4 Header file Locaton]
@@ -35,6 +70,37 @@
#include <boost/integer/details/bft/storage.hpp>
``
[h4 Example]
+
+Specified storage type example.
+``
+struct red;
+struct green;
+struct blue;
+
+typedef bitfield_tuple<
+ storage<unsinged int>,
+ member<unsigned int,red,4>,
+ member<unsigned int,green,4>,
+ member<unsigned int,blue,4>
+> rgb444;
``
+The type `rgb444` shown in the above example has the size of 4. `rgb444` has the
+same size as the integer type which the storage type specifies.
+
+non-specified storage type example.
``
+struct red;
+struct green;
+struct blue;
+
+typedef bitfield_tuple<
+ member<unsigned int,red,4>,
+ member<unsigned int,green,4>,
+ member<unsigned int,blue,4>
+> rgb444_2;
+``
+The in this example a storage type is being deduced by the `bitfield_tuple`. So
+the type `rgb444_2` has a size of 2 which is the size of an unsigned short which
+is the smallest type that could hold all of the bitfields.
+
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/building.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/building.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/building.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -4,6 +4,6 @@
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)
]
-[section Building With `bitfield_tuple`]
-TODO
+[section Building With bitfield_tuple]
+Coming Soon.
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/dependencies.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/dependencies.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/dependencies.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -21,17 +21,32 @@
[h5 Standard Library Includes]
* <cstddef> - Included for `std::size_t`.
- * Included by boost.integer.bitfield
+ * Included by Boost.Integer.Bitfield
* <cassert>
* <limits>
- * <netinet/in.h> <- Need to do implact analysis and remove this header
-from the includes before final draft.
-[h5 Boost Library Includes]
-* boost.Preprocessor
- * <boost/preprocessor/repetition/enum.hpp>
- * <boost/preprocessor/repetition/repeat_from_to.hpp>
+[h4 Boost Library Includes]
+[h5 boost.Preprocessor]
+* <boost/preprocessor/repetition/enum.hpp>
+* <boost/preprocessor/repetition/repeat_from_to.hpp>
+
+[h5 Boost.Config]
+* <boost/config.hpp>
+
+[h5 Boost.MPL]
+* <boost/mpl/vector.hpp>
+* <boost/mpl/not.hpp>
+* <boost/mpl/deref.hpp>
+* <boost/mpl/at.hpp>
+* <boost/mpl/less.hpp>
+* <boost/mpl/size.hpp>
+* <boost/mpl/int.hpp>
+* <boost/mpl/assert.hpp>
+* <boost/mpl/if.hpp>
+* <boost/mpl/minus.hpp>
+* <boost/mpl/size_t.hpp>
+* <boost/mpl/void.hpp>
[note The `mpl::vector` is a limiting factor of the `bitfield_tuple` for more
information on how to deal with limitations of the `bitfield_tuple` and its
@@ -39,117 +54,47 @@
and `bitfield_reference` regarding Preconditions.]
-* boost.MPL
- * <boost/mpl/vector.hpp>
- * <boost/mpl/not.hpp>
- * <boost/mpl/deref.hpp>
- * <boost/mpl/at.hpp>
- * <boost/mpl/less.hpp>
- * <boost/mpl/size.hpp>
- * <boost/mpl/int.hpp>
- * <boost/mpl/assert.hpp>
- * <boost/mpl/if.hpp>
- * <boost/mpl/minus.hpp>
- * <boost/mpl/size_t.hpp>
- * <boost/mpl/void.hpp>
-
-* boost.Type Traits
- * <boost/type_traits.hpp> <- Need to figure out which parts of type_traits
-are being used and make sure that I only include those.
- * <boost/type_traits/is_const.hpp>
-
-
-* boost.Static Assert
- * <boost/static_assert.hpp>
-
-
-* boost.Enable If
- * <boost/utility/enable_if.hpp>
-
-
-* boost.Fusion
- * <boost/fusion/sequence/intrinsic.hpp>
- * <boost/fusion/support/is_sequence.hpp>
- * <boost/fusion/support/is_view.hpp>
- * <boost/fusion/support/tag_of_fwd.hpp>
- * <boost/fusion/iterator/iterator_facade.hpp>
- * <boost/fusion/iterator/value_of.hpp>
- * <boost/fusion/iterator/deref.hpp>
- * <boost/fusion/iterator/next.hpp>
- * <boost/fusion/iterator/prior.hpp>
- * <boost/fusion/iterator/distance.hpp>
- * <boost/fusion/iterator/key_of.hpp>
- * <boost/fusion/iterator/value_of_data.hpp>
- * <boost/fusion/iterator/deref_data.hpp>
-
-
-[h4 Bitfield Tuple Specific Headers]
-
-* <boost/integer/details/bft/template_expansion_macros.hpp>
- * Includes macros for tempate parameter generation and defining macros
-which can be used for specilization over a bitfield_tuple type.
-* <boost/integer/details/bitfield_tuple_impl.hpp>
- * Base class for a `bitfield_tuple` that is responsible for enforcing
-some of the preconditions related to the `bitfield_tuples` template parameters.
-* <boost/integer/details/bft/bft_element.hpp>
- * Element used for storing information about the `bitfield_tuple`'s
-bitfields.
-* <boost/integer/details/bft/arg_parse_impl.hpp>
- * A structure and its specializations which are responsible for the paring
-of template parameters into `bitfield_element`s which are then stored in an
-mpl sequence.
-* <boost/integer/details/bft/deduce_storage.hpp>
- * Functionality for deducing the storage type for a bitfield tuple if one
-isn't supplied.
-* <boost/integer/details/bft/name_lookup.hpp>
- * predicate used with `mpl::find_if` for locating items within the mpl
-sequence with the name tag specified by the user.
-* <boost/integer/details/bft/reference_builder.hpp>
- * used to aid with the construction of the `bitfield_reference` template of
-a bitfield, from a `bitfield_tuple`.
-* <boost/integer/bitfield_tuple_fwd.hpp>
- * forward declaration of the `bitfield_tuple`.
-* <boost/integer/details/fusion_ext_includes.hpp>
- * Includes all of the headers necessary for creating the boost.fusion
-extension of the `bitfield_tuple`.
-* <boost/integer/details/bft/ext/bitfield_tuple_fusion_includes.hpp>
- * Include all header files from the related to the bitfield
-tuple which compose the fusion extension interface of a `bitfield_tuple`.
-* <boost/integer/details/bft/make_bitfield_tuple.hpp>
- * contains macros and functions used for creating the `make_bitfield_tuple`
-funciton template.
-
-
-[h5 Bitfield Tuple Fusion Extension]
-* header files which compose the boost.Fusion interface extension of a
-`bitfield_tuple`.
- * <boost/integer/bft/ext/tag_of.hpp>
- * <boost/integer/bft/ext/bitfield_iterator.hpp>
- * <boost/integer/bft/ext/fusion/is_sequence_impl.hpp>
- * <boost/integer/bft/ext/fusion/is_view_impl.hpp>
- * <boost/integer/bft/ext/fusion/category_of_impl.hpp>
- * <boost/integer/bft/ext/fusion/at_impl.hpp>
- * <boost/integer/bft/ext/fusion/begin_impl.hpp>
- * <boost/integer/bft/ext/fusion/size_impl.hpp>
- * <boost/integer/bft/ext/fusion/end_impl.hpp>
-
+[h5 Boost.Type Traits]
+* <boost/type_traits/add_reference.hpp>
+* <boost/type_traits/is_const.hpp>
+* <boost/type_traits/make_unsigned.hpp>
+* <boost/type_traits/is_same.hpp>
+* <boost/type_traits/is_pod.hpp>
+
+[h5 Boost.Static Assert]
+* <boost/static_assert.hpp>
+
+[h5 Boost.Enable If]
+* <boost/utility/enable_if.hpp>
+
+[h5 Boost.Fusion]
+* <boost/fusion/sequence/intrinsic.hpp>
+* <boost/fusion/support/is_sequence.hpp>
+* <boost/fusion/support/is_view.hpp>
+* <boost/fusion/support/tag_of_fwd.hpp>
+* <boost/fusion/iterator/iterator_facade.hpp>
+* <boost/fusion/iterator/value_of.hpp>
+* <boost/fusion/iterator/deref.hpp>
+* <boost/fusion/iterator/next.hpp>
+* <boost/fusion/iterator/prior.hpp>
+* <boost/fusion/iterator/distance.hpp>
+* <boost/fusion/iterator/key_of.hpp>
+* <boost/fusion/iterator/value_of_data.hpp>
+* <boost/fusion/iterator/deref_data.hpp>
[h5 Boost Vault Includes]
* <boost/bitfield/bitfield.hpp>
- * Does the storage and retrieval of data to and from the bitfield_tuples
-internal storage.
-
-
-[h5 Boost.integer Bit Mask Includes]
+[h5 Boost.Integer Bit Mask Extension Includes]
* <boost/integer/bits_mask.hpp>
* <boost/integer/bit_width.hpp>
-
-[/
-
-
-
+* <boost/integer/high_bits_mask.hpp>
+* <boost/integer/low_bits_mask.hpp>
+* <boost/integer/integral_mask.hpp>
+
+[h5 Bitfield Tuple Include Files ]
+Please see the Files section for a full list and description of all files
+which are part of the `bitfield_tuple` and its interface.
-]
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/intallation.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/intallation.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/intallation.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -5,7 +5,5 @@
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
]
[section Installation]
-There is no need to install or link against bitfield_tuple. It is a
-header only component. For additional dependencies of bitfield_tuple please
-see the Dependencies section of the documentation.
+Coming Soon.
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/testing.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/testing.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/getting_started/testing.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -4,10 +4,21 @@
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)
]
+
+
[section Testing]
-Currently only tested on GCC 4.4.
+List of compilers which the library has been tested on.
+
+* GCC
+ * GCC-4.4.3
+* MSVC
+ * MSVC 10.0
+ * MSVC 9.0
+* Cygwin
+ * GCC-3.4.4
+* MinGW with
+ * GCC 4.4.0
+ * GCC 4.5.0
-TODO:
-Test on more compilers and add the information here.
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/glossary.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/glossary.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/glossary.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -20,5 +20,10 @@
Wikipedia Data Struture Alignment] - Data Structure Alignment article from
Wikipedia. This relates directly to packing of data structures.
+* Endianness
+ * [@http://en.wikipedia.org/wiki/Endianness Wikipedia Endianness] - Wikipedia
+article on endianness.
+ * [@http://mysite.verizon.net/beman/endian-0.10/libs/integer/doc/endian.html
+Endians] - In boost standbox.
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/tutorial.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/tutorial.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bft_doc/users_guide/tutorial.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -80,7 +80,6 @@
#include <boost/integer/bitfield_tuple.hpp>
#include <iostream>
-using namespace boost;
using namespace boost::bitfields;
// names used to mimic the names in struct foo.
@@ -116,31 +115,44 @@
The different templates that can be used within a `bitfield_tuple`'s template
-decalaration.
+declaration.
[table
[
[Signature][Brief Description]
]
[
- [`filler<std::size_t>`][ Padding in bits that can be used to seperate bitfield.]
+ [`padding<std::size_t>`]
+ [ Padding in bits that can be used to separate bitfield.]
]
[
- [`bit_align<std::size_t>`][ Sets the offset of the first bit of the next
-bitfield supplied to a multiple of the integer supplied. ]
+ [`align<std::size_t>`]
+ [ Sets the offset of the first bit of the next bitfield supplied to a
+multiple of the integer supplied. ]
]
[
- [`flag<typename>`][ Makes a single bit width boolean `member` with a name
-supplied to as the parameter. ]
+ [`flag<typename>`]
+ [ Makes a single bit width boolean `member` with a name supplied to as
+the parameter. ]
]
[
- [`member<typename, typename, std::size_t>`][ Used for specifying a
-member where the first parameter is the type being stored, the second is the name
-and the third is the width in bits.]
+ [`member<typename, typename, std::size_t>`]
+[ Used for specifying a member where the first parameter is the type being
+stored, the second is the name and the third is the width in bits.]
]
[
- [`storage<typename>`][ The type specified in this parameter is used as
-the storage. This parameter is optional and it doesn't matter where in the template
-you put it.]
+ [`storage<typename>`]
+ [ The type specified in this parameter is used as the storage. This
+parameter is optional and it doesn't matter where in the template you put it.]
+ ]
+ [
+ [`pointer<typename,typename,typename>`]
+ [ This allows for a pointer to have bits stuffed into it and have both
+extracted separately but stored together.]
+ ]
+ [
+ [`custom<typename,typename,typename,typename>`]
+ [ This type allows for custom packing and unpacking of the the data
+before it is stored within the bitfield_tuple. ]
]
]
[tip Read the documentation under the class reference section for additional
@@ -149,14 +161,146 @@
[h5 Part 4: Fusion Sequence extension]
The `bitfield_tuple` is a boost.fusion sequence. It supports the all of the
-functionality that is supported by a random access container and an associtve
+functionality that is supported by a random access container and an associative
sequence. The `bitfield_tuple` internally stores its fields as an associative
array. This allows the `bitfield_tuple` to provide both index based as well as
-named `get` functions. For full documentataion of how to use boost.fusion see
-the boost.fusion documentation. For the boost.fusion features supported by
+named `get` functions. For full documentation of how to use boost.fusion see
+the boost.fusion documentation. For the Boost.Fusion features supported by
the `bitfield_tuple` see the fusion extension documentation located in the
reference section of the documentation.
+``
+#include <boost/integer/bitfield_tuple.hpp>
+#include <iostream>
+#include <boost/fusion/include/for_each.hpp>
+
+using namespace boost::bitfields;
+
+struct red;
+struct green;
+struct pink;
+struct blue;
+struct salmon;
+
+typedef bitfield_tuple<
+ member<char,red,4>,
+ member<unsigned char, green,5>,
+ member<int, salmon, 16>,
+ storage<std::size_t>
+> fusion_example_tuple;
+
+struct unary_function_object{
+ template <typename T>
+ void operator() (T x) {
+ std::cout << x << std::endl;
+ }
+};
+
+int main() {
+
+ fusion_example_tuple bft;
+ bft.get<0>() = 1;
+ bft.get<1>() = 2;
+ bft.get<2>() = 3;
+
+ boost::fusion::for_each(bft,unary_function_object());
+ return 0;
+}
+``
+The above code uses the fusion for_each to iterate over each element within
+the bitfield_tuple and print it. For a full description of all of the
+Boost.Fusion supported operations please see the section of the documentation
+relating to the Boost.Fusion sequence extension.
+
+
+[h5 Part 5: Pointer stuffing]
+`bitfield_tuple` provides a mechanism for for stuffing bits into pointers (as
+well as other things). For a more in depth description of the `pointer` member
+of `bitfield_tuple` please refer to the documentation for `pointer`. The
+following is a basic example for pointers which point to DWORD aligned sections
+of memory.
+
+``
+#include <boost/integer/bitfield_tuple.hpp>
+#include <boost/assert.hpp>
+struct color;
+struct ptr;
+
+typedef bitfield_tuple<
+ pointer<int, ptr>,
+ member<unsigned int,color,2>
+> color_stuffed_ptr_tuple;
+
+using namespace boost::bitfields;
+
+int main() {
+ int* some_ptr = new int();
+ color_stuffed_ptr_tuple colored_ptr;
+ colored_ptr.get<ptr>() = some_ptr;
+ colored_ptr.get<color>() = 3;
+
+ // set the value of the thing being pointed at to 3.
+ *colored_ptr.get<ptr>() = 3;
+
+ // make sure that the color is correctly set.
+ BOOST_ASSERT(( colored_ptr.get<color>() == 3 ));
+
+ return 0;
+}
+
+``
+There is much more one can do with a stuffed pointer but this is the minimal
+example of how to use the `pointer` member.
+
+[h5 Part 5: Custom Integral Stuffing]
+The `custom` member allows the user to specify a section of bits within a type
+and extract those bits and then store them inside of the `bitfield_tuple`. One
+of the use cases for something like this is if a number is always even then the
+last bit is always zero. The following example is how to specify the `custom`
+member such that it is used to store an always even number.
+
+``
+#include <boost/integer/bitfield_tuple.hpp>
+
+using namespace boost::bitfields;
+struct always_even_int;
+struct extra_bool;
+typedef bitfield_tuple<
+ custom<
+ unsigned int,
+ always_even_int,
+ boost::high_bits_mask<
+ unsigned int,
+ (boost::bit_width<unsigned int>::value - 1)
+ >
+ >,
+ flag<extra_bool>
+> custom_stuffing;
+
+int main() {
+ custom_stuffing cs;
+ cs.get<always_even_int>() = 4;
+
+ BOOST_ASSERT(( cs.get<always_even_int>() == 4));
+ cs.get<extra_bool>() = true;
+
+ BOOST_ASSERT(( sizeof(custom_stuffing) == sizeof(unsigned int) ));
+}
+``
+The `high_bits_mask` in the above example, is what is used to specify the value
+bits within the value type. The mask is used to extract the value bits out of
+the `unsigned int` when the `get<alway_even_int()`'s value type assignment
+operator is called. When the `operator value_type()` the function returns the
+value bits so that they match the mask that was used to take them. For instance,
+if the order of the template parameters was switched so that the
+`flag<extra_bool>` was to be first and the `custom` member second the data
+structure would look exactly the same, but there would be a slight difference in
+performance because of the shifts which would have to occur in order to
+correctly unpack or pack the type before it is returned or stored.
+
+There is much more that can be done with the `custom` member type then what is
+shown for additional information on how to fully utilize all features of this
+type please see the documentation relating the `custom` member.
[endsect]
Modified: sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_masks.qbk
==============================================================================
--- sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_masks.qbk (original)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_masks.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -18,5 +18,6 @@
[include:high_bits_mask high_bits.qbk]
[include:low_bits_mask low_bits.qbk]
[include:bits_mask bits_mask.qbk]
+[include:bit_width bit_width.qbk]
[endsect]
Added: sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_width.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2010/bit_masks/lib/integer/doc/bit_width.qbk 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -0,0 +1,67 @@
+[/
+Copyright (c) 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)
+]
+
+[c++]
+[section:bit_width bit_width]
+[h3 Description]
+`bit_width` is a basic type trait style meta-function which takes a type,
+and gives you the width of that type in bits.
+
+
+[h3 Header File Information]
+``
+#include <boost/integer/bit_width.hpp>
+``
+
+
+[h3 Template Signature]
+`bit_width` has the following template signature:
+``
+namespace boost {
+template <typename T> struct bit_width;
+}
+``
+
+[h3 Template Parameters]
+
+[table
+ [[Parameter][Description]]
+ [[`T`][ A type which you would like the width of. ]]
+]
+
+[h3 Interface]
+[table
+ [[Operation][Description]]
+ [[`N::value`][ Returns a value of type `std::size_t` which is the number of bits
+within `T`. ]]
+]
+
+
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ ]
+ [ You must be able to call `sizeof` on type `T` ]
+ [ This is enforced by attempting to take the `sizeof` `T` and the
+compiler telling you you can not. ]
+ ]
+]
+
+[h3 Examples]
+
+Example:
+``
+assert( bit_width<int>::value == 32);
+``
+
+[endsect]
+
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-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -29,27 +29,64 @@
// 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 Header File Information]
+``
+#include <boost/integer/bits_mask.hpp>
+``
[h3 Template Signature]
`bits_mask` has the following template signature:
``
-template <typename T, unsigned int Offset, unsigned int Width = 1 >
-struct bits_mask;
+namespace boost {
+template <typename T, unsigned int Offset, unsigned int Width = 1u > struct bits_mask;
+}
``
+[h3 Bit Mask Hierarchy]
+`bits_mask` inherits from `integral_mask`.
+
+
+[h3 Template Parameters]
[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. ]]
+ [[`Offset`][ This is the number of bits from the least significant bit to the first bit being used to compose the mask.
+Another way to think of this is the amount that the mask has been shifted to the left (using the left shift operator). ]]
+ [[`Width`][ This is the width of the mask in bits. `Width` has a default
+value of `1u` so that `bits_mask` can be easily used to create boolean flags
+by providing only an `Offset` to the bit.]]
]
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [ ]
+ [ `T` must be an integral type. ]
+ [ This is only a documented precondition. It is not enforced. ]
+ ]
+ [
+ [ `(Offset + Width) <= ( bit_width<T>::value )`]
+ [ The `Width + Offset` must be less then or equal to the number of bits
+within the integral type `T` ]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ Valid range for mask width is > 0.]
+ [ The `Width` of a mask must not be zero. Because `Width` is of
+`std::size_t` it can not be negative.]
+ [ Enforced by domain of template parameter and by static assert. ]
+ ]
+]
+
+
[h3 Interface]
-`TYPENAME` Compile time interface. Assume that N is of type
-`N TYPE` the type supplied here is only for example.
+`bits_mask` Compile time interface. Assume that `N` is of type
+`bits_mask<unsigned int,4,1>` the type supplied here is only for example.
[table
[[Operation][Description]]
@@ -59,37 +96,9 @@
[[`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`
-this function will be made fasters and more effieient.]]
+return the value associated with the type.]]
]
-[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 `bits_mask` template.
@@ -145,7 +154,7 @@
``
-The implicit cast operator allows for simplicity, clairity of code. In the
+The implicit cast operator allows for simplicity, clarity 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-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -1,10 +1,10 @@
-
[/
Copyright (c) 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)
]
+
[c++]
[section:high_bits_maskbits high_bits_mask]
[h3 Description]
@@ -13,6 +13,7 @@
significant bit. The `high_bits_mask` changes base on the width of the type but
always maintains the same high level description of the bits. For example,
``
+
// using high bits to create a mask starting from the left most bit with a width
// of 15
typedef high_bits_mask<int, 15> bits;
@@ -21,18 +22,24 @@
``
[h3 Header File Information]
-Header file: <boost/integer/high_bits_mask.hpp>
-Header file: <boost/integer/high_low_mask.hpp>
+``
+#include <boost/integer/high_bits_mask.hpp>
+#include <boost/integer/high_low_mask.hpp>
+``
+
[h3 Template Signature]
`high_bits_mask` has the following template signature:
``
namespace boost {
-template <typename T, unsigned int Width>
-struct high_bits_mask;
+template <typename T, unsigned int Width> struct high_bits_mask;
}
``
+
+
[h3 Bit Mask Hierarchy]
+`high_bits_mask` inherits from `integral_mask`.
+
[h3 Template Parameters]
@@ -51,7 +58,7 @@
[[`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::offset`][ Always set to zero for this type. The offset is something which
+ [[`N::offset`][ Always set to zero for this type. The offset is something which
all of the mask type support and refers the amount the mask has been shifted to
the right or the left (Depending on the type of mask used). In the case of
`integral_mask`, no left or right shift has occurred so `N::offset` is always set
@@ -61,6 +68,25 @@
]
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [`bit_width<T>::value >= Width`]
+ [ The `Width` must not be greater then the size in bits of type `T`.]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ ]
+ [ `T` must be an integral type. ]
+ [ This is only a documented precondition. It is not enforced. ]
+ ]
+]
+
[h3 Examples]
Examples and use cases related to the `high_bits_mask` template.
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-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -14,8 +14,9 @@
[h3 Header File Information]
-Header file: <boost/integer/integral_mask.hpp>
-
+``
+#include <boost/integer/integral_mask.hpp>
+``
[h3 Template Signature]
`integral_mask` has the following template signature:
@@ -45,12 +46,12 @@
]
[
[ ]
- [ T must be an integral type. ]
+ [ `T` must be an integral type. ]
[ This is only a documented precondition. It is not enforced. ]
]
[
[ ]
- [ Value must be in the domain of the integral type T. ]
+ [ `Value` must be in the domain of the integral type `T`. ]
[ This is only a documented precondition. It is not enforced. ]
]
]
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-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -4,29 +4,38 @@
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)
]
+
[c++]
[section:low_bits_mask low_bits_mask]
[h3 Description]
-`low_bits_mask` creates a mask of bits starting from the right most bit and
-extending out to the left. The `low_bits_mask` is similar to the `high_bits_mask`
-just starts on the right most bit instead of the left most bit. The way
-`low_bits_mask` behaves in the following example:
+`low_bits_mask` is a section of contiguous of bits which extend out from the
+least significant bit toward the most significant bit. The following is a basic
+example of how `low_bits_mask` works:
``
typedef low_bits_mask<int, 10> mask;
// mask::value has the following binary value
// 0000 0000 0000 0000 0000 0011 1111 1111
``
-The `low_bits_mask` template is located in the <boost/integer/low_bits_mask.hpp>
-header file.
+
+[h3 Header File Information]
+``
+#include <boost/integer/low_bits_mask.hpp>
+#include <boost/integer/high_low_mask.hpp>
+``
[h3 Template Signature]
`low_bits_mask` has the following template signature:
``
-template <typename T, unsigned int Width>
-struct low_bits_mask;
+namespace boost {
+template <typename T, unsigned int Width> struct low_bits_mask;
+}
``
+[h3 Bit Mask Hierarchy]
+`low_bits_mask` inherits from `integral_mask`.
+
+[h3 Template Parameters]
[table
[[Parameter][Description]]
[[`T`][ Is an integral type which the mask is to be created over. ]]
@@ -43,12 +52,32 @@
[[`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 0 for this mask because the `low_bits_mask` is not
+shifted in any direction and always starts at the least significant bit. ]]
[[`operator T()`][ Run time support function. All this function does is
-return the value associated with the type. With the c++0x feature `constexper`
-this function will be made fasters and more effieient.]]
+return the value associated with the type.]]
]
+[h3 Preconditions]
+[table
+ [
+ [Precondition]
+ [Description]
+ [Enforcement]
+ ]
+ [
+ [`bit_width<T>::value >= Width`]
+ [ The `Width` must not be greater then the size in bits of type `T`.]
+ [ Enforced by static assert. ]
+ ]
+ [
+ [ ]
+ [ `T` must be an integral type. ]
+ [ This is only a documented precondition. It is not enforced. ]
+ ]
+]
+
[h3 Examples]
Examples and use cases related to the `low_bits_mask` template.
Modified: sandbox/SOC/2010/bit_masks/notes.txt
==============================================================================
--- sandbox/SOC/2010/bit_masks/notes.txt (original)
+++ sandbox/SOC/2010/bit_masks/notes.txt 2010-08-21 16:08:09 EDT (Sat, 21 Aug 2010)
@@ -5,9 +5,8 @@
---------------------------------------------------------------------------------
- Links to add for ease of documentation navigation
---------------------------------------------------------------------------------
+
+
--------------------------------------------------------------------------------
Project Documentation Status
@@ -40,201 +39,84 @@
B) integral_mask_type
- Links to add:
- 1) Create link for Boost.Type Traits
- 2) Create a link to the header file
-
- * Make sure that integral_mask and all uses of N are enclosed in
- ` `.
+ Links to add:
+ 1) Create link for Boost.Type Traits
+ 2) Create a link to the header file
C) high_bits_mask
- * Rewrite Description paragraph.
- * Give multiple examples at the top of the page showing the
- bits for more types then just int (short and char).
- * Add documentation for offset for interface.
- * Re word documentation for value change to say something along
- the lines of value of the mask instead of value associated with
- N.
- * Add documentation for the header file in which high bits mask
- is located. Make sure to document both header files that can be
- used to include high_bits_mask.
- * The section for the header file needs its own header.
- * Make sure that high_bits_mask and all uses of N are enclosed in
- ` `.
- * Note the position in the hierarchy in relation to integral_mask.
- * Should I be using high bit and low bit instead of using left and
- right?
- * Make sure the link for this section is enclosed inside of ` `.
- * Make note of the namespace in which this exists.
- * Add hex counter-example?
- * Document PRECONDITIONS for using the template.
-
- D) low_bits_mask
- * Rewrite the Description for this class so that it doesn't
- reference high_bits_mask as an example.
- * Make sure the link for this section is enclosed inside of ` `.
- * Make sure low_bits_mask and all uses of N are enclosed inside of
- ` `.
- * Create section for the header files.
- * Note the position in the hierarchy in relation to integral_mask.
- * Add both header files which can be used to include this class.
- * Make note of the namespace in which this exists.
- * Add documentation for offset as part of the interface.
- * Add hex counter-example?
- * Document PRECONDITIONS for using the template.
+ Links to add:
+ 1) Create a link to the header file
+
+ D) low_bits_mask
+ Links to add:
+ 1) Create a link to the header file
+
E) bits_mask
- * Make sure the link for this section is enclosed inside of ` `.
- * Make sure that bits_mask and all uses of N are enclosed within
- ` `.
- * Add a section for header files.
- * Add the header file which this exist's within to that section.
- * Move comments from inside of the code section into the
- description (unless its binary representation of a mask.
- * Add hex counter-example?
- * Note the position in the hierarchy in relation to integral_mask.
- * Note the namespace in which this exists.
- * Remove TYPENAME from the example section and replace it with
- `bits_mask`.
- * Note the default parameter for Width inside of the parameter
- documentation.
-
- D) bit_width <- NEW
- * Create section for the bit_width meta-function.
- * Note this as a meta-function and NOT a mask.
- * Explain where this is used and what it does.
- * Note header file.
- * Note parameters and interface.
- * Give example of basic usage.
- * Give equivalent code for what this is actually doing( 8*sizeof(T) ).
- * - Maybe Rationale?!?!
+ Links to add:
+ 1) Create a link to the header file
+
+ D) bit_width
+ Links to add:
+ 1) Create a link to the header file
+**** TODO STILL ****
E) MPL integration example <- NEW
* Show how the different bit mask's can be used for creating more
complex masks by using the MPL bitwise operations.
* This may be better suited to a different section.
+**** TODO STILL ****
+
3) bitfield_tuple
A) Overview
- * Add very simple summary to this page saying what a bitfield_tuple
- actually is.
-
I) Description
- * Remove the part about endianness (at end of description).
- * Add additional use cases for doing strange things with pointers.
- * Add example for doing something with a custom member.
- * Add the traditional example of how item's are stored within
- and integer.
- * Explain how the
-
+ Links to add:
+ 1) Create a link to the example section in last paragraph.
II) rationale
- * Add documentation about the space saving measures for pointers.
- * Add reference to the red-black tree color storage.
- * Add something about storing boolean values within a number that
- is always even.
+ Links to add:
+ 1) Add links to the red-black tree, Boost.fusion and clang
+ these are to be used as reference material where these things
+ are actually being used.
B) Users Guide
I) Getting Started
a) Installation
- * Remove the current documentation and add "coming soon".
-
b) Dependencies
- * Need to do implact analysis and remove this header from the
- includes before final draft.
- * Remove the netinet from the dependencies documentation.
- * double check all of the items used from type traits and
- update the list of includes with the correct files from
- type traits.
- * Change boost to Boost and capitalize all of the library
- names.
- * update the "Bitfield Tuple Specific Headers" section
- by adding of the header files and their respective location.
-
+ Links to add:
+ 1) Create a link to the Files section in last paragraph.
c) Building With bitfield_tuple
- * Add "Coming Soon".
-
d) Testing
- * add the compilers which Vicente and my self tested on.
II) Tutorial
- * Need to come up with some basic example for each of the
- different parts of the interface, then make a tutorial for each.
+ Links to add:
+ 1) Create a link for all of the different members that make up
+ the interface. (theres a table with a list of them inside
+ of it, that is where the links need to go).
+ 2) Create a link for pointer in the "part 5"s intro paragraph.
+
III) External Resources
- * Add relevant links here.
+ * Add relevant links here. Need to think about more relevant links
+ and add them!!!!
IV) Glossary
- * Add the wikipedia article about endianness.
- * Add a link to Beman's endians in vault/sandbox maybe both?
* Add a link to Vicente's Bitfield within boost vault / sandbox.
C) Reference
I) Concepts
II) bitfield_tuple Class Reference
a) bitfield_tuple and bitfield_reference
- * Note the namespace that bitfield_tuple resides within.
- * CHANGE: Enforced macro macro error message.
- ->
- Enforced by macro error message.
- * Template Members in first sentence there is a comma where
- a period should be.
- * Update preconditions for both custom and pointer members.
-
b) struct padding
- * Add header file to the documentation.
- * Note that this class needs to be noted as being included
- with the bitfield_tuple header.
- * Make Bits lower case.
- * Add an example.
- * Add template parameter documentation.
-
c) struct member
- * Add a Real description to this section.
- * Add header file to the documentation.
- * Note that this class needs to be noted as being included
- with the bitfield_tuple header.
- * Add an example.
-
d) struct flag
- * Move the example lower on the page under the example
- section.
- * Create real Description for the this.
- * Add documentation for the template parameter.
-
e) struct align
- * Give example referencing binary.
- * Add an example.
- * Add documentation for the template parameter.
-
f) struct storage
- * Add documentation for the template parameter.
- * Add 2 examples here and then show that their sizes are the
- same using both deduced and non-deduced types.
-
g) struct pointer
- * Add documentation for the template parameter.
-
- * Add 3 examples of how to specify the mask.
- * Add 2 examples of how to use a pointer member.
- * Make sure pointer is enclosed within ` ` when referencing
- the template.
-
h) struct custom
- * Add documentation for the template parameter.
- * Add an example of how to use custom with and 1 without
- providing your own policy.
- * Document template parameters.
- * Document what a policy looks like and what a policy does/how
- it interacts with the reference type.
- * This also needs a description.
-
III) bitfield_tuple Macro Reference
- a) Parameter Adjustment macros
- b) Code Generation Macros
-
IV) Function Reference
- a) Function make_bitfield_tuple
b) get as a free function <- NEW
V) Meta-Function Reference
@@ -305,7 +187,9 @@
--------------------------------------------------------------------------------
Tests to add
--------------------------------------------------------------------------------
-1) Compile failure test for mask_size meta function.
+1) Compile failure test for mask_size meta function.
+2) Compile failure test for both pointer, custom and flag to test for not using
+the same name more then once.
--------------------------------------------------------------------------------
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