efun: present

SYNOPSIS:

        object present(string str)
        object present(string str, int n)
        object present(string str, object env)
        object present(string str, int n, object env)

        object present(object ob)
        object present(object ob, object env)

DESCRIPTION:

        This efun checks if an object is present in a given environment.
        The object is identified by id <str> or by an object <ob>. This
        latter form of the efun can be used as a fast way to test for the
        presence of a known object.

        When searching objects by id, the efun by default returns the first
        object found matching the id. In order to search for other than the
        first object, a number can be specified either directly as the
        argument <n>, or implicetely inside the <str> in the form "<id>
        <n>".
        
        By default, the efun searches first in the inventory of
        this_object(), then in its environment. However, if <env> is given,
        the efun searches just inside <env>.

        When searching both inventory and environment of this_object(),
        the numbering is applied linear over both spaces (see example).

        The driver identifies objects by calling the lfun id() in each
        object.

EXAMPLES:

        present("chest");
          --> returns the first 'chest' object in this object.

        present("chest 2")
          --> returns the second 'chest' object in this object.

        present("chest 2", 1)
          --> returns the first 'chest 2' object in this object.

        Assume there is one "chest" inside the current object, and
        two in its environment:
          present("chest", 1) -> returns the chest inside
          present("chest", 2) -> returns the first chest outside
          present("chest", 3) -> returns the second chest outside
        
        A typical 2.4.5-implementation of the "do <id> <n>" command style
        is:

            void init () { add_action ("open_chest", "open"); }

            int open_chest (string str) {
              if (present (str) != this_object ())
                  return 0; /* Not this chest */
              ...
            }

HISTORY:

        LDMud 3.2.11/3.3.610 introduced the (str, n) argument form.
        LDMud 3.3.713 modified the <n> search behaviour so that the
          numbering is applied over both inventory and environment
          together. Before, the numbering was individual in each
          space, leading to situations where low-numbered objects in the
          environment were hidden by those in the inventory.

SEE ALSO:

	
	move_object(E), environment(E), this_object(E), present_clone(E),
	id(A), init(A)