This struct constitutes a type declaration for a box-function. The function is used to create parsable expression "literals" from constant values of custom type stored in boxes.
The function is used by the library if all of the following occurs:
If the last condition is met, compilation of the "normalized optimized expression string " would fail. If it is not met, then without a proper implementation of this function, the only "damage" is that such string would show an integral value where a constant custom type was expected.
The challenge of implementing this box-function for a custom type, is to convert constants of custom types back into a normalized, human readable but also compilable expression string. As the expression syntax only defines the built-in literal types Integer , Float and String , the constants have to be created using either appropriate custom identifiers or "constructor functions" that have to be provided in addition along with the implementation of this box-function to make it compilable.
A sample for that situation is given in chapter 11.5.6 Normalized, Optimized Expression Strings of the Programmer's Manual.
The identifiers and constructor functions in turn need to be compile-time evaluatable to ensure that recompiling the optimized string results to constants so that the same optimized expression program is generated..
So far, this probably sounded a little complicated. Let us look step by step at the sample given in the aforementioned manual section, that is solved internally by the library using this box-function declaration.
Compiler plug-in DateAndTime introduces ALib class TimePointBase::Duration to expressions. This is for example done by defining identifiers as follows:
The "constructor functions" are declared to be compile-time invokable and return a constant value at compile-time in case their input parameter is constant. When the program - that may due to optimization not contain the identifiers any more - becomes de-compiled, these constants have to be written to the normalized expression string in a way that corresponding constant values of type Duration are expressed.
To perform this task, an implementation of the box-function that this struct declares has to be registered with boxes containing values of TimePointBase::Duration.
Registrations of box-functions have to be done in the bootstrap code of the library. In this case it is done in static method plugins::DateAndTime::Bootstrap . The function name that is used for the implementation is FToLiteral_Duration. Here is the line of code that registers the function with the boxed type:
The implementation is given in an anonymous namespace of the compilation unit of compiler plug-in DateAndTime. The function's signature has to meet the one given with type definition Signature of this struct. Besides the first parameter that passes the box that the function is invoked on (the one containing the constant value of custom type), second parameter expressionString provides the AString that the function is requested to write the "generation expression" to.
The implementation code looks as follows:
As it can be understood from the code, the interface implementation tries to find the best matching "constructor function" for teh time span given, writes its name and the constant parameter enclosed by brackets "()"
.
Only with such interface implementation in place - one that covers all possible constants - this library is able to create parsable, normalized, optimized expression strings. To finalize this example, we check what the result for three sample expressions looks like:
Definition at line 1268 of file expressions.hpp.
#include <expressions.hpp>
Public Type Index: | |
using | Signature = void (*) ( const Box& constantValue, AString& expressionString ) |
Signature of the invokable function.
constantValue | The constant program value that is about to be written into expressionString . |
expressionString | The expression string that is currently generated. |
Definition at line 1277 of file expressions.hpp.