User Tools


Differences

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

Link to this comparison view

cl:functions:subseq [2019/11/11 05:00]
cl:functions:subseq [2019/11/13 17:00] (current)
Line 1: Line 1:
 +====== Accessor SUBSEQ ======
 +
 +====Syntax====
 +  * **subseq** //​sequence//​ //start// ''&​optional''​ //end// → //​subsequence// ​
 +  (**setf** (**subseq** //​sequence//​ //start// ''&​optional''​ //end//) //​new-subsequence//​)
 +
 +====Arguments and Values====
 +//​sequence//​ - a //​[[CL:​Glossary:​proper sequence]]//​.
 +//start//, //end// - //​[[CL:​Glossary:​bounding index designator|bounding index designators]]//​ of //​sequence//​. The default for //end// is **[[CL:​Constant Variables:​nil]]**.
 +//​subsequence//​ - a //​[[CL:​Glossary:​proper sequence]]//​.
 +//​new-subsequence//​ - a //​[[CL:​Glossary:​proper sequence]]//​.
 +
 +====Description====
 +**subseq** creates a //​[[CL:​Glossary:​sequence]]//​ that is a copy of the subsequence of //​sequence//​ //bounded// by //start// and //end//.
 +
 +//start// specifies an offset into the original //​sequence//​ and marks the beginning position of the subsequence. //end// marks the position following the last element of the subsequence.
 +
 +**subseq** always allocates a new //​[[CL:​Glossary:​sequence]]//​ for a result; it never shares storage with an old //​[[CL:​Glossary:​sequence]]//​. The result subsequence is always of the same //​[[CL:​Glossary:​type]]//​ as //​sequence//​.
 +
 +If //​sequence//​ is a //​[[CL:​Glossary:​vector]]//,​ the result is a //​[[CL:​Glossary:​fresh]]//​ //​[[CL:​Glossary:​simple array]]// of //​[[CL:​Glossary:​rank]]//​ one that has the same //​[[CL:​Glossary:​actual array element type]]// as //​sequence//​. If //​sequence//​ is a //​[[CL:​Glossary:​list]]//,​ the result is a //​[[CL:​Glossary:​fresh]]//​ //​[[CL:​Glossary:​list]]//​.
 +
 +**[[CL:​Macros:​setf]]** may be used with **subseq** to destructively replace //​[[CL:​Glossary:​element|elements]]//​ of a subsequence with //​[[CL:​Glossary:​element|elements]]//​ taken from a //​[[CL:​Glossary:​sequence]]//​ of new values. If the subsequence and the new sequence are not of equal length, the shorter length determines the number of elements that are replaced. The remaining //​[[CL:​Glossary:​element|elements]]//​ at the end of the longer sequence are not modified in the operation.
 +
 +====Examples====
 +<​blockquote>​
 +([[CL:​Macros:​defparameter]] *str* "​012345"​) <​r>"​012345"​ </r>
 +(subseq *str* 2) <​r>"​2345"​ </r>
 +(subseq *str* 3 5) <​r>"​34"​ </r>
 +([[CL:​Macros:​setf]] (subseq *str* 4) "​abc"​) <​r>"​abc"​ </r>
 +*str* <​r>"​0123ab"​ </r>
 +([[CL:​Macros:​setf]] (subseq *str* 0 2) "​A"​) <​r>"​A"​ </r>
 +*str* <​r>"​A123ab"​ </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]]//​. Should be prepared to signal an error of type type-error if //​new-subsequence//​ is not a //​[[CL:​Glossary:​proper sequence]]//​.
 +
 +====See Also====
 +  * **[[CL:​Functions:​replace|Function REPLACE]]**
 +
 +====Notes====
 +None.
 +
 +\issue{SUBSEQ-OUT-OF-BOUNDS} \issue{RANGE-OF-START-AND-END-PARAMETERS:​INTEGER-AND-INTEGER-NIL}