User Tools


Differences

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

Link to this comparison view

cl:functions:replace [2019/09/14 05:00]
cl:functions:replace [2019/09/22 06:00] (current)
Line 1: Line 1:
 +====== Function REPLACE ======
 +
 +====Syntax====
 +  * **replace** //​sequence-1//​ //​sequence-2//​ ''&​key''​ //start1// //end1// //start2// //end2// → //​sequence-1//​
 +
 +====Arguments and Values====
 +  * //​sequence-1//​ - a //​[[CL:​Glossary:​sequence]]//​.
 +  * //​sequence-2//​ - a //​[[CL:​Glossary:​sequence]]//​.
 +  * //start1//, //end1// - //​[[CL:​Glossary:​bounding index designator|bounding index designators]]//​ of //​sequence-1//​. The defaults for //start1// and //end1// are ''​0''​ and **[[CL:​Constant Variables:​nil]]**,​ respectively.
 +  * //start2//, //end2// - //​[[CL:​Glossary:​bounding index designator|bounding index designators]]//​ of //​sequence-2//​. The defaults for //start2// and //end2// are ''​0''​ and **[[CL:​Constant Variables:​nil]]**,​ respectively.
 +
 +====Description====
 +Destructively modifies //​sequence-1//​ by replacing the //​[[CL:​Glossary:​element|elements]]//​ of //​subsequence-1//​ //​[[CL:​Glossary:​bounded]]//​ by //start1// and //end1// with the //​[[CL:​Glossary:​element|elements]]//​ of //​subsequence-2//​ //​[[CL:​Glossary:​bounded]]//​ by //start2// and //end2//.
 +
 +//​Sequence-1//​ is destructively modified by copying successive //​[[CL:​Glossary:​element|elements]]//​ into it from //​sequence-2//​. //​[[CL:​Glossary:​element|elements]]//​ of the subsequence of //​sequence-2//​ //​[[CL:​Glossary:​bounded]]//​ by //start2// and //end2// are copied into the subsequence of //​sequence-1//​ //​[[CL:​Glossary:​bounded]]//​ by //start1// and //end1//. If these subsequences are not of the same length, then the shorter length determines how many //​[[CL:​Glossary:​element|elements]]//​ are copied; the extra //​[[CL:​Glossary:​element|elements]]//​ near the end of the longer subsequence are not involved in the operation. The number of elements copied can be expressed as:
 +
 +<​blockquote>​
 +([[CL:​Functions:​min]] ([[CL:​Functions:​math-subtract|-]] //end1// //start1//) ([[CL:​Functions:​math-subtract|-]] //end2// //​start2//​))
 +</​blockquote>​
 +
 +If //​sequence-1//​ and //​sequence-2//​ are the //​[[CL:​Glossary:​same]]//​ //​[[CL:​Glossary:​object]]//​ and the region being modified overlaps the region being copied from, then it is as if the entire source region were copied to another place and only then copied back into the target region. However, if //​sequence-1//​ and //​sequence-2//​ are not the same, but the region being modified overlaps the region being copied from (perhaps because of shared list structure or displaced //​[[CL:​Glossary:​array|arrays]]//​),​ then after the **replace** operation the subsequence of //​sequence-1//​ being modified will have unpredictable contents. It is an error if the elements of //​sequence-2//​ are not of a //​[[CL:​Glossary:​type]]//​ that can be stored into //​sequence-1//​.
 +
 +====Examples==== ​
 +<​blockquote> ​
 +(replace "​abcdefghij"​ "​0123456789"​ :start1 4 :end1 7 :start2 4) → "​abcd456hij" ​
 +([[CL:​Macros:​defparameter]] *lst* "​012345678"​) → "​012345678" ​
 +(replace *lst* *lst* :start1 2 :start2 0) → "​010123456" ​
 +*lst* → "​010123456" ​
 +</​blockquote>​
 +
 +====Side Effects====
 +The //​sequence-1//​ is modified.
 +
 +====Affected By====
 +None.
 +
 +====Exceptional Situations====
 +None.
 +
 +====See Also====
 +  * **[[CL:​Functions:​fill|Function FILL]]**
 +
 +====Notes====
 +None.
 +
 +
 +\issue{SUBSEQ-OUT-OF-BOUNDS} \issue{RANGE-OF-START-AND-END-PARAMETERS:​INTEGER-AND-INTEGER-NIL}