A
          / \      _             Play Now                         Nemesis on 
          | |     | |  _______   _        _   _______    _______   _    _______
          | |\    | | |   ____| |  \    /  | |   ____|  /   ____| | |  /   ____|
 /-------/-------------------------------------------------------------------,
O= Home <=XX|  About  News  Pics  Adventurers  Wizards  Download  Connect     >
 \-------\-------------------------------------------------------------------'
          | |   \   | |  |____  | |      | | |  |____   ___ \  \  | |  ___ \  \
          | |     \_| |_______| |_|      |_| |_______| |_______/  |_| |_______/
          \ /
           V  

Documentation Area

Document Path: /doc/efun/assoc

Name: assoc - search a key in an alist

Syntax:
	mixed assoc(mixed key, mixed *keys, mixed *|void data_or_fail,
	            mixed|void fail)

Description:
	The assoc efun searches a key in an alist.

	There are three modes of calling:
	i ) With exactly two arguments, the second being an array which's first
	    element is no array. In this case the entire array is searched for
	    the key; -1 is returned if not found, else the index (like
	    member_array, but faster, and you need a presorted key list).

	ii) With two or three arguments, the second being an array which's
	    first element is an array. The array has to have a second element
	    of the same size; the key is searched in the first and the
	    associated element of the second array that is element of second
	    argument is returned if succesful; if not, 0 is returned, or the
	    third argument, if given.

	iii) With three or four arguments, the second being an array of keys
	     (first element no array) and the third is a matching data array.
	     returns 0 or fourth argument (if given) for failure, or the
	     matching entry in the array given as third argument for success.

	Complexity : O( lg(n) ), where n is the number of keys.

Note:
	For using assoc like member_array, you need a presorted key list,
	generated by order_alist/insert_alist. Be careful not to use it for
	other arrays: It will cause undefined behaviour!

Return value:
	Undefined if another list is given in place of a presorted key list.

See also:
efun/order_alist
efun/insert_alist
LPC/alists