.. highlightlang:: us

.. index:: MapLookup

.. _maplookup:

MapLookup
=========

.. us.tag  MapLookup ENGLISH Map_Get Changed420 Changed570

:ref:`MapLookup` uses a hashing algorithm to quickly find the map element with a
key that exactly matches the given key.

.. function::  data = MapLookup(hMap, ssKey)
    data = MapLookup(hMap, ssKey, default_value)

.. us.return

**Return Value**

*data* is a real, complex or string matrix. In case of an error the function
returns 0.

.. us.params

**Parameters**

.. uparam:: hMap

   *hMap* Identifies the map.

.. uparam:: ssKey

   *ssKey* specifies the key that identifies the element to be looked up.

.. uparam:: default_value

   The function returns the value *default_value*, if the key *ssKey*
   does not exist in the map . *default_value* can be a real, complex or 
   string matrix.

.. us.comment

**Comment**

To check if the return value is valid the :ref:`ObjGetOk` can be used. If the key
does not exist in the map :ref:`ObjGetOk` returns FALSE (0).

.. us.example

**Example**

::

   hMap = MapCreate();
   MapSetAt(hMap, "Test1", [1,2,3,4,5,6]);
   MapSetAt(hMap, "Test2", [2,5,7,6,3,1,6,7,8]);
   MapSetAt(hMap, "Header1", ["1,5l", "4 Valves"]);
   if (MapKeyExists(hMap, "Test2") {
       rmStr = MapLookup(hMap, "Test2");
   } else 
       // set to default:
       rmStr = [2,5,7,6,3,1,6,7,8];
   }
   // or
   rmStr = MapLookup(hMap, "Test1", [2,5,7,6,3,1,6,7,8])

.. us.history

**History**

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

   * - Version
     - Description
   * - 5.7.0
     - New parameter *default_value* added.
   * - 4.2.0
     - The function can return 8-bit clean strings (may contain 0-characters).

.. seealso::
   :ref:`overview-map`,
   :ref:`MapCreate`,
   :ref:`MapSetAt`,
   :ref:`MapKeyExists`

:sub:`id-2108427`