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 rational 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.

On 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 276 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.

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:
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

detail::StructArray Array

Used when storing C++ arrays.

Definition at line 279 of file placeholder.inl.

◆ Debugger_Integral

integer Debugger_Integral

This union field was inserted only for debug display.

Definition at line 285 of file placeholder.inl.

◆ Debugger_String

character* Debugger_String

This union field was inserted only for debug display.

Definition at line 284 of file placeholder.inl.

◆ FloatingPoints

detail::UnionFloatingPoints FloatingPoints

Collection of floating points of different sizes.

Definition at line 281 of file placeholder.inl.

◆ Integrals

detail::UnionIntegrals Integrals

Collection of integrals of different sizes.

Definition at line 280 of file placeholder.inl.

◆ Pointers

detail::UnionPointers Pointers

Collection of void, char and character pointers.

Definition at line 278 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 assured 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

UsageLength The number of bytes to clear.

Definition at line 429 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

idx	The index requested. Only `0` and `1` is allowed.

Returns: The integral value one or two.

Definition at line 383 of file placeholder.inl.

◆ GetUInteger()

constexpr uinteger GetUInteger ( int idx ) const

inlineconstexpr

Returns the unsigned integral at index idx .

Parameters

idx	The index requested. Only `0` and `1` is allowed.

Returns: The integral value one or two.

Definition at line 401 of file placeholder.inl.

◆ Length()

constexpr integer Length ( ) const

inlineconstexpr

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

Returns: The length stored.

Definition at line 369 of file placeholder.inl.

Here is the call graph for this function:

◆ Pointer() [1/2]

template<typename TReturn >

constexpr TReturn * Pointer ( ) const

inlineconstexpr

Returns a pointer of type TReturn .

Template Parameters

TReturn The requested pointer type

Returns: The pointer stored.

Definition at line 343 of file placeholder.inl.

◆ Pointer() [2/2]

constexpr void Pointer ( const char * value )

inlineconstexpr

Sets a pointer of type char*.

Parameters

value The value to set.

Definition at line 356 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

TMapped The value type to unbox.

Returns: The value stored.

Definition at line 544 of file placeholder.inl.

◆ SetInteger()

constexpr void SetInteger	(	int	idx,
		integer	value )

inlineconstexpr

Sets value at index idx .

Parameters

idx	The index to store value in. Only `0` and `1` is allowed.
value	The value to set.

Definition at line 391 of file placeholder.inl.

◆ SetUInteger()

constexpr void SetUInteger	(	int	idx,
		uinteger	value )

inlineconstexpr

Sets value at index idx .

Parameters

idx	The index to store value in. Only `0` and `1` is allowed.
value	The value to set.

Definition at line 409 of file placeholder.inl.

◆ ULength()

constexpr uinteger ULength ( ) const

inlineconstexpr

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

Returns: The length stored.

Definition at line 375 of file placeholder.inl.

Here is the call graph for this function:

◆ VoidPointer() [1/2]

constexpr void * VoidPointer ( ) const

inlineconstexpr

Returns a pointer of type void*.

Returns: The pointer stored.

Definition at line 349 of file placeholder.inl.

◆ VoidPointer() [2/2]

constexpr void VoidPointer ( const void * value )

inlineconstexpr

Sets a pointer of type void*.

Parameters

value The value to set.

Definition at line 363 of file placeholder.inl.

◆ Write() [1/3]

template<typename TArray >

constexpr 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

TArray The templated pointer type.

Parameters

pointer	The pointer to store.
length	The 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

TMapped The mapped type to store.

Parameters

value The 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

TMapped The mapped type to store.

Parameters

value The value of type TMapped to store.

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

placeholder.inl

Description:

Custom Boxing

Constexpr Boxing

Public Field Index:

Public Method Index:

Field Details:

◆ Array

◆ Debugger_Integral

◆ Debugger_String

◆ FloatingPoints

◆ Integrals

◆ Pointers

Method Details:

◆ Clear()

◆ GetInteger()

◆ GetUInteger()

◆ Length()

◆ Pointer() [1/2]

◆ Pointer() [2/2]

◆ Read()

◆ SetInteger()

◆ SetUInteger()

◆ ULength()

◆ VoidPointer() [1/2]

◆ VoidPointer() [2/2]

◆ Write() [1/3]

◆ Write() [2/3]

◆ Write() [3/3]