User Tools


Differences

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

Link to this comparison view

cl:functions:subsetp [2019/09/14 05:00]
cl:functions:subsetp [2019/09/20 16:00] (current)
Line 1: Line 1:
 +====== Function SUBSETP ======
  
 +====Syntax====
 +  * **subsetp** //list-1 list-2 ''&​key''​ key test test-not// → //​generalized-boolean//​
 +
 +====Arguments and Values====
 +  * //list-1// - a //​[[CL:​Glossary:​proper list]]//.
 +  * //list-2// - 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]]**.
 +  * //​generalized-boolean//​ - a //​[[CL:​Glossary:​generalized boolean]]//​.
 +
 +====Description====
 +**subsetp** returns //​[[CL:​Glossary:​true]]//​ if every element of //list-1// //matches// some element of //list-2//, and //​[[CL:​Glossary:​false]]//​ otherwise.
 +
 +Whether a list element is the same as another list element is determined by the functions specified by the keyword arguments. ​  The first argument to the **'':​test''​** or **'':​test-not''​** ​ function is typically part of an element of //list-1// extracted by the **'':​key''​** function; the second argument is  typically part of  an element of //list-2// extracted by the **'':​key''​** function.
 +
 +The argument to the **'':​key''​** function is an element of either //list-1// or //list-2//; the return value is part of the element of the supplied list element. If **'':​key''​** is not supplied or **[[CL:​Constant Variable:​nil]]**, ​ the //list-1// or //list-2// element itself is supplied to the **'':​test''​** or **'':​test-not''​** ​ function.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​defparameter]] //​*cosmos*//​ '(1 "​a"​ (1 2))) <​r>​*COSMOS*</​r>​
 +(subsetp '(1) //​*cosmos*//​) <​r>//​[[CL:​Glossary:​true]]//</​r>​
 +(subsetp '((1 2)) //​*cosmos*//​) → //​[[CL:​Glossary:​false]]//​
 +(subsetp '((1 2)) //​*cosmos*//​ :test #'​[[CL:​Functions:​equal]]) <​r>//​[[CL:​Glossary:​true]]//</​r>​
 +(subsetp '(1 "​A"​) //​*cosmos*//​ :test #'​[[CL:​Functions:​equalp]]) <​r>//​[[CL:​Glossary:​true]]//</​r>​
 +(subsetp '((1) (2)) '((1) (2))) <​r>//​[[CL:​Glossary:​false]]//</​r>​
 +(subsetp '((1) (2)) '((1) (2)) :key #'​[[CL:​Functions:​car]]) <​r>//​[[CL:​Glossary:​true]]//</​r>​
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +Should be prepared to signal an error of type type-error if //list-1// and //list-2// are not //​[[CL:​Glossary:​proper list|proper lists]]//.
 +
 +====See Also====
 +{\secref\TraversalRules}
 +
 +====Example Implementation====
 +To be done.
 +
 +====Notes====
 +The **'':​test-not''​** parameter is deprecated.
 +
 +\issue{MAPPING-DESTRUCTIVE-INTERACTION:​EXPLICITLY-VAGUE}
 +\issue{TEST-NOT-IF-NOT:​FLUSH-ALL}