SYNOPSIS
    mixed search (object this, object  what, int mode)
    mixed search (object this, string  what, int mode)
    mixed search (object this, string* what, int mode)

DESCRIPTION
    search() searches for an object 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-string exploded by
      its spaces. 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.

    Results:
      0
        No matching object was found.

      <obj>       (SM_OBJECT only)
      ({ <obj> }) (other modes)
        A single object was specified and found.

      ({ <obj>, <obj>, ... <obj> })
        The specified singular id matched a whole class of objects.

      ([ FOUND_SINGLE: ({ <obj> ... <obj> })  (SM_MULTI only)
       , FOUND_CLASS : ({ <obj> ... <obj> })
       , FOUND_MULTI : ({ <obj> ... <obj> })
       , FOUND_NUMBER: <integer> 
      ])
        A plural id was specified and matched those objects of
        FOUND_MULTI. If a count was specified (SM_COUNT only), it
        is stored as FOUND_NUMBER.
        FOUND_SINGLE and FOUND_CLASS contain non-plural matches,
        which may happen, if one search has to find objects from
        several containers ('get gems from all bags').

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