Locate()

Description

FUNCTION: locate(looker, string, where)

The locate function is used to look for an object from the perspective of looker (You must own looker). The database number of the item that is found is returned. The where parameter specifies a list of places to look, from this list:

a - Look for absolute references (#number)
c - Look for exits carried by looker (and by looker's parents).
e - Look for exits in looker's location (and the location's parents).
h - Look for 'here', which matches looker's location.
i - Look in looker's inventory.
m - Look for 'me', which matches looker.
n - Look for looker's neighbors (other objects in the same location).
p - Look for player names prefixed by a '*'
* - Look for everything in the above list.

You may also specify qualifiers in where to help resolve possible ambiguities:

E - Prefer exits over other types.
L - Prefer unlocked exits over locked exits.
P - Prefer players over other types.
R - Prefer rooms over other types.
T - Prefer things over other types.
V - Report "Can't find..." and "Which one..." errors to looker.
X - Select randomly if search finds multiple matches.

If nothing matches, the value #-1 is returned. If more than one thing of the preferred type matches, but nothing matches exactly, the value #-2 is returned, except if the X qualifier was specified in which case one is chosen at random. If more than one thing exactly matches, one is chosen at random. If you specify more than one type preference (E, P, R, or T), then the last one entered is the one that is obeyed. The default is for no type to be preferred.

Related Topics: num(), PARENT OBJECTS.

Examples

> i
test1(#378)
test(#376)
You have 42463 clams.
> look
Nullspace(#250R)
test1(#382)
> say locate(me,test,i)                > say locate(me,tes,in)
You say "#376"                         You say "#-2"
> say locate(me,test,n)                > say locate(here,tes,*)
You say "#382"                         You say "#382"
> say locate(me,test1,in)              > say locate(me,out,e)
You say "#378"                         You say "#252"
> say locate(me,test1,in)              > say locate(me,here,*)
You say "#382"                         You say "#250"

(The formatting probably needs work, but it was the best way I could find to deal with the volume of information without some kind of massive rewrite. --Soylent 02:08, 3 December 2005 (EST))