2.8.3.13 Replicate and rotate

Function: xsubstring str from

Function: xsubstring str from to

Function: xsubstring str from to start

Function: xsubstring str from to start end

This is the “extended substring” procedure that implements replicated copying of a substring of some string.

str is a string; start and end are optional arguments that demarcate a substring of str, defaulting to 0 and the length of str (i.e. the whole string).

This function replicates the selected substring “up and down” index space, in both the positive and negative directions. For example, if:

str   = "abcdefg"
start = 3
end   = 6

then we have the conceptual bidirectionally–infinite string:

...  d  e  f  d  e  f  d  e  f  d  e  f  d  e  f  d  e  f  d  ...
... -9 -8 -7 -6 -5 -4 -3 -2 -1  0 +1 +2 +3 +4 +5 +6 +7 +8 +9  ...

that is defg repeated in both directions.

xsubstring returns the substring of this string beginning at index from, and ending at to which defaults to from + (end - start).

We can use xsubstring to perform a variety of tasks:

• To rotate a string left:

  (xsubstring "abcdef" 2)         ⇒ "cdefab"
  

• To rotate a string right:

  (xsubstring "abcdef" -2)        ⇒ "efabcd"
  

• To replicate a string:

  (xsubstring "abc" 0 7)          ⇒ "abcabca"
  

Note that:

• The from/to indices give a half–open range; the characters from index from up to, but not including, index to.
• The from/to indices are not in terms of the index space for string str. They are in terms of the replicated index space of the substring defined by str, start, and end.

It is an error if start = end; although this is allowed by special dispensation when from = to.

Function: string-xcopy! dst.str dst.start src.str src.from

Function: string-xcopy! dst.str dst.start src.str src.from src.to

Function: string-xcopy! dst.str dst.start src.str src.from src.to src.start

Function: string-xcopy! dst.str dst.start src.str src.from src.to src.start src.end

Exactly the same as xsubstring, but the extracted text is written into the string dst.str starting at index dst.start. This operation is not defined if (eq? dst.str src.str) or these two arguments share storage; we cannot copy a string on top of itself.