doc/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 examples).

        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)