User Tools


Differences

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

Link to this comparison view

cl:functions:position [2019/09/14 05:00]
cl:functions:position [2019/09/19 02:00] (current)
Line 1: Line 1:
 +====== Function POSITION, POSITION-IF,​ POSITION-IF-NOT ======
 +
 +====Syntax====
 +  * **position** //item// //​sequence//​ ''&​key''​ //​from-end//​ //test// //​test-not//​ //start// //end// //key// → //​position//​
 +  * **position-if** //​predicate//​ //​sequence//​ ''&​key''​ //​from-end//​ //start// //end// //key// → //​position// ​
 +  * **position-if-not** //​predicate//​ //​sequence//​ ''&​key''​ //​from-end//​ //start// //end// //key// → //​position// ​
 +
 +====Arguments and Values====
 +  * //item// - an //​[[CL:​Glossary:​object]]//​.
 +  * //​sequence//​ - a //​[[CL:​Glossary:​proper sequence]]//​.
 +  * //​predicate//​ - a //​[[CL:​Glossary:​designator]]//​ for a //​[[CL:​Glossary:​function]]//​ of one argument that returns a //​[[CL:​Glossary:​generalized boolean]]//​.
 +  * //​from-end//​ - a //​[[CL:​Glossary:​generalized boolean]]//​. The default is //​[[CL:​Glossary:​false]]//​.
 +  * //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]]//​.
 +  * //start//, //end// - //​[[CL:​Glossary:​bounding index designator|bounding index designators]]//​ of //​sequence//​. The defaults for //start// and //end// are ''​0''​ and **[[CL:​Constant Variables:​nil]]**,​ respectively.
 +  * //key// - a //​[[CL:​Glossary:​designator]]//​ for a //​[[CL:​Glossary:​function]]//​ of one argument, or **[[CL:​Constant Variables:​nil]]**.
 +  * //​position//​ - a //​[[CL:​Glossary:​bounding index]]// of //​sequence//,​ or **[[CL:​Constant Variables:​nil]]**.
 +
 +====Description====
 +**position**,​ **position-if**,​ and **position-if-not** each search //​sequence//​ for an //​[[CL:​Glossary:​element]]//​ that //​[[CL:​Glossary:​satisfy the test|satisfies the test]]//.
 +
 +The //​position//​ returned is the index within //​sequence//​ of the leftmost (if //​from-end//​ is //​[[CL:​Glossary:​true]]//​) or of the rightmost (if //​from-end//​ is //​[[CL:​Glossary:​false]]//​) //​[[CL:​Glossary:​element]]//​ that //​[[CL:​Glossary:​satisfy the test|satisfies the test]]//; otherwise **[[CL:​Constant Variables:​nil]]** is returned.
 +
 +The index returned is relative to the left-hand end of the entire //​sequence//,​ regardless of the value of //​[[CL:​Glossary:​start]]//,​ //​[[CL:​Glossary:​end]]//,​ or //​[[CL:​Glossary:​from-end]]//​.
 +
 +====Examples====
 +<​blockquote>​
 +(position #\a "​baobab"​ :from-end [[CL:​Constant Variables:​t]]) <r>4 </r>
 +(position-if #'​[[CL:​Functions:​oddp]] '((1) (2) (3) (4)) :start 1 :key #'​[[CL:​Functions:​car]]) <r>2 </r>
 +(position 595 '()) <​r>​[[CL:​Constant Variables:​NIL]] </r>
 +(position-if-not #'​[[CL:​Functions:​integerp]] '(1 2 3 4 5.0)) <r>4 </r>
 +</​blockquote>​
 +
 +====Side Effects====
 +None.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +Should be prepared to signal an error of type type-error if //​sequence//​ is not a //​[[CL:​Glossary:​proper sequence]]//​.
 +
 +====See Also====
 +  * **[[CL:​Functions:​find|Function FIND]]**
 +  * {\secref\TraversalRules}
 +
 +====Notes====
 +The **'':​test-not''​** //​[[CL:​Glossary:​argument]]//​ is deprecated.
 +
 +The //​[[CL:​Glossary:​function]]//​ **position-if-not** is deprecated.
 +
 +\issue{TEST-NOT-IF-NOT:​FLUSH-ALL} \issue{SUBSEQ-OUT-OF-BOUNDS} \issue{RANGE-OF-START-AND-END-PARAMETERS:​INTEGER-AND-INTEGER-NIL} \issue{MAPPING-DESTRUCTIVE-INTERACTION:​EXPLICITLY-VAGUE} \issue{TEST-NOT-IF-NOT:​FLUSH-ALL}