%mathpiper,def="Assoc"

/* Assoc : given an assoc list like for example l:={{a,2},{b,3}},
   Assoc(b,l) will return {b,3}. if the key is not in the list,
   it will return the atom Empty.
*/

Function("Assoc",{key,list})  Builtin'Assoc(key,list);

%/mathpiper



%mathpiper_docs,name="Assoc",categories="User Functions;Lists (Operations)"
*CMD Assoc --- return element stored in association list
*STD
*CALL
	Assoc(key, alist)

*PARMS

{key} -- string, key under which element is stored

{alist} -- association list to examine

*DESC

The association list "alist" is searched for an entry stored with
index "key". If such an entry is found, it is returned. Otherwise
the atom {Empty} is returned.

Association lists are represented as a list of two-entry lists. The
first element in the two-entry list is the key, the second element is
the value stored under this key.

The call {Assoc(key, alist)} can (probably more
intuitively) be accessed as {alist[key]}.

*E.G.

In> writer := {};
Result: {};
In> writer["Iliad"] := "Homer";
Result: True;
In> writer["Henry IV"] := "Shakespeare";
Result: True;
In> writer["Ulysses"] := "James Joyce";
Result: True;
In> Assoc("Henry IV", writer);
Result: {"Henry IV","Shakespeare"};
In> Assoc("War and Peace", writer);
Result: Empty;

*SEE AssocIndices, [], :=, AssocDelete, AssocValues
%/mathpiper_docs