User Tools


Differences

This shows you the differences between two versions of the page.

Link to this comparison view

cl:functions:adjoin [2019/07/14 17:00]
cl:functions:adjoin [2019/07/17 21:00] (current)
Line 1: Line 1:
 +====== 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}