SYNOPSIS
    mixed locate (object this, object  what, int mode, void|object *also)
    mixed locate (object this, string  what, int mode, void|object *also)
    mixed locate (object this, string* what, int mode, void|object *also)

DESCRIPTION
    locate() searchs the thing <what> in the container <this>. 
    However, as locate() is called as part of a search(), there is no
    real need to call it manually in most cases.

    For a complete description read /doc/concepts/search.

    <this> is the container in which the search happens.
    <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 what is to be searched how.
    <also> (if specified) is a list of objects to be considered
      part of <this> own inventory.

    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), searchm(SEFUN), sort_findings(SEFUN)