SYNOPSIS
    mixed searchm (object this, object  what, int mode, void|closure pred)
    mixed searchm (object this, string  what, int mode, void|closure pred)
    mixed searchm (object this, string* what, int mode, void|closure pred)

DESCRIPTION
    search() searches for one or several objects from a given livings
    viewpoint. 
    For a complete description read /doc/concepts/search.

    <this> is the living, from which viewpoint the search happens,
      or if SM_LOCATE is specified, the container within the
      search shall happen.
    <what> may be an object, an id-string or an id-strings. If it
      is an object, the result is either the object itself (if it is
      contained), or 0.
    <mode> specifies where the living should search. Outside of
      its inventory it must be able to see, unless SM_IGNLIGHT
      is set.
    <pred> is a filter function which has to take an object as
      first argument and which has to return non-zero if the object
      should be considered for finding at all.

    If the <mode> is SM_OBJECT, the result is an array of objects
    (and id-strings for those not found).

    Else, the found objects are folded into an result array of
    four result-arrays:

      string *result[FOUND_IDS]
        The id-strings which could not be located.

      object *result[FOUND_SINGLE]
        Those objects which could be unambiguously identified.

      object *result[FOUND_CLASS]
        Objects which matched a class id-string.
        These are sub-organized into arrays for each class-match.

      object *result[FOUND_MULTI]
        Objects which matched a plural id-string.
        These are sub-organized into arrays for each plural-match,
        with each sub-array starting with parsed integer count (or
        0 if there was none).

      int     result[FOUND_SPECS]
        How much distinct object specifications have been processed
        successfully.

    It is guaranteed that the FOUND_SINGLE objects to not appear
    in the other result-arrays.
    If there is no data for one of the result types, the
    associated entry is set to 0.

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