Default behaviour is to return all FOUND_SINGLE objects, the first FOUND_CLASS object of each class, all uncounted FOUND_MULTI objects and as much counted FOUND_MULTI objects as the parsed count specified.
Result is a mapping of integer keys with at least these entries (which could be 0)
int result[-FOUND_SINGLE]
Non-zero if the <data> contained counted plural objects, where
the specified count was larger than the objects found.
string *result[FOUND_IDS]
The id-string for which no object could be located.
object *result[FOUND_SINGLE]
The array of objects found and considered.
int result[FOUND_SPECS]
How much distinct object specifications have been processed
successfully.
<pred> is a closure which determines how a given obj from <data>
should be considered
int <pred>(object obj, int type, int left, int count)
<obj> is the object to analyze, <type> one of FOUND_SINGLE, FOUND_CLASS and FOUND_MULTI, depending on <obj>s match-type. <left> and <count> are specified for FOUND_CLASS objects only and show the number of objects from this class left to analyze, and how much of the objects analyzed so far have been included into the result.
Result of the <pred> call is an integer to be used as index into the result mapping. Predefined results are 0 (to omit the object from the result mapping) and FOUND_SINGLE (to include the object into the associated field). Own result values may start from FOUND_FREE upwards.
If the result value is negative, the object will be included as if the value would be positive, but for counted FOUND_MULTI objects the internal counter will not be changed.
For convenience, the <pred> may also be specified as non-zero integer, if all objects shall be treated equal.
System-provided predicate closures are
closure sort_f_default(...)
Default <pred>icate is this simulated efun, which returns FOUND_SINGLE for the first FOUND_CLASS object of each class, and for every other object as well.
closure sort_f_std(..., closure extra)
This <pred>icate works as sort_f_default(), except that includes exactly one object of a FOUND_CLASS. Additionally, it calls extra(<object>) for each accepted object, and if it results in non-zero, the returned object is classified as FOUND_NOTHANDLE instead of FOUND_SINGLE.
closure sort_f_prop (string prop)
closure sort_f_nprop (string prop)
This simulate efun constructs a <pred>icate, which combines sort_f_std() together with a query of each checked objects property <prop>.
If the property is non-zero (resp. zero for sort_f_nprop), the object is classified as FOUND_NOTHANDLE.