In many practical applications the source of input is changed in the form of included files that are ‘pasted’ at the point where the according statement occurs. The handling of this scenerio was mentioned in section Include Stack. In this section a more liberal approach is described where the input source can be switched without keeping track of previous content. This is done by the reset() function group which has the following signatures
template <class InputHandleT> void reset(InputHandleT* input_handle, const char* CharacterEncodingName = 0x0); void reset_buffer(QUEX_TYPE_ANALYZER* me, QUEX_TYPE_CHARACTER* BufferMemoryBegin, size_t BufferMemorySize, QUEX_TYPE_CHARACTER* BufferEndOfContentP, const char* CharacterEncodingName = 0x0);
The first argument is an input handle of the user’s like, i.e. either a FILE*, istream*, or wistream* pointer, or a pointer to a derived class’ object. The second argument is character encoding name which is used for the input. If the same converter is used, the CharacterEncodingName must be set to zero. If the analyzer works only on plain memory, the following reset function may be used
void reset(const char* CharacterEncodingName = 0x0);
which allows to specify a character encoding name, but the input stream is not specified.
The reset function clears and resets all components of the lexical analyzer as they are:
The byte order reversion flag is not set to false. It remains as it was before the reset.
The reset buffer function allows to (re-)start lexical analyzis on a user provided buffer. It does basically the same as the reset function. However, it distinguishes two cases as indicated by its return value:
If reset_buffer returns 0x0, then there was no user provided buffer and nothing further is to be done with respect to memory management.
If the return value is non-zero, then there was a buffer memory which as previouly been provided by the user. The return value points to the beginning of the old memory chunk. The engine itselft does not de-allocate the memory. It is the task of the user.
If the function reset_buffer is called with zero as the first argument BufferMemoryBegin, then no memory is initialized. However, the current memory pointer is returned if it was provided by the user. Otherwise, as described above, zero is returned. This is helpful at the end of the analyzis in order to de-allocate any memory that is still contained inside the analyzer. An application of reset_buffer can be observed in file re-point.cpp and re-point.c in the 010 subdirectory of the demos.