User Tools


Differences

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

Link to this comparison view

cl:macros:pushnew [2019/08/16 12:00]
cl:macros:pushnew [2019/08/23 05:00] (current)
Line 1: Line 1:
 +====== Macro PUSHNEW ======
  
 +====Syntax====
 +  * **pushnew** //item place ''&​key''​ key test test-not// → //​new-place-value//​
 +
 +====Arguments and Values==== ​
 +  * //​item//​---an //​[[CL:​Glossary:​object]]//​.  ​
 +  * //​place//​---a //​[[CL:​Glossary:​place]]//,​ the //​[[CL:​Glossary:​value]]//​ of which is a //​[[CL:​Glossary:​proper list]]//​. ​
 +  * //​test//​---a //​[[CL:​Glossary:​designator]]//​ for a //​[[CL:​Glossary:​function]]//​ of two //​[[CL:​Glossary:​arguments]]//​ that returns a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​test-not//​---a //​[[CL:​Glossary:​designator]]//​ for   a //​[[CL:​Glossary:​function]]//​ of two //​[[CL:​Glossary:​arguments]]// ​ that returns a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //key//---a //​[[CL:​Glossary:​designator]]//​ for a //​[[CL:​Glossary:​function]]//​ of one argument, ​ or **[[CL:​Constant Variable:​nil]]**.
 +  * //​new-place-value//​---a //​[[CL:​Glossary:​list]]//​ (the new //​[[CL:​Glossary:​value]]//​ of //place//).
 +
 +====Description====
 +**pushnew** tests whether ​ //item// is the same as any existing element of the //​[[CL:​Glossary:​list]]//​ stored in //​place//​. ​ If //item// is not, it is prepended to the //​[[CL:​Glossary:​list]]//,​ and the new //​[[CL:​Glossary:​list]]//​ is stored in //place//.
 +
 +**pushnew** returns the new //​[[CL:​Glossary:​list]]//​ that is stored in //place//.
 +
 +Whether or not //item// is already a member of the //​[[CL:​Glossary:​list]]//​ that is in //place// is determined by comparisons using **'':​test''​** or **'':​test-not''​**. The first argument to the **'':​test''​** or **'':​test-not''​** function is //item//; the second argument is an element of the //​[[CL:​Glossary:​list]]//​ in //place// as returned by the **'':​key''​** function (if supplied).
 +
 +If **'':​key''​** is supplied, it is used to extract the part to be tested from both //item// and the //​[[CL:​Glossary:​list]]//​ element, as for **[[CL:​Functions:​adjoin]]**.
 +
 +The argument to the **'':​key''​** function ​ is an element of the //​[[CL:​Glossary:​list]]//​ stored in  //place//. The **'':​key''​** function typically returns part part of the element of the //​[[CL:​Glossary:​list]]//​. If **'':​key''​** is not supplied or **[[CL:​Constant Variable:​nil]]**,​ the //​[[CL:​Glossary:​list]]// ​ element is used.
 +
 +For information about the //​[[CL:​Glossary:​evaluation]]//​ of //​[[CL:​Glossary:​subforms]]//​ of //place//, \seesection\GenRefSubFormEval.
 +
 +It is //​[[CL:​Glossary:​implementation-dependent]]//​ whether or not **pushnew** ​ actually executes the storing form for its //place// in the situation where the //item// is already a member of the //​[[CL:​Glossary:​list]]//​ held by //place//.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​defparameter]] *x* '(a (b c) d)) <​r>​*X*</​r>​
 +(pushnew 5 ([[CL:​Functions:​cadr]] *x*)) <r>(5 B C)   </​r>​
 +*x* <r>(A (5 B C) D)</​r>​
 +(pushnew 'b ([[CL:​Functions:​cadr]] *x*)) <r>(5 B C)  </r>
 +*x* <r>(A (5 B C) D)</​r>​
 +([[CL:​Macros:​defparameter]] *list* '((1) (1 2) (1 2 3))) <​r>​*LIST*</​r>​
 +(pushnew '(2) *list*) <​r>​((2) (1) (1 2) (1 2 3))</​r>​
 +(pushnew '(1) *list*) <​r>​((1) (2) (1) (1 2) (1 2 3))</​r>​
 +(pushnew '(1) *list* :test #'​[[CL:​Functions:​equal]]) <​r>​((1) (2) (1) (1 2) (1 2 3))</​r>​
 +(pushnew '(1) *list* :key #'​[[CL:​Functions:​car]]) <​r>​((1) (2) (1) (1 2) (1 2 3)) </r>
 +</​blockquote>​
 +
 +====Side Effects====
 +The contents of //place// may be modified.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +**[[CL:​Macros:​push]]**,​ **[[CL:​Functions:​adjoin]]**,​ {\secref\GeneralizedReference}
 +
 +====Example Implementation====
 +To be done.
 +
 +The effect of
 +
 +<​blockquote>​
 +(pushnew //item// //place// :test //p//)
 +</​blockquote>​
 +
 +is roughly equivalent to
 +<​blockquote>​
 +
 +([[CL:​Macros:​setf]] //place// ([[CL:​Functions:​adjoin]] //item// //place// :test //p//))
 +</​blockquote>​
 +
 +except that the //​[[CL:​Glossary:​subforms]]//​ of ''​place''​ are evaluated only once,  and ''​item''​ is evaluated before ''​place''​.
 +
 +====Notes====
 +None.
 +
 +\issue{PUSH-EVALUATION-ORDER:​FIRST-ITEM}
 +\issue{PUSHNEW-STORE-REQUIRED:​UNSPECIFIED}