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

Documentation Area

Document Path: /doc/efun/insert_alist

Name: insert_alist - insert an entry into an assorted list

Syntax:
	mixed insert_alist( mixed key, mixed data_or_key_list..., mixed *alist)

Description:
	Insert_alist inserts an entry into an alist, or shows the place where
	this is to be done.

	When called with the last argument being an alist: The first argument
	is a key to be inserted, the second and all the following but the last
	are data to associate it with. The last has to be an array with as
	much elements as key and data arguments are given, the matching key
	and data arrays; this should be already an alist, or the return value
	will neither be an alist.

	When called with the last argument being a list of non-lists: The call
	has to be done with exactly two arguments. The first argument is a key
	to be inserted in the presorted key list (first element of an array
	that is an alist) that has to be given as second argument. Return
	value is the index where the key has to be inserted to preserve the
	structure of a presorted alist, or the index where the key has been
	found.

	Caveats: when called with certain string keys, the correct place might
	change after the call. So better don't use this mode of calling with
	a string key.

	Complexity is O( lg(n) + a*n ) Where n is the number of keys and s is
	a very small constant (for block move).

Return value:
	When called with the last argument being an alist: the enlarged assoc
	list ( array of two arrays ). If the key is already in the list, the
	data is simply replaced in the returned list.

	When called with the last argument being a list of non-lists: the
	return value is an int.

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