132a133,142
> // The following implements the BitUnion system of defining bitfields
> //on top of an underlying class. This is done through the extensive use of
> //both named and unnamed unions which all contain the same actual storage.
> //Since they're unioned with each other, all of these storage locations
> //overlap. This allows all of the bitfields to manipulate the same data
> //without having to know about each other. More details are provided with the
> //individual components.
>
> //This namespace is for classes which implement the backend of the BitUnion
> //stuff. Don't use any of this directly! Use the macros at the end instead.
134a145,147
> //A base class for all bitfields. It instantiates the actual storage,
> //and provides getBits and setBits functions for manipulating it. The
> //Data template parameter is type of the underlying storage.
140a154,157
> //This function returns a range of bits from the underlying storage.
> //It relies on the "bits" function above. It's the user's
> //responsibility to make sure that there is a properly overloaded
> //version of this function for whatever type they want to overlay.
146a164
> //Similar to the above, but for settings bits with replaceBits.
153a172,174
> //A class which specializes a given base so that it can only be read
> //from. This is accomplished by only passing through the conversion
> //operator.
163a185
> //Similar to the above, but only allows writing.
174a197,198
> //This class implements ordinary bitfields, that is a span of bits
> //who's msb is "first", and who's lsb is "last".
191a216,221
> //When a BitUnion is set up, an underlying class is created which holds
> //the actual union. This class then inherits from it, and provids the
> //implementations for various operators. Setting things up this way
> //prevents having to redefine these functions in every different BitUnion
> //type. More operators could be implemented in the future, as the need
> //arises.
220a251,265
> //This macro is a backend for other macros that specialize it slightly.
> //First, it creates/extends a namespace "BitfieldUnderlyingClasses" and
> //sticks the class which has the actual union in it, which
> //BitfieldOperators above inherits from. Putting these classes in a special
> //namespace ensures that there will be no collisions with other names as long
> //as the BitUnion names themselves are all distinct and nothing else uses
> //the BitfieldUnderlyingClasses namespace, which is unlikely. The class itself
> //creates a typedef of the "type" parameter called __DataType. This allows
> //the type to propagate outside of the macro itself in a controlled way.
> //Finally, the base storage is defined which BitfieldOperators will refer to
> //in the operators it defines. This macro is intended to be followed by
> //bitfield definitions which will end up inside it's union. As explained
> //above, these is overlayed the __data member in its entirety by each of the
> //bitfields which are defined in the union, creating shared storage with no
> //overhead.
231a277,280
> //This closes off the class and union started by the above macro. It is
> //followed by a typedef which makes "name" refer to a BitfieldOperator
> //class inheriting from the class and union just defined, which completes
> //building up the type for the user.
238a288,294
> //This sets up a bitfield which has other bitfields nested inside of it. The
> //__data member functions like the "underlying storage" of the top level
> //BitUnion. Like everything else, it overlays with the top level storage, so
> //making it a regular bitfield type makes the entire thing function as a
> //regular bitfield when referred to by itself. The operators are defined in
> //the macro itself instead of a class for technical reasons. If someone
> //determines a way to move them to one, please do so.
247a304,305
> //This closes off the union created above and gives it a name. Unlike the top
> //level BitUnion, we're interested in creating an object instead of a type.
250c308,310
< //This is so we can send in parameters with commas
---
> //The preprocessor will treat everything inside of parenthesis as a single
> //argument even if it has commas in it. This is used to pass in templated
> //classes which typically have commas to seperate their parameters.
253a314,317
> //This wraps another bitfield class inside a _BitfieldRO class using
> //inheritance. As explained above, the _BitfieldRO class only passes through
> //the conversion operator, so the underlying bitfield can then only be read
> //from.
259a324,325
> //Similar to above, but for making write only versions of bitfields with
> //_BitfieldWO.
265a332,333
> //This uses all of the above to define macros for read/write, read only, and
> //write only versions of regular bitfields.
276a345
> //Use this to define an arbitrary type overlayed with bitfields.
278a348
> //Use this to define conveniently sized values overlayed with bitfields.
> // The following implements the BitUnion system of defining bitfields
> //on top of an underlying class. This is done through the extensive use of
> //both named and unnamed unions which all contain the same actual storage.
> //Since they're unioned with each other, all of these storage locations
> //overlap. This allows all of the bitfields to manipulate the same data
> //without having to know about each other. More details are provided with the
> //individual components.
>
> //This namespace is for classes which implement the backend of the BitUnion
> //stuff. Don't use any of this directly! Use the macros at the end instead.
134a145,147
> //A base class for all bitfields. It instantiates the actual storage,
> //and provides getBits and setBits functions for manipulating it. The
> //Data template parameter is type of the underlying storage.
140a154,157
> //This function returns a range of bits from the underlying storage.
> //It relies on the "bits" function above. It's the user's
> //responsibility to make sure that there is a properly overloaded
> //version of this function for whatever type they want to overlay.
146a164
> //Similar to the above, but for settings bits with replaceBits.
153a172,174
> //A class which specializes a given base so that it can only be read
> //from. This is accomplished by only passing through the conversion
> //operator.
163a185
> //Similar to the above, but only allows writing.
174a197,198
> //This class implements ordinary bitfields, that is a span of bits
> //who's msb is "first", and who's lsb is "last".
191a216,221
> //When a BitUnion is set up, an underlying class is created which holds
> //the actual union. This class then inherits from it, and provids the
> //implementations for various operators. Setting things up this way
> //prevents having to redefine these functions in every different BitUnion
> //type. More operators could be implemented in the future, as the need
> //arises.
220a251,265
> //This macro is a backend for other macros that specialize it slightly.
> //First, it creates/extends a namespace "BitfieldUnderlyingClasses" and
> //sticks the class which has the actual union in it, which
> //BitfieldOperators above inherits from. Putting these classes in a special
> //namespace ensures that there will be no collisions with other names as long
> //as the BitUnion names themselves are all distinct and nothing else uses
> //the BitfieldUnderlyingClasses namespace, which is unlikely. The class itself
> //creates a typedef of the "type" parameter called __DataType. This allows
> //the type to propagate outside of the macro itself in a controlled way.
> //Finally, the base storage is defined which BitfieldOperators will refer to
> //in the operators it defines. This macro is intended to be followed by
> //bitfield definitions which will end up inside it's union. As explained
> //above, these is overlayed the __data member in its entirety by each of the
> //bitfields which are defined in the union, creating shared storage with no
> //overhead.
231a277,280
> //This closes off the class and union started by the above macro. It is
> //followed by a typedef which makes "name" refer to a BitfieldOperator
> //class inheriting from the class and union just defined, which completes
> //building up the type for the user.
238a288,294
> //This sets up a bitfield which has other bitfields nested inside of it. The
> //__data member functions like the "underlying storage" of the top level
> //BitUnion. Like everything else, it overlays with the top level storage, so
> //making it a regular bitfield type makes the entire thing function as a
> //regular bitfield when referred to by itself. The operators are defined in
> //the macro itself instead of a class for technical reasons. If someone
> //determines a way to move them to one, please do so.
247a304,305
> //This closes off the union created above and gives it a name. Unlike the top
> //level BitUnion, we're interested in creating an object instead of a type.
250c308,310
< //This is so we can send in parameters with commas
---
> //The preprocessor will treat everything inside of parenthesis as a single
> //argument even if it has commas in it. This is used to pass in templated
> //classes which typically have commas to seperate their parameters.
253a314,317
> //This wraps another bitfield class inside a _BitfieldRO class using
> //inheritance. As explained above, the _BitfieldRO class only passes through
> //the conversion operator, so the underlying bitfield can then only be read
> //from.
259a324,325
> //Similar to above, but for making write only versions of bitfields with
> //_BitfieldWO.
265a332,333
> //This uses all of the above to define macros for read/write, read only, and
> //write only versions of regular bitfields.
276a345
> //Use this to define an arbitrary type overlayed with bitfields.
278a348
> //Use this to define conveniently sized values overlayed with bitfields.