|
ALib C++ Library
|
by |  |
|
Loading...
Searching...
No Matches
|
ALib C++ Library
|
by | |
|
This is the central class of ALib Boxing . By using template meta programming, an object of this class can be created by passing just any C++ type to the constructor. The passed value will be "boxed" within the instance of this class.
Then, the instances of this class support type checking, value extraction ("unboxing") and the invocation of "virtual methods". All features are customizable in detail per "boxable type".
A thorough introduction to and documentation of all aspects of ALib Boxing is given with Programmer's Manual ALib Boxing .
Functors std::hash, std::equal_to and std::less are specialized for this type with the inclusion of header file alib/compatibility/std_boxing_functional.hpp as documented with namespace alib::compatibility::std.
|
protected |
|
protected |
Default constructor.
After creation with this constructor, a call to IsType<void> returns true. To reset an instance previously used, assign keyword nullptr.
|
defaultnoexcept |
Trivial default destructor.
Constructor using template meta programming to fetch any type of C++ value.
Internally, this constructor is implemented using a set of different constructors which are selected by the compiler using std::enable_if conditions.
Types derived from class Box itself are boxed by coping the internal values of the box. This means, that boxing objects of derived types is similar to "downcasting" the object to class Box.
| TBoxable | Any C++ type to be boxed. |
| src | The src value or pointer type T. |
|
inline |
|
inline |
Same as method Call, but usable with interfaces that only accept a mutable (aka not constant) box. Technically, the only difference between this method and Call is that the latter is declared const.
| TFDecl | The function type to call. Has to be explicitly specified. |
| TArgs | Types of the variadic arguments args . Do not need to be specified. |
| args | Variadic arguments forwarded to the function. |
TReturn() if the requested function type was not found for this Box. Definition at line 1189 of file box.inl.
|
inline |
Invokes a function registered for boxes of the mapped type. The function declaration is provided with the first template parameter TFDecl . The variadic further template parameters do not need to be specified. They specify the types of the called function's parameters and are matched against the function signature given with the declaration. If the types of the given function arguments do not correspond to the types of the box-function called, a compile-time error is raised.
If no corresponding function was registered for the mapped type, then a default function , that is applicable to any mapped type is searched. If neither is found, a default value of the return type of the function is returned.
With debug builds, an assertion is raised if the function type is not known at all to ALib Boxing . This is true, if an implementation was neither registered with any other mapped type, nor registered as a default.
| TFDecl | The function type to call. Has to be explicitly specified. |
| TArgs | Types of the variadic arguments args . Do not need to be specified. |
| args | Variadic arguments forwarded to the function. |
TReturn() if the requested function type was not found for this Box. Definition at line 1135 of file box.inl.
|
inline |
Alternative version of non-constant version of method Call, which accepts the function's pointer as a first argument. Such pointer can be received upfront with method GetFunction.
| TFDecl | The function type to call. Has to be explicitly specified. |
| TArgs | Types of the variadic arguments args . Do not need to be specified. |
| args | Variadic arguments forwarded to the function. |
| function | The function to invoke. |
TReturn() if the requested function type was not found for this Box. Definition at line 1217 of file box.inl.
|
inline |
Alternative version of method Call, which accepts the function's pointer as a first argument. Such pointer can be received upfront with method GetFunction.
| TFDecl | The function type to call. Has to be explicitly specified. |
| TArgs | Types of the variadic arguments args . Do not need to be specified. |
| args | Variadic arguments forwarded to the function. |
| function | The function to invoke. |
TReturn() if the requested function type was not found for this Box. Definition at line 1161 of file box.inl.
| ALIB_API void Clone | ( | monomem::MonoAllocator & | memory | ) |
Returns the result of invocation of built-in boxing function FHashcode .
| memory | A monotonic allocator used for storing cloned data. |
|
inline |
Non-constant variant of Data, that allows write access to the internal memory of this box.
A use case for non-constant access could be the implementation of a non-constant box-function. In fact, this is the only occasion where within any ALib Module this method was needed.
|
inline |
|
inline |
Returns the vtable of this instance that is associated with the currently boxed type.
Available only with debug builds.
|
inline |
Returns the std::type_info struct describing the element type of mapped array types.
typeid(void) is returned.std::type_info of the mapped type. Searches an implementation of a box-function identified by template parameter TFDecl , which has to be implemented according the rules of function declarations.
If found, a non-nulled function pointer is returned, otherwise a nulled one.
On success, the function can be invoked by passing the returned pointer to method CallDirect. This approach avoids further searches that are otherwise to be performed with multiple invocations of method Call.
If parameter defaults equals Reach::Local , functions specific to the mapped type of this box (registered using BootstrapRegister ) are searched. If Reach::Global is given, then a defaulted function (registered using BootstrapRegisterDefault ) is searched, if no specific function was found.
assert( box1.IsSameType( box2 ) );
auto* func= box1.GetFunction<FMyFunc>( Reach::Global );
if( func != nullptr )
for( int i= 0; i< 10; ++i )
{
box1.CallDirect<FMyFunc>( func, i );
box2.CallDirect<FMyFunc>( func, i );
}
| TFDecl | The function declaration to search for. |
| searchScope | Reach::Local chooses type-specific functions only, while. Reach::Global includes default functions in the search. |
| isInvocation | Available only in debug compilations. If true, a counter associated with an implementation found is increaed to provide statistics. Defaults to false and should not be given. |
nullptr in case that no function is available. Returns the number of relevant bytes used in the placeholder.
This method is used with default implementations of box-functions FHashcode and FEquals .
|
inlinestaticprotected |
Shortcut inline method to retrieve the vtable singleton for the template type. In debug-compilations, the received vtable is checked for being registered.
| TBoxable | The source type to receive the vtable for. |
| size_t Hashcode | ( | ) | const |
Returns the result of invocation of built-in boxing function FHashcode .
Definition at line 195 of file boxing.cpp.
|
inline |
Returns true if this box represents an array of objects. In this case, method UnboxLength (usually) will return the length of the array and UnboxElement may be used to access elements of the array.
true if this box represents an array, false otherwise. Definition at line 711 of file box.inl.
|
inline |
Returns true if this objects represents an array and the element type equals template parameter TElementType .
| TElementType | The array element type to compare our element type with. |
true if this box represents an array of given type, false otherwise. Definition at line 724 of file box.inl.
|
inline |
Tests if this this box contains one of types char, wchar_t, char16_t or char32_t.
With default library compilation that disables symbol ALIB_FEAT_BOXING_BIJECTIVE_CHARACTERS, this method will be inlined and simply returns IsType<wchar>().
Otherwise this method will not be inlined and tests for all four different character types.
true if this box contains a character type, false otherwise. Definition at line 651 of file box.inl.
|
inline |
Returns true if this box contains an element of a scoped or non-scoped enum type. Enum element values are always boxed as type integer stored in union field Placeholder .
true if this box contains an object boxed as pointer type, false otherwise. Definition at line 748 of file box.inl.
| bool IsFloatingPoint | ( | ) | const |
Tests if this this box contains a floating point type.
double and long double. If it is set, in addition type float is tested.true if this box contains a floating point type, false otherwise. Definition at line 168 of file boxing.cpp.
| bool IsNotNull | ( | ) | const |
Returns the result of a call to built-in boxing function FIsNotNull .
false if this object represents a nulled object, true otherwise. Definition at line 194 of file boxing.cpp.
|
inline |
Returns the negated result of a call to built-in boxing function FIsNotNull .
true if this object represents a nulled object, false otherwise. Definition at line 1312 of file box.inl.
|
inline |
Returns true if this box uses pointer-boxing, otherwise false. The default boxing of pointers will store the pointer to the boxed object in union Placeholder::Pointers .
true if this box contains an object boxed as pointer type, false otherwise. Definition at line 736 of file box.inl.
Returns true if other and this object share the same boxed type. Note, if this box has void state (no value boxed), then this method returns false, even if given other is void state as well.
| other | The box to compare our type with. |
true if this box has the same type like other , false otherwise.
|
inline |
Tests if this this box contains a signed integral type (one of the C++ fundamental types of different sizes).
With compilation that disables ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS, this method will be inlined and simply returns IsType<integer>().
Otherwise this method will not be inlined and tests for the five different integer sizes (int8_t, int16_t, int32_t, int64_t and intGap_t ).
true if this box contains a signed integral type, false otherwise. Definition at line 574 of file box.inl.
Checks if this box stores a value of type TBoxable .
If template parameter TBoxable it is not unboxable, a compile-time assertion is given, with specific guidance why the type must not be unboxed and for that reason must not even be tested for.
Special type void may be given to test if this box does contain a value at all. A box does not contain a value, after
nullptr, ornullptr.For more information on the "void state" of boxes, see manual chapter 12.1 Void And Nulled Boxes.
| TBoxable | The boxable type guessed. |
true if this box stores a value that is convertible to type TBoxable , false otherwise.
|
inline |
Tests if this this box contains an unsigned integral type (one of the C++ fundamental type of different sizes).
With default library compilation that disables ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS, this method will be inlined and simply returns IsType<uinteger>().
Otherwise this method will not be inlined and tests for the five different integer sizes (uint8_t, uint16_t, uint32_t, uint64_t and uintGap_t ).
true if this box contains an unsigned integral type, false otherwise. Definition at line 592 of file box.inl.
Explicit cast operator to bool. Returns the result of built-in box-function FIsTrue .
true if the boxed value represents value true, false otherwise. Definition at line 193 of file boxing.cpp.
Comparison operator. Returns the negated result of operator==.
| rhs | The right hand side argument of the comparison. |
true if this object equals rhs , false otherwise. Comparison operator. Returns the result of invocation of built-in box-function FIsLess .
| rhs | The right hand side argument of the comparison. |
true if this object is smaller than rhs , otherwise false. Definition at line 204 of file boxing.cpp.
Comparison operator. Uses a combination of operator< and operator==.
| rhs | The right hand side argument of the comparison. |
true if this object is smaller than rhs , otherwise false. Definition at line 205 of file boxing.cpp.
Trivial default move assign operator.
this. Trivial default copy assign operator.
this. Comparison operator. Returns the result of invocation of built-in boxing function FEquals .
| rhs | The right hand side argument of the comparison. |
true if this object equals rhs , false otherwise. Definition at line 203 of file boxing.cpp.
Comparison operator. Uses a combination of operator< and operator==.
| rhs | The right hand side argument of the comparison. |
true if this object is smaller than rhs , otherwise false. Definition at line 206 of file boxing.cpp.
|
inline |
Returns the std::type_info struct describing the boxed type. To get the element type of boxed arrays, use ElementTypeID.
nullptr assigned, typeid(void) is returned.std::type_info reference is returned that corresponds to an array of the element type of size 1. For example, if an array of type double of arbitrary size was boxed, then typeid(double[1])is returned.std::type_info of the mapped type. Definition at line 902 of file box.inl.
|
inline |
Returns the contents of this box converted to type TBoxable . By default this is done by invoking template method Placeholder::Read on field data. This behavior might be customized by specializing structT_Boxer ".
With debug builds, the actual type of this object is
\ref ALIB_ASSERT_ERROR "asserted" to equal the templated return type.
\note
With debug builds, it is \ref ALIB_ASSERT_ERROR "asserted" that given TBoxable is mapped to the type stored, so that IsType returned true for TBoxable . In release compilations, no checks are performed!
| TUnboxable | The type to unbox. If it is not unboxable, a compile-time assertion is given. |
|
inline |
Returns the pointer to the first array element.
true and the stored type is the same as requested. In release compilations, no checks are performed!| TElementType | The type of array elements |
Definition at line 948 of file box.inl.
|
inline |
Unboxes one of the types char, wchar_t, char16_t or char32_t and converts it to wchar .
With default library compilation that disables ALIB_FEAT_BOXING_BIJECTIVE_CHARACTERS, this method will be inlined and simply returns Unbox<wchar>().
Otherwise this method will not be inlined and tests for the four different character types prior to unboxing.
Definition at line 668 of file box.inl.
|
inline |
Returns a reference to element idx of the boxed array.
true, that the stored type is the same as the requested type and the provided idx is between 0 and the length of the array. In release compilations, no checks are performed!| TElementType | The type of array elements |
| idx | The index of the element to receive. |
Definition at line 999 of file box.inl.
| double UnboxFloatingPoint | ( | ) | const |
Unboxes a floating point value as double.
double and long double and convert the latter. If it is set, in addition type float is tested.true if this box contains a floating point type, false otherwise. Definition at line 180 of file boxing.cpp.
|
inline |
Returns the length of a boxed Array. While in theory, the length applies only to arrays, in debug-compilations, no run-time type check is performed. This way, mapped types that use the second "word" of the placeholder to store a value of type integer, may also use this function.
In the latter case, the name of this method might be misleading and therefore, it is recommended to use Data().integer[1] to denote that a custom interpretation of the placeholder is performed. The compilation result is the same.
Some quick rational for why ALib is generally using signed types for array lengths, is given here.
Definition at line 979 of file box.inl.
|
inline |
Convenient method to unbox types boxed as pointers, as a non-const pointer type.
| TUnboxable | The type to unbox. If it is not unboxable, a compile-time assertion is given. |
const object.
|
inline |
Unboxes a signed integral.
With default library compilation that disables ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS, this method will be inlined and simply returns Unbox<integer>().
Otherwise this method will not be inlined and tests for the five different integer sizes (1, 2, 4 and 8 bytes size and the alib::intGap_t) prior to unboxing.
Definition at line 609 of file box.inl.
|
inline |
Unboxes an unsigned integral.
With default library compilation that disables ALIB_FEAT_BOXING_BIJECTIVE_INTEGRALS, this method will be inlined and simply returns Unbox<uinteger>().
Otherwise this method will not be inlined and tests for the five different integer sizes (1, 2, 4 and 8 bytes size and the alib::uintGap_t) prior to unboxing.
Definition at line 626 of file box.inl.