boxingtraits.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_boxing of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib {  namespace boxing  {
 
/// This is an empty type used to denote that default boxing is active. The type is
/// used with the default implementation of the type trait #"BoxTraits".
/// Providing this type in custom specializations, makes such specialization in-effective.
/// \see Templated struct #"BoxTraits" for more information.
struct DefaultBoxingTag  {};
 
/// This is an empty type used to denote that a type must not be boxed.
/// To disable \alib_boxing_nl for a custom type, a specialization of type-traits
/// struct #"BoxTraits" must use this type to define type alias
/// #"BoxTraits::Mapping".
///
/// \see
///   Templated struct #"BoxTraits" for more information.
struct NotBoxableTag     {};
 
 
//==================================================================================================
/// This template struct is used to define customized behavior for boxing C++ type
/// \p{TBoxable}.
///
/// ### Default Boxing: ###
/// If this struct is \b not specialized for template type \p{TBoxable},
/// default boxing applies.
/// With that, values \b and pointers of a type are boxed in the same way:
/// - They are both boxed to a pointer of \p{TBoxable} if a value of the type does not "fit" into
///   a box's #"boxing::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 \c operator= of class #"Box", indirection \c operator* is applied.
///
/// <br><p>
/// ### 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. <b>Type alias #".Mapping":</b><br>
///    This alias defines the type that a value of \p{TBoxable} is converted to when boxed.
///
///    If special type #"NotBoxableTag" is given, then boxing is disallowed for
///    type \p{TBoxed}.
///    In this case, only declarations of functions \b Write"and \b Read need to be provided, as
///    they are never invoked.
///
///    The default implementation of this struct uses a second special type available,
///    #"DefaultBoxingTag" which denotes default boxing.
///
/// 2. <b>Boolean constexpr value #".IsArray":</b><br>
///    If set to \c true, array-boxing is performed. In this case #".Mapping" denotes the element
///    type of the boxed C++ array.
///
/// 3. <b>Static Method #".Write":</b><br>
///    This method is invoked for converting source values to mapped types.
///    Often the default implementation given in the default version of this struct is
///    applicable. In this case it can simply be copied to the specialization.
///
///    Custom implementations may use one of the overloads of method
///    #"Placeholder::Write(const TInt)" or alternatively write to the \c union members of the
///    placeholder directly.
///
/// 4. <b>Static Method #".Read":</b><br>
///    This method is invoked for converting the placeholder data back to the boxed source type.
///    Often the default implementation given in the default version of this struct is
///    well suited. In this case it can simply be copied to the specialization.<br>
///    Custom implementations may use one of the overloads of method #"Placeholder::Read"
///    or alternatively read the \c union members of the placeholder directly.
///
///    A type becomes #"IsUnboxable;not unboxable" at the moment this function
///    returns a different type than \p{TBoxable}.<br>
///    This may well be intended, and thus the specialized version of this struct
///    may declare this method to return \c void.
///    In this case a declaration of the method is enough, as it will never be invoked.<br>
///    With conditional specializations of this struct (see  Programmer's Manual
///    chapter #"alib_boxing_customizing_conditional"), the return type might be likewise
///    conditionally set.
///    Such a return type then decides which of the types are unboxable and which are not.
///
/// \note
///   If a specialization uses default type mapping by providing<br>
///
///       using   Mapping=  DefaultBoxingTag;
/// \note
///   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.
///
/// <br><p>
/// ### 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 makes the code
/// more readable. Finally, chances are good that code that uses the macros remains compatible
/// with future versions of module \alib_boxing_nl.
///
/// All macros expect this struct's template type \p{TBoxable} as the first parameter, and most
/// expect the mapped type as the second parameter.
///
/// 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"
///
/// <br><p>
/// ### Value Boxing and Nulled Pointers: ###
/// If a type is boxed as value (either with default boxing or custom boxing) and a \e nulled
/// pointer to that type is boxed, method #"Placeholder::Clear" is invoked
/// instead of this struct's method #".Write".
///
/// <br><p>
/// ### Avoiding Seldom Compilation Errors: ###
/// For technical reasons, namely to avoid compilation problems, some conditional specialization
/// is internally made that declare method #".Read" \c void. This is sometimes needed if a type is
/// not returnable, even if that becomes never be boxed or unboxed.
/// Such a situation might happen, for example, if class #"%Box" is part of a \c union.<br>
/// The specialization is made for the following types of \p{TBoxable}:
/// - C++ array types<br>
///   Those types are fetched by an overloaded constructor that does not (because it cannot)
///   leverage this struct. Likewise, they cannot be unboxed in the usual fashion.
/// - Function types (selected by <c>std::is_function<TBoxable>::value</c>).
///
/// If a dubious error message about method #".Read" not being able to return a certain type occurs,
/// even one that a user's code even "actively" tries to box or unbox, then it might be helpful
/// to specialize this struct for such a type, without providing implementations of #"%.Write" and
/// #"%.Read" and with the latter to return \c void.
///
/// <br><p>
/// \see More explanation and sample code is given in chapter
///      #"alib_boxing_customizing" of the
///      #"alib_mod_boxing;Programmer's Manual" of module \alib_boxing_nl.
///
/// @tparam TBoxable    The source type to customize boxing for.
//==================================================================================================
template<typename TBoxable>
struct BoxTraits {
    /// Defines the mapped type.
    /// Special designator types #"DefaultBoxingTag" and
    /// #"NotBoxableTag" may be given to denote corresponding behavior.
    /// The default implementation specifies designator type #"%DefaultBoxingTag", which
    /// disables custom boxing.
    using   Mapping=      DefaultBoxingTag;
 
    /// Denotes whether type \p{TBoxable} is boxed as an array-type or not.
    static constexpr bool IsArray= false;
 
    /// Used for boxing a value, precisely writing the boxable portion of a type into
    /// field #"Box::data", which is given with parameter \p{box}.<br>
    /// The default implementation of this struct implements this method as follows:
    /// \snippet "boxing/boxingtraits.hpp"    DOX_BOXING_T_BOXER_WRITE
    ///
    /// This implementation leverages the overloaded method #"Placeholder::Write(const TInt)"
    /// and is often all that is needed with custom specializations.
    /// @param box The placeholder of the destination box.
    /// @param value  The value to that is to be boxed.
    DOX_MARKER([DOX_BOXING_T_BOXER_WRITE])
    static constexpr void  Write( Placeholder& box, const TBoxable& value )  { box.Write( value ); }
    DOX_MARKER([DOX_BOXING_T_BOXER_WRITE])
 
    /// Used for unboxing a value, precisely reading the contents of field #"Box::data",
    /// which is given with output parameter \p{box} and creating a value of type \p{TBoxable} from
    /// that.<br>
    /// The default implementation of this struct implements this method as follows:
    /// \snippet "boxing/boxingtraits.hpp"    DOX_BOXING_T_BOXER_READ
    ///
    /// This implementation leverages the overloaded method #"Placeholder::Read"
    /// and is often all that is needed with custom specializations.
    ///
    /// If a different type than \p{TBoxable} is returned, then that source type is not unboxable.
    /// To intend such behavior, for example, because \p{TBoxable} is mapped to a reduced type
    /// and therefore unboxing is not possible, specializations may declare the return type to be
    /// \c void and omit a definition of this method.<br>
    /// With conditional customizations, also other return types may be given, which likewise denote
    /// an unboxable source type. A sample of that is given with Programmer's Manual chapter
    /// #"alib_boxing_customizing_conditional".
    ///
    /// @param box   The Placeholder to unbox the data from
    /// @return \c The unboxed object.
    static
    std::conditional_t<!std::is_abstract<TBoxable>::value, TBoxable, TBoxable&>
    Read( const Placeholder& box) {
DOX_MARKER([DOX_BOXING_T_BOXER_READ])
return box.Read<TBoxable>();
DOX_MARKER([DOX_BOXING_T_BOXER_READ])
    }
 
}; // BoxTraits
 
//############################## critical specializations of BoxTraits #############################
#if !DOXYGEN
 
// This is necessary for types that can't be used as return type in any way, for example
// types with extents, functions, etc.
template<typename TBoxable>
requires( std::is_array_v<TBoxable> || std::is_function<TBoxable>::value )
struct BoxTraits<TBoxable>
{
    using                   Mapping=  DefaultBoxingTag;
    static constexpr bool   IsArray=  std::is_array_v<TBoxable>;
 
    static void             Write( Placeholder& box,  TBoxable& value );
    static void             Read ( const Placeholder& box);
};
 
// void (needed to pass TMP stuff)
template<>
struct BoxTraits<void>
{
    using                   Mapping=  DefaultBoxingTag;
    static constexpr bool   IsArray=  false;
    static void             Write( Placeholder& box,  const void* value );
    static void*            Read ( const Placeholder& box);
};
 
#endif
 
//==================================================================================================
/// This specializable \c constexpr must be set for custom types, if the following applies:
/// - A custom boxing implements #"BoxTraits::Write" in a way that a different number
///   of bytes are used in union #"boxing::Placeholder" than the \c sizeof() operator reports
///   on the mapped type's size.
/// - if the standard copy constructor (used with default boxing) writes a different size.
/// - One of the above and no specialized version of both box-functions #"FHashcode"
///   or #"FEquals" are set.
///
/// <b>Background:</b><br>
/// The default implementations of #"FHashcode" and #"FEquals"
/// must use the first N "relevant" bytes of the placeholder only. The non-relevant bytes are
/// not written and therefore must not be taken into account.<br>
/// To receive the number of relevant bytes, they invoke
/// #"Box::GetPlaceholderUsageLength" (at runtime).
/// This value is set at compile-time with the creation of a mapped type's \e vtable.
/// While for array types, the value is set to the overall size of union #"boxing::Placeholder",
/// for non-array types, the value of this type trait is used.
///
/// It might be surprising, but a built-in specialization exists for even a C++ fundamental type
/// <c>long double</c>, which is dependent on the compiler/platform.
/// For example, on GNU/Linux 64-bit, GCC reports \c 16 with <c>sizeof(long double)</c>.
/// However, if a <c>long double</c> value is copied, e.g with:
///
///      *pointerToLongDouble= 3.14L;
///
/// then only 10 bytes are written. The reason for this is that <c>sizeof</c> reports the size
/// needed for alignment when placed in an array of that type.
/// In the case of \alib_boxing_nl, 6 bytes of the placeholder remain random and therefore
/// must not be used for hashing or testing values on equality.
///
/// @tparam TMappedPlain The mapped type to modify relevant placeholder length for #"%FHashcode"
///                      and #"%FEquals" implementation.
//==================================================================================================
template<typename TMappedPlain>
inline constexpr unsigned SizeTraits= sizeof(TMappedPlain);
 
/// Specialization of traits-expression for type <c>long double</c>.
/// The implementation of this type is platform-dependent and may be adopted to a certain
/// compiler/processor combination by passing the configuration macro
/// #"ALIB_SIZEOF_LONGDOUBLE_WRITTEN".
template<>
inline constexpr unsigned SizeTraits<long double> = ALIB_SIZEOF_LONGDOUBLE_WRITTEN;
 
ALIB_ALLOW_DOCS
//==================================================================================================
/// A concept that is satisfied for types which boxing is customized for, hence for types for which
/// a specialization of the type trait #"BoxTraits" exists.
///
/// \see
///   Concepts #"IsUnboxable", #"IsLocked" and
///   #"IsNotBoxable".
///
/// @tparam T  The type to check.
//==================================================================================================
template<typename T>
concept IsCustomized
=    (  std::is_pointer_v<T> || !std::same_as<DefaultBoxingTag, typename BoxTraits<            T  >::Mapping> )
  && ( !std::is_pointer_v<T> || !std::same_as<DefaultBoxingTag, typename BoxTraits<ALIB_TVALUE(T)*>::Mapping>);
 
// Note: besides checking BoxTraits<T>, in the case a pointer is given, we also have to check
// BoxTraits for the type that results when
// - the pointer is removed and then
// - a const is removed and finally
// - the pointer is added again. Otherwise "const T*" is not deferred to "T*"
 
/// This concept is for internal use. It is satisfied if the given type \p{T} fits into the
/// placeholder, is copy-constructible and trivially destructible.
/// @tparam T       The type to test.
/// @tparam TVal    Decayed version of \p{T}. Deduced by the compiler, must not be given.
template<typename T, typename TVal= ALIB_TVALUE(T)>
concept IsStdPH=        sizeof(std::conditional_t<std::same_as<void, TVal>, void*, TVal>)
                     <= sizeof(Placeholder)
                 &&  std::is_copy_constructible    <TVal>::value
                 &&  std::is_trivially_destructible<TVal>::value;
 
/// This concept is for internal use. It is satisfied if the given type \p{T}
/// has customized boxing with a \c constexpr version of the method <b>BoxTraits<T>::Write</b>
/// which takes only one parameter, namely an instance of \p{T}.
/// @tparam T       The type to test.
template<typename T>
concept IsConstExprWrite=
    requires(T& t) { { BoxTraits<T>::Write(t)  } -> std::same_as<Placeholder>; };
 
 
/// This type trait by default inherits \c std::false_type. If specialized for
/// template type \p{TCharArray} to inherit \c std::true_type, then boxing that type will not be
/// customized automatically with a corresponding specialization of #"ArrayTraits".
/// This keeps the customization of boxing open to be performed in a different way.
///
/// \see
///   See manual chapter #"alib_boxing_strings" of the
///   Programmer's Manual of module \alib_boxing_nl.
///
/// @tparam TCharArray The type that #"ArrayTraits" is specialized for but still no
///                    character array boxing should be performed.
template<typename TCharArray>
struct SuppressCharArrayBoxingTraits  : std::false_type       {};
 
 
template<typename T>
concept IsStringType =
       !SuppressCharArrayBoxingTraits<std::remove_cv_t<T>>::value
  && (    characters::ArrayTraits  <std::remove_cv_t<T>, nchar>::Access == characters::Policy::Implicit
       || characters::ArrayTraits  <std::remove_cv_t<T>, wchar>::Access == characters::Policy::Implicit
       || characters::ArrayTraits  <std::remove_cv_t<T>, xchar>::Access == characters::Policy::Implicit
       );
 
template<typename T>
concept IsUnboxableStringType =
          characters::ArrayTraits  <T, nchar>::Construction == characters::Policy::Implicit
       || characters::ArrayTraits  <T, wchar>::Construction == characters::Policy::Implicit
       || characters::ArrayTraits  <T, xchar>::Construction == characters::Policy::Implicit
       ;
 
 
//==================================================================================================
/// A concept that is satisfied for types for which boxing is customized to disable unboxing.
/// In other words, types for which a specialization of the type trait #"%BoxTraits"
/// exists which declares method #"BoxTraits::Read" to have a different return type
/// than \p{T} or \p{T&}.
///
/// \see
///   #"IsUnboxable" for an alternative concept that satisfied if a type can be
///   unboxed and methods #"Box::IsType" and #"Box::Unbox" do not fail to
///   compile with that type.
///
/// @tparam T  The type to check.
//==================================================================================================
template<typename T>
concept IsLocked =
    !std::same_as<T, std::remove_reference_t<decltype(BoxTraits<T>::Read(std::declval<Placeholder>()))> >;
 
//==================================================================================================
/// A concept that is satisfied if:
///
/// - boxing was customized for the given type and #"NotBoxableTag" was given as
///   mapped type, or
/// - given type is a value type, no customization is given for it, while the corresponding
///   pointer type has customized boxing with mapped type being #"NotBoxableTag", or
/// - given type is a pointer  type, no customization is given for it, while the corresponding
///   value type has customized boxing with mapped type being #"NotBoxableTag".
///
/// If a type is not boxable, it can be neither boxed nor unboxed.
///
/// \see
///   Concepts #"IsCustomized", #"IsLocked" and
///   #"IsUnboxable".
///
/// @tparam T  The type to check.
//==================================================================================================
template<typename T>
concept IsNotBoxable =
          std::same_as<NotBoxableTag, typename BoxTraits<T>::Mapping>
    || (    !IsCustomized<T>
         && (     (    !std::is_pointer_v<T>
                    && std::same_as<NotBoxableTag,
                                    typename BoxTraits<        T*>::Mapping> )
              ||  (     std::is_pointer_v<T>
                    && std::same_as<NotBoxableTag,
                                    typename BoxTraits<std::remove_pointer_t<T>>::Mapping> ) ) )
       ;
 
 
 
 
//==================================================================================================
/// This concept is satisfied if a type can be unboxed and methods #"Box::IsType"
/// and #"Box::Unbox" will not fail to compile with that type.
///
/// With default boxing, one of the types \p{T} and \p{T*} are unboxable (depending on value type
/// size and whether the type is copy-constructible and trivially destructible).
///
/// If custom boxing for either or both of types \p{T} and \p{T*} is in place, then the given type
/// is not unboxable if:
/// - customization is not in place for the version passed (value or pointer).
/// - customization is in place for the given type but concept #"IsLocked" is satisfied.
/// - The type is mapped to #"NotBoxableTag".
///
/// \see
///   Concepts #"IsCustomized", #"IsLocked" and
///   #"IsNotBoxable".
///
/// @tparam T  The type to check.
//==================================================================================================
template<typename T>
concept  IsUnboxable=
        // default boxing
        (    !IsCustomized<std::remove_pointer_t<T> >
          && !IsCustomized<std::remove_pointer_t<T>*>
          &&    bool(  std::is_pointer_v<T> )
             == bool(     ( sizeof(Placeholder) <  sizeof(ALIB_TVALUE(T))  )
                      ||  !std::is_copy_constructible    <ALIB_TVALUE(T)>::value
                      ||  !std::is_trivially_destructible<ALIB_TVALUE(T)>::value )  )
   ||   // custom boxing
        (     IsCustomized<T>
          && !IsLocked    <T>
          && !IsNotBoxable<T> )
 
   ||   // string type
        IsUnboxableStringType<T>
;
 
ALIB_POP_ALLOWANCE
 
 
}} // namespace [alib::boxing]