T_Boxer< TBoxable, TEnableIf > Struct Template Reference

Description:

template<typename TBoxable, typename TEnableIf = void>
struct alib::boxing::T_Boxer< TBoxable, TEnableIf >

---

This template struct is used to define customized behavior for boxing C++ type TBoxable .

Default Boxing:

If this struct is not specialized for template type TBoxable , default boxing applies. With that, values and pointers of a type are boxed in the same way:

• They are both boxed to a pointer of TBoxable if a value of the type does not "fit" into a box's Placeholder or if the type is not copy-constructible or not trivially destructible.
• Otherwise, both are boxed as values, hence if a pointer is given to the constructor or assign operator= of class Box , indirection operator* is applied.

Custom Boxing With Specializations Of This Struct:

The default boxing briefly described above, can be manipulated by providing a specialization of this struct. All three entities of this default implementation have to be provided with such specializations:

1. Type definition Mapping:
   The mapped type must be given using helper struct TMappedTo or TMappedToArrayOf . The mapped type needs to be given as an explicit template parameter of those. In the case of TMappedTo, the template parameter denotes the mapped type, while with TMappedToArrayOf, the template parameter denotes the type of the elements of the boxed C++ array.

   If special type detail::TNotBoxable is given (still wrapped in the helper, hence given as TMappedTo<TNotBoxable>), then boxing is disallowed for type TBoxed . In this case, only declarations of functions Write and Read need to be provided, as they are never invoked.

   The default implementation of this struct uses a second special type available, detail::TDefaultBoxing which denotes default boxing.

2. Static Method Write:
   This method is invoked for converting source values to mapped types. Often the default implementation given in the un-specialized version this struct is applicable. In this case it can simply be copied to the specialization.

   Custom implementations may use TMP-enabled overloads of method Placeholder::Write or alternatively write to the union members of the placeholder directly.

3. Static Method Read:
   This method is invoked for converting the placeholder data back to the boxed source type. Often the default implementation given in the un-specialized version of this struct is well suited. In this case it can simply be copied to the specialization.
   Custom implementations may use TMP-enabled overloads of method Placeholder::Read or alternatively read the union members of the placeholder directly.

   A type becomes not unboxable in the moment this function returns a different type than TBoxable .
   This may well be intended and thus the specialized version of this struct may declare this method to return void. In this case a declaration of the method is sufficient, as it will never be invoked.
   With TMP-enabled specializations of this struct (see Programmer's Manual chapter 7.7 Tutorial: Conditional Customization), the return type might be conditionally set. Such TMP-defined return type then decides about which of the TMP-enabled types are unboxable and which are not.

Note

If a specialization uses default type mapping by providing

using   Mapping=      TMappedTo<TDefaultBoxing>;

in theory, a mixture of default and custom boxing is in place! Note, that the authors of this library and documentation have not seen a use case for this, yet.

Helper Macros:

A set of macros for defining specializations exist. The use of the macro is recommended, as besides being less error prone, their use make the code more readable. Finally, chances are good that code that uses the macros remains compatible with future versions of module ALib Boxing .

All macros expect this struct's template type TBoxable as the first parameter, and most expect the mapped type as the second parameter. The latter must not be wrapped in templated helpers TMappedTo respectively TMappedToArrayOf, as the macros internally do that.

For more information, see the reference documentation of the macros, which are:

• ALIB_BOXING_CUSTOMIZE
• ALIB_BOXING_CUSTOMIZE_TYPE_MAPPING
• ALIB_BOXING_CUSTOMIZE_NOT_UNBOXABLE
• ALIB_BOXING_CUSTOMIZE_ARRAY_TYPE
• ALIB_BOXING_CUSTOMIZE_ARRAY_TYPE_NON_UNBOXABLE
• ALIB_BOXING_CUSTOMIZE_DENY_BOXING

Value Boxing and Nulled Pointers:

If a type is boxed as value (either with default boxing or custom boxing) and a nulled pointer to that type is boxed, method Placeholder::Clear is invoked instead of this struct's method Write.

Avoiding Seldom Compilation Errors:

For technical reasons, namely to avoid TMP compilation problems, some conditional specialization is internally made, that declare method Read void. This is sometimes needed, if a type is not returnable, even if that becomes never be boxed or unboxed. Such situation might happen with TMP, for example if class Box is part of a union.
The specialization is made for the following types of TBoxable :

• C++ array types
  Those types are fetched by an overloaded constructor that does not (because it can not) leverage this struct. Likewise, they can not be unboxed in the usual fashion.
• Function types (selected by std::is_function<TBoxable>::value).

If a dubious error message about method Read not being able to return a certain type occurs, even one that a user's code maybe even does "actively" try to box or unbox, then it might be helpful to specialize this struct for such type, without providing implementations of Write and Read and with the latter to return void.

See also

More explanation and sample code is given in chapter 7. Customizing Boxing of the Programmer's Manual of module ALib Boxing .

Template Parameters

TBoxable	The source type to customize boxing for.
TEnableIf	Optional TMP parameter to allow conditional specializations.

Definition at line 241 of file typetraits.inl.

Public Type Index:
using	Mapping = TMappedTo<detail::TDefaultBoxing>

Public Static Method Index:
static	Read (const Placeholder &src)
static void	Write (Placeholder &target, const TBoxable &value)

Type Definition Details:

Mapping

template<typename TBoxable , typename TEnableIf = void>

using Mapping = TMappedTo<detail::TDefaultBoxing>

Defines the mapped type. With specializations, that type has to be wrapped in either TMappedTo or TMappedToArrayOf . Special designator types detail::TDefaultBoxing and detail::TNotBoxable may be wrapped, to denote corresponding behavior.

The default implementation specifies designator type TDefaultBoxing, which disables custom boxing.

Definition at line 252 of file typetraits.inl.

Method Details:

Read()

template<typename TBoxable , typename TEnableIf = void>

static Read ( const Placeholder & src )

inlinestatic

Used for unboxing a value, precisely reading the contents of field Box::data , which is given with parameter src and creating a value of type TBoxable from that.
The default implementation of this struct implements this method as follows:

return src.Read<TBoxable>();

This implementation leverages the TMP-enabled overloads Placeholder::Read and is often all that is needed with custom specializations.

If a different type than TBoxable is returned, then that source type is not unboxable. To intend such behavior, for example because TBoxable is mapped to a reduced type and therefore unboxing is not possible, specializations may declare return type void and omit a definition of this method.
With TMP enabled customizations, also other return types may given, which likewise denote an unboxable source type. A sample of that is given with Programmer's Manual chapter 7.7 Tutorial: Conditional Customization.

Parameters

src	The Placeholder to unbox the data from

Returns

The unboxed object.

Definition at line 302 of file typetraits.inl.

Write()

template<typename TBoxable , typename TEnableIf = void>

static void Write ( Placeholder & target, const TBoxable & value )

inlinestatic

Used for boxing a value, precisely writing the boxable portion of a type into field Box::data , which is given with parameter target .
The default implementation of this struct implements this method as follows:

    static void  Write( Placeholder& target,  const TBoxable& value )
    {
        target.Write( value );
    }

This implementation leverages the TMP-enabled overloads Placeholder::Write and is often all that is needed with custom specializations.

See also

A possible alternative declaration (signature) of this method is explained with manual chapter 12.3 Optimizations With "constexpr"-Boxing.

Parameters

target	The placeholder of the destination box.
value	The value to that is to be boxed.

Definition at line 272 of file typetraits.inl.

---

The documentation for this struct was generated from the following file:

• typetraits.inl