ALib C++ Library
Library Version: 2412 R0
Documentation generated by doxygen
Loading...
Searching...
No Matches
Placeholder Union Reference

Description:

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

  • fundamental types,
  • "fitting" value types that are copy assignable,
  • "fitting" value types that are not copy assignable,
  • pointers and
  • arrays (only boxing).

For these type, the default implementation of T_Boxer::Write and Read, as given for example with macro ALIB_BOXING_CUSTOMIZE_TYPE_MAPPING.

Custom Boxing

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.

Constexpr Boxing

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.

Note
Unions StructArray, UnionIntegrals, UnionFloatingPoints and UnionPointers are defined in the detail namespace instead of being inner types. This is due to a restriction of the MSC compiler.
See also
Chapter 7. Customizing Boxing of the Programmer's Manual of ALib Boxing.
Furthermore structs T_Boxer and T_SizeInPlaceholder.

Definition at line 260 of file placeholder.inl.

Collaboration diagram for Placeholder:
[legend]

Public Field Index:

detail::StructArray Array
 Used when storing C++ arrays.
 
integer Debugger_Integral
 This union field was inserted only for debug display.
 
characterDebugger_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)
 

Field Details:

◆ Array

Used when storing C++ arrays.

Definition at line 263 of file placeholder.inl.

◆ Debugger_Integral

integer Debugger_Integral

This union field was inserted only for debug display.

Definition at line 269 of file placeholder.inl.

◆ Debugger_String

character* Debugger_String

This union field was inserted only for debug display.

Definition at line 268 of file placeholder.inl.

◆ FloatingPoints

Collection of floating points of different sizes.

Definition at line 265 of file placeholder.inl.

◆ Integrals

Collection of integrals of different sizes.

Definition at line 264 of file placeholder.inl.

◆ Pointers

Collection of void, char and character pointers.

Definition at line 262 of file placeholder.inl.

Constructor(s) / Destructor Details:

◆ Placeholder()

Placeholder ( )
inline

Default constructor, leaves everything uninitialized.

Definition at line 273 of file placeholder.inl.

Method Details:

◆ Clear()

template<unsigned int UsageLength>
ALIB_WARNINGS_RESTORE constexpr void Clear ( )
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.

Template Parameters
UsageLengthThe number of bytes to clear.

Definition at line 390 of file placeholder.inl.

◆ GetInteger()

ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE constexpr integer GetInteger ( int idx) const
inlineconstexpr

Returns the signed integral at index idx.

Parameters
idxThe index requested. Only 0 and 1 is allowed.
Returns
The integral value one or two.

Definition at line 350 of file placeholder.inl.

◆ GetUInteger()

uinteger GetUInteger ( int idx) const
inlineconstexpr

Returns the unsigned integral at index idx.

Parameters
idxThe index requested. Only 0 and 1 is allowed.
Returns
The integral value one or two.

Definition at line 364 of file placeholder.inl.

◆ Length()

integer Length ( ) const
inlineconstexpr

Returns the length of a stored array (the second word stored).

Returns
The length stored.

Definition at line 340 of file placeholder.inl.

Here is the call graph for this function:

◆ Pointer() [1/2]

template<typename TReturn >
TReturn * Pointer ( ) const
inlineconstexpr

Returns a pointer of type TReturn.

Template Parameters
TReturnThe requested pointer type
Returns
The pointer stored.

Definition at line 322 of file placeholder.inl.

◆ Pointer() [2/2]

void Pointer ( const char * value)
inlineconstexpr

Sets a pointer of type char*.

Parameters
valueThe value to set.

Definition at line 331 of file placeholder.inl.

◆ Read()

template<typename TMapped >
ALIB_FORCE_INLINE constexpr TMapped Read ( ) const
inlineconstexpr

Templated read method for value types. The value is dereferenced from the start of the placeholder memory.

Template Parameters
TMappedThe value type to unbox.
Returns
The value stored.

Definition at line 505 of file placeholder.inl.

◆ SetInteger()

void SetInteger ( int idx,
integer value )
inlineconstexpr

Sets value at index idx.

Parameters
idxThe index to store value in. Only 0 and 1 is allowed.
valueThe value to set.

Definition at line 356 of file placeholder.inl.

◆ SetUInteger()

void SetUInteger ( int idx,
uinteger value )
inlineconstexpr

Sets value at index idx.

Parameters
idxThe index to store value in. Only 0 and 1 is allowed.
valueThe value to set.

Definition at line 370 of file placeholder.inl.

◆ ULength()

uinteger ULength ( ) const
inlineconstexpr

Returns the length of a stored array (the second word stored).

Returns
The length stored.

Definition at line 344 of file placeholder.inl.

Here is the call graph for this function:

◆ VoidPointer() [1/2]

void * VoidPointer ( ) const
inlineconstexpr

Returns a pointer of type void*.

Returns
The pointer stored.

Definition at line 326 of file placeholder.inl.

◆ VoidPointer() [2/2]

void VoidPointer ( const void * value)
inlineconstexpr

Sets a pointer of type void*.

Parameters
valueThe value to set.

Definition at line 336 of file placeholder.inl.

◆ Write() [1/3]

template<typename TArray >
void Write ( const TArray * pointer,
integer length )
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.)

Template Parameters
TArrayThe templated pointer type.
Parameters
pointerThe pointer to store.
lengthThe array's length to store.

◆ Write() [2/3]

template<typename TMapped >
void Write ( const TMapped & value)
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.

Template Parameters
TMappedThe mapped type to store.
Parameters
valueThe value of type TMapped to store.

◆ Write() [3/3]

template<typename TMapped >
void Write ( const TMapped & value)
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.

Template Parameters
TMappedThe mapped type to store.
Parameters
valueThe value of type TMapped to store.

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