Collaboration diagram for Placeholder:

Class 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 it 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. In C++ 11, constructors have to be empty except member initializations. Apart from that, in all C++ versions, 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 that 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 278 of file placeholder.inl.

Public Fields
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 Methods
template<unsigned int UsageLength>
ALIB_WARNINGS_RESTORE ALIB_CPP14_CONSTEXPR void	Clear ()

constexpr ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE integer	GetInteger (int idx) const

constexpr uinteger	GetUInteger (int idx) const

constexpr integer	Length () const

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

ALIB_CPP14_CONSTEXPR void	Pointer (const char *value)

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

ALIB_CPP14_CONSTEXPR void	SetInteger (int idx, integer value)

ALIB_CPP14_CONSTEXPR void	SetUInteger (int idx, uinteger value)

constexpr uinteger	ULength () const

constexpr void *	VoidPointer () const

ALIB_CPP14_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)

Member Function Documentation

◆ Clear()

ALIB_WARNINGS_RESTORE ALIB_CPP14_CONSTEXPR void Clear ( )

inline

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 431 of file placeholder.inl.

◆ GetInteger()

constexpr ALIB_WARNINGS_ALLOW_UNSAFE_BUFFER_USAGE 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 385 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 403 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 371 of file placeholder.inl.

Here is the call graph for this function:

◆ Pointer() [1/2]

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 345 of file placeholder.inl.

◆ Pointer() [2/2]

ALIB_CPP14_CONSTEXPR void Pointer ( const char * value )

inline

Sets a pointer of type char*.

Parameters

value The value to set.

Definition at line 358 of file placeholder.inl.

◆ Read()

constexpr ALIB_FORCE_INLINE 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 548 of file placeholder.inl.

◆ SetInteger()

ALIB_CPP14_CONSTEXPR void SetInteger	(	int	idx,
		integer	value
	)

inline

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 393 of file placeholder.inl.

◆ SetUInteger()

ALIB_CPP14_CONSTEXPR void SetUInteger	(	int	idx,
		uinteger	value
	)

inline

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 411 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 377 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 351 of file placeholder.inl.

◆ VoidPointer() [2/2]

ALIB_CPP14_CONSTEXPR void VoidPointer ( const void * value )

inline

Sets a pointer of type void*.

Parameters

value The value to set.

Definition at line 365 of file placeholder.inl.

◆ Write() [1/3]

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]

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]

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

Class Description

Custom Boxing

Constexpr Boxing

Public Fields

Public Methods

Member Function Documentation

◆ 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]