%mathpiper,def="AssocDelete"

/// Delete an element of an associative list.
LocalSymbols(hash, key, element, hash'expr)
[

/// AssocDelete(hash,{"key", value})
10 # AssocDelete(hash_IsList, element_IsList) <--
[
	Local(index);
	index := Find(hash, element);
	If(
		index > 0,
		DestructiveDelete(hash, index)
	);
	index>0;	// return False if nothing found

];


/// AssocDelete(hash, "key")
20 # AssocDelete(hash_IsList, key_IsString) <--
[
	AssocDelete(hash, Builtin'Assoc(key, hash));
];

30 # AssocDelete(hash_IsList, Empty) <-- False;

//HoldArgument("AssocDelete", hash);
//UnFence("AssocDelete", 1);
//UnFence("AssocDelete", 2);

];	// LocalSymbols(hash, ...)

%/mathpiper



%mathpiper_docs,name="AssocDelete",categories="User Functions;Lists (Operations)"
*CMD AssocDelete --- delete an entry in an association list
*STD
*CALL
	AssocDelete(alist, "key")
	AssocDelete(alist, {key, value})

*PARMS

{alist} -- association list

{"key"} -- string, association key

{value} -- value of the key to be deleted

*DESC

The key {"key"} in the association list {alist} is deleted. (The list itself is modified.) If the key was found and successfully deleted, returns {True}, otherwise if the given key was not found, the function returns {False}.

The second, longer form of the function deletes the entry that has both the
specified key and the specified value. It can be used for two purposes:
*	1. to make sure that we are deleting the right value;
*	2. if several values are stored on the same key, to delete the specified entry (see the last example).

At most one entry is deleted.

*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> AssocDelete(writer, "Henry IV")
Result: True;
In> AssocDelete(writer, "Henry XII")
Result: False;
In> writer
Result: {{"Ulysses","James Joyce"},
	  {"Iliad","Homer"}};
In> DestructiveAppend(writer,
	  {"Ulysses", "Dublin"});
Result: {{"Iliad","Homer"},{"Ulysses","James Joyce"},
	  {"Ulysses","Dublin"}};
In> writer["Ulysses"];
Result: "James Joyce";
In> AssocDelete(writer,{"Ulysses","James Joyce"});
Result: True;
In> writer
Result: {{"Iliad","Homer"},{"Ulysses","Dublin"}};


*SEE Assoc, AssocIndices, AssocValues
%/mathpiper_docs