.. highlightlang:: us

.. index:: obj_lookup

.. _obj_lookup:

obj_lookup
==========

.. us.tag  obj_lookup ENGLISH obj New410 Changed5147 Changed5502

:ref:`obj_lookup` returns the value of a given key.

.. function:: val = obj_lookup(obj, key)
              val = obj_lookup(obj, key, default)

.. us.return

**Return Value**

*val* is the value of the given key. If the key does not exist, the function
returns the number 0 (default), an empty string, or throws an exception
(see :ref:`obj_set_str_return`).

.. us.params

**Parameters**

.. uparam:: obj

   *obj* is the object created with :ref:`obj_create`.

.. uparam:: key

   *key* is a string or an integer number.

.. uparam:: default

   *default* is the value that will be returned if the key does not exists.

.. us.comment

**Comment**

An alternative syntax for ``val = obj_lookup(obj, key)`` is
``val = obj.lookup(key)`` or ``val = obj[key]``. If the key is a string
and matches the rules for function names ``val = m.key`` is allowed too.

.. us.example

**Example**

::

   obj = obj_create()
   obj.set_at(1, 123)
   obj.set_at("a", 456)
   print obj_lookup(obj, 1)
   print obj.lookup(1)
   print obj[1]
   print obj_lookup(obj, "a")
   print obj.lookup("a")
   print obj["a"]
   print obj.a

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2013.2
     - You can specify in :ref:`obj_set_str_return` that the look up call throws
       an exception, if the key does not exist. If a *default* value is specified
       and the key does not exist, the function does not throw an exception.
   * - 5.14.7
     - New parameter *default*.
   * - 4.1.0
     - New.

.. seealso::
   :ref:`overview-uniscript-objects`,
   :ref:`obj_set_at`,
   :ref:`obj_has_key`,
   :ref:`obj_set_str_return`

:sub:`id-1771386`