The AP_NormalisedEvent structure

The AP_NormalisedEvent structure has a pointer to a table of client-visible functions exported by the object called AP_NormalisedEvent_Functions. This function table provides access to the operations that may be performed on the event object:

size - Return the number of elements (name-value pairs) currently stored by the event.

empty - Check whether the event is empty or not.

add - Add a new name-value pair to the event. The given name and value will be copied into the event. If an element with the same name already exists, it will not be overwritten. This returns an iterator into the events at the point where the new element was added.

addQuick - Add a new name-value pair to the event. The given name and value will be copied into the event. If an element with the same name already exists, it will not be overwritten.

remove - Remove the named element from the normalised event.

removeAll - Remove all elements from the normalised event. The empty function will return AP_TRUE after this function has been called.

replace - Change the value of a named element in the normalised event. If an element with the given name already exists, its value will be replaced with a copy of the given value. Otherwise, a new element is created just as though addQuick had been called.

exists - Check whether a given element exists in the normalised event.

find - Search for a named element in the normalised event. Returns an iterator into the event at the point where the element was located.

findValue - Search for a named element in the normalised event and return its value.

findValueAndRemove - Search for a named element in the normalised event and return its value. If found, the element will also be removed from the event.

findValueAndRemove2 - Search for a named element in the normalised event and return its value. If found, the element will also be removed from the event. Unlike findValueAndRemove it tells you whether it was able to remove the value, or whether it did not exist.

first - Return an iterator pointing to the first element of the normalised event. Successive calls to the next function of the returned iterator will allow you to visit all the elements of the event.

last - Return an iterator pointing to the last element of the normalised event. Successive calls to the back function of the returned iterator will allow you to visit all the elements of the event.

toString - Return a printable string representation of the normalised event. The returned string is owned by the caller and should be freed when it is no longer required.

char8free – Free a string returned by the toString function; should be called when the string is no longer required.

All of these functions take an initial AP_NormalisedEvent* argument; this is analogous to the implicit ‘this’ pointer passed to a C++ object when a member function is invoked on it.

In addition, the AP_NormalisedEvent_ctor constructor function is provided to create a new event instance. AP_NormalisedEvent_dtor destroys a normalised event object, and should be when the event is no longer required to free up resources.

The reader is invited to examine the header file for the full definitions of all these functions.