SYNOPSIS
    mapping sort_findings (mixed data, void|closure pred)

DESCRIPTION
    Sort the <data> computed by a call to searchm(), mainly flattening
    the found objects into one or more neat lists.

    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 examines the result. If the result from that call is a closure,
    it calls this closure with <object> as argument and uses the result
    from that call. If the end result is 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.

SEE ALSO
    search(C), foundp(SEFUN), search(SEFUN), searchm(SEFUN)