A protected member of this union is contained in class Box to store a boxed object. This member is passed as an argument to static methods Write and Read of type traits struct T_Boxer, which implement boxing and unboxing.
This union declares different inner structs and unions and contains one corresponding member of each. This sorts the union fields into different groups, which his also helpful when debugging instances of type box.
The overall size of this union is two times the size of std::size_t
, hence 16 bytes on a 64-bit and 8 bytes on a 32-bit system.
Virtually any sort of data might be written into the union. With non-injective boxing, what means that two or more types are boxed to the same target type, the format that type uses has to be implemented by all Write and Read methods of any specialization of T_Boxer. Otherwise, undefined behavior occurs.
This type offers two sets of templated overloaded methods, named Write and Read. In addition to be overloaded, the methods use TMP to be selected by the compiler only for certain template types.
The methods cover boxing and unboxing of the most frequent types like
For these type, the default implementation of T_Boxer::Write and Read, as given for example with macro ALIB_BOXING_CUSTOMIZE_TYPE_MAPPING.
Custom implementations of boxing and unboxing may read from and write to the union data directly.
In the latter case, a "continuous" use of the available data is suggested. Aat least, gaps in writing should be initialized with a value (e.g., 0
). The rationale for this is that the default implementations of box-functions FHashcode and FEquals use only the first N relevant bytes. If now, gaps are not written, they contain "random" data, what would cause a failure of these default functions.
By the same token, if a customization of a non-array type writes a different length then C++ operator sizeof
reports for the mapped type, then also struct TMP T_SizeInPlaceholder has to be specialized for that type, so that method Box::GetPlaceholderUsageLength reports the right value. Not that also method Clear, used when boxing nulled pointers, only clears as much data in this struct as reported by T_SizeInPlaceholder.
As explained in chapter 12.3 Optimizations With "constexpr"-Boxing, method T_Boxer::Write may be defined with a different signature that returns a value of this union, instead of receiving one to be filled. The aim is to allowing constexpr
instances of class Box to be created from likewise constexpr
values. The C++ language rules for constexpr
constructors impose some restrictions. No reinterpret casts have to be performed. Furthermore, an union constructor must not initialize a field of an inner union by accessing it using the dot operator. Instead, the inner unions need to provide constexpr
constructors that are called for the field of the outer union.
While this library defines constexpr
-boxing for all fundamental types and for most library types of other modules (if it provides customized boxing for), still such customization is considered "expert use" as the gain to do it for custom types is marginal. For this reason, the constructors of inner structs and unions, and all reflection of those with a corresponding constructor of this outer union are not documented. This is to keep the documentation lean and non-repetitive. Therefore, for reference of the constexpr
constructors available for this union, please consult the source code, found in file alib/boxing/placeholder.inl.
Definition at line 260 of file placeholder.inl.
Public Field Index: | |
detail::StructArray | Array |
Used when storing C++ arrays. | |
integer | Debugger_Integral |
This union field was inserted only for debug display. | |
character * | Debugger_String |
This union field was inserted only for debug display. | |
detail::UnionFloatingPoints | FloatingPoints |
Collection of floating points of different sizes. | |
detail::UnionIntegrals | Integrals |
Collection of integrals of different sizes. | |
detail::UnionPointers | Pointers |
Collection of void , char and character pointers. | |
Public Method Index: | |
Placeholder () | |
Default constructor, leaves everything uninitialized. | |
template<unsigned int UsageLength> | |
ALIB_WARNINGS_RESTORE constexpr void | Clear () |
ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE constexpr integer | GetInteger (int idx) const |
constexpr uinteger | GetUInteger (int idx) const |
constexpr integer | Length () const |
template<typename TReturn > | |
constexpr TReturn * | Pointer () const |
constexpr void | Pointer (const char *value) |
template<typename TMapped > | |
ALIB_FORCE_INLINE constexpr TMapped | Read () const |
constexpr void | SetInteger (int idx, integer value) |
constexpr void | SetUInteger (int idx, uinteger value) |
constexpr uinteger | ULength () const |
constexpr void * | VoidPointer () const |
constexpr void | VoidPointer (const void *value) |
template<typename TArray > | |
constexpr void | Write (const TArray *pointer, integer length) |
template<typename TMapped > | |
void | Write (const TMapped &value) |
template<typename TMapped > | |
void | Write (const TMapped &value) |
detail::StructArray Array |
Used when storing C++ arrays.
Definition at line 263 of file placeholder.inl.
integer Debugger_Integral |
This union field was inserted only for debug display.
Definition at line 269 of file placeholder.inl.
character* Debugger_String |
This union field was inserted only for debug display.
Definition at line 268 of file placeholder.inl.
detail::UnionFloatingPoints FloatingPoints |
Collection of floating points of different sizes.
Definition at line 265 of file placeholder.inl.
detail::UnionIntegrals Integrals |
Collection of integrals of different sizes.
Definition at line 264 of file placeholder.inl.
detail::UnionPointers Pointers |
Collection of void
, char
and character pointers.
Definition at line 262 of file placeholder.inl.
|
inline |
Default constructor, leaves everything uninitialized.
Definition at line 273 of file placeholder.inl.
|
inlineconstexpr |
Clears this box data.
It has to be ensured that all memory used by a mapped type are cleared. For example, the default implementations of box-functions FHashcode and FEquals are using the relevant bytes of this placeholder and those must not be of random value.
For efficiency reasons, the rest should not be cleared.
UsageLength | The number of bytes to clear. |
Definition at line 390 of file placeholder.inl.
|
inlineconstexpr |
Returns the signed integral at index idx.
idx | The index requested. Only 0 and 1 is allowed. |
Definition at line 350 of file placeholder.inl.
|
inlineconstexpr |
Returns the unsigned integral at index idx.
idx | The index requested. Only 0 and 1 is allowed. |
Definition at line 364 of file placeholder.inl.
|
inlineconstexpr |
Returns the length of a stored array (the second word stored).
Definition at line 340 of file placeholder.inl.
|
inlineconstexpr |
Returns a pointer of type TReturn.
TReturn | The requested pointer type |
Definition at line 322 of file placeholder.inl.
|
inlineconstexpr |
Sets a pointer of type char*
.
value | The value to set. |
Definition at line 331 of file placeholder.inl.
|
inlineconstexpr |
Templated read method for value types. The value is dereferenced from the start of the placeholder memory.
TMapped | The value type to unbox. |
Definition at line 505 of file placeholder.inl.
|
inlineconstexpr |
Sets value at index idx.
idx | The index to store value in. Only 0 and 1 is allowed. |
value | The value to set. |
Definition at line 356 of file placeholder.inl.
|
inlineconstexpr |
Sets value at index idx.
idx | The index to store value in. Only 0 and 1 is allowed. |
value | The value to set. |
Definition at line 370 of file placeholder.inl.
|
inlineconstexpr |
Returns the length of a stored array (the second word stored).
Definition at line 344 of file placeholder.inl.
|
inlineconstexpr |
Returns a pointer of type void*
.
Definition at line 326 of file placeholder.inl.
|
inlineconstexpr |
Sets a pointer of type void*
.
value | The value to set. |
Definition at line 336 of file placeholder.inl.
|
inlineconstexpr |
This version of the overloaded methods is used for boxing C++ array types. The type and length of the array is stored in field Array of the data union.
Note that for unboxing custom types from C++ array types, a custom implementation of T_Boxer::Read is needed. Such implementation reads the pointer and length directly from this struct. (I.e. there is no overloaded method Read available for arrays.)
TArray | The templated pointer type. |
pointer | The pointer to store. |
length | The array's length to store. |
|
inline |
This version of the overloaded methods is selected using TMP with most types, namly fundamental, pointers and those value types that are copy assignable.
The type is stored at the start of the data, by reinterpreting the address of field UnionPointers::Memory to a pointer to TMapped and using the C++ assign operator on that dereferenced pointer.
TMapped | The mapped type to store. |
value | The value of type TMapped to store. |
|
inline |
This version of the overloaded methods is selected using TMP with types boxed as values that are not copy-assignbable.
The copying is performed using memcpy
. This is necessary to avoid de-referencing type-punned pointers which would break the strict-aliasing rule when compiling the code with higher optimization levels. Note that modern compilers like GCC usually optimize the invocation of memcpy
out.
TMapped | The mapped type to store. |
value | The value of type TMapped to store. |