User Tools


Differences

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

Link to this comparison view

cl:functions:reverse [2019/09/14 05:00]
cl:functions:reverse [2019/09/20 08:00] (current)
Line 1: Line 1:
 +====== Function REVERSE, NREVERSE ======
 +
 +====Syntax====
 +  * **reverse** //​sequence//​ → //​reversed-sequence//​
 +  * **nreverse** //​sequence//​ → //​reversed-sequence//​
 +
 +====Arguments and Values====
 +  * //​sequence//​ - a //​[[CL:​Glossary:​proper sequence]]//​.
 +  * //​reversed-sequence//​ - a //​[[CL:​Glossary:​sequence]]//​.
 +
 +====Description====
 +**reverse** and **nreverse** return a new //​[[CL:​Glossary:​sequence]]//​ of the same kind as //​sequence//,​ containing the same //​[[CL:​Glossary:​element|elements]]//,​ but in reverse order.
 +
 +**reverse** and **nreverse** differ in that **reverse** always creates and returns a new //​[[CL:​Glossary:​sequence]]//,​ whereas **nreverse** might modify and return the given //​sequence//​. **reverse** never modifies the given //​sequence//​.
 +
 +For **reverse**,​ 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]]//​.
 +
 +For **nreverse**,​ if //​sequence//​ is a //​[[CL:​Glossary:​vector]]//,​ the result is a //​[[CL:​Glossary:​vector]]//​ 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:​list]]//​.
 +
 +For **nreverse**,​ //​sequence//​ might be destroyed and re-used to produce the result. The result might or might not be //​[[CL:​Glossary:​identical]]//​ to //​sequence//​.
 +
 +Specifically,​ when //​sequence//​ is a //​[[CL:​Glossary:​list]]//,​ **nreverse** is permitted to **[[CL:​Macros:​setf]]** any part, **[[CL:​Functions:​car]]** or **[[CL:​Functions:​cdr]]**,​ of any //​[[CL:​Glossary:​cons]]//​ that is part of the //​[[CL:​Glossary:​list structure]]//​ of //​sequence//​. When //​sequence//​ is a //​[[CL:​Glossary:​vector]]//,​ **nreverse** is permitted to re-order the elements of //​sequence//​ in order to produce the resulting //​[[CL:​Glossary:​vector]]//​.
 +
 +====Examples==== ​
 +<​blockquote> ​
 +([[CL:​Macros:​defparameter]] *str* "​abc"​) <​r>"​abc"​ </r>
 +(reverse *str*) <​r>"​cba"​ </r>
 +*str* <​r>"​abc"​ </r>
 +([[CL:​Macros:​defparameter]] *str* ([[CL:​Functions:​copy-seq]] *str*)) <​r>"​abc"​ </r>
 +(nreverse *str*) <​r>"​cba"​ </r>
 +*str* <​r>//​[[CL:​Glossary:​implementation-dependent]]//​ </r>
 +([[CL:​Macros:​defparameter]] *list* ([[CL:​Functions:​list]] 1 2 3)) <r>(1 2 3) </r>
 +(nreverse *list*) <r>(3 2 1) </r>
 +*list* <​r>//​[[CL:​Glossary:​implementation-dependent]]//​ </r>
 +</​blockquote>​
 +
 +====Side Effects====
 +**nreverse** might either create a new //​[[CL:​Glossary:​sequence]]//,​ modify the argument //​sequence//,​ or both.
 +
 +(**reverse** does not modify //​sequence//​.)
 +
 +====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====
 +None.
 +
 +====Notes====
 +None.
 +
 +
 +\issue{REMF-DESTRUCTION-UNSPECIFIED:​X3J13-MAR-89}