====== Function ADJOIN ====== ====Syntax==== * **adjoin** //item list ''&key'' key test test-not// → //new-list// ====Arguments and Values==== * //item// - an //[[CL:Glossary:object]]//. * //list// - a //[[CL:Glossary:proper list]]//. * //test// - a //[[CL:Glossary:designator]]// for a //[[CL:Glossary:function]]// of two //[[CL:Glossary:argument|arguments]]// that returns a //[[CL:Glossary:generalized boolean]]//. * //test-not// - a //[[CL:Glossary:designator]]// for a //[[CL:Glossary:function]]// of two //[[CL:Glossary:argument|arguments]]// that returns a //[[CL:Glossary:generalized boolean]]//. * //key// - a //[[CL:Glossary:designator]]// for a //[[CL:Glossary:function]]// of one [[CL:Glossary:argument]], or **[[CL:Constant Variable:nil]]**. * //new-list// - a //[[CL:Glossary:list]]//. ====Description==== Tests whether //item// is the same as an existing element of //list//. If the //item// is not an existing element, **adjoin** adds it to //list// (as if by **[[CL:Functions:cons]]**) and returns the resulting //[[CL:Glossary:list]]//; otherwise, nothing is added and the original //list// is returned. The //test//, //test-not//, and //key// affect how it is determined whether //item// is the same as an //[[CL:Glossary:element]]// of //list//. For details, see {\secref 17.2.1}. ====Examples==== <blockquote> ([[CL:Macros:defparameter]] *slist* '()) <r>*SLIST*</r> (adjoin 'a *slist*) <r>(A) </r> *slist* <r>[[CL:Constant Variable:nil|NIL]] </r> ([[CL:Macros:setf]] *slist* (adjoin '(test-item 1) *slist*)) <r>((TEST-ITEM 1)) </r> (adjoin '(test-item 1) *slist*) <r>((TEST-ITEM 1) (TEST-ITEM 1)) </r> (adjoin '(test-item 1) *slist* :test #'[[CL:Functions:equal]]) <r>((TEST-ITEM 1)) </r> (adjoin '(new-test-item 1) *slist* :key #'[[CL:Functions:cadr]]) <r>((TEST-ITEM 1)) </r> (adjoin '(new-test-item 1) *slist*) <r>((NEW-TEST-ITEM 1) (TEST-ITEM 1)) </r> </blockquote> ====Side Effects==== None. ====Affected By==== None. ====Exceptional Situations==== Should be prepared to signal an error of type type-error if //list// is not a //[[CL:Glossary:proper list]]//. ====See Also==== **[[CL:Macros:pushnew|Macro PUSHNEW]]**, {\secref\TraversalRules} ====Example Implementation==== <blockquote> (adjoin //item// //list// :key //fn//) ≡ ([[CL:Macros:if]] ([[CL:Functions:member]] ([[CL:Functions:funcall]] //fn// //item//) //list// :key //fn//) //list// ([[CL:Functions:cons]] //item// //list//)) </blockquote> ====Notes==== The **'':test-not''** parameter is deprecated. \issue{MAPPING-DESTRUCTIVE-INTERACTION:EXPLICITLY-VAGUE} \issue{TEST-NOT-IF-NOT:FLUSH-ALL}