- (xsubstring s from [to start end]) -> stringprocedure
This is the "extended substring" procedure that implements replicated copying of a substring of some string.
S is a string; START and END are optional arguments that demarcate a substring of S, defaulting to 0 and the length of S (i.e., the whole string). Replicate this substring up and down index space, in both the positive and negative directions. For example, if S = "abcdefg", START=3, and 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 ...
xsubstring returns the substring of this string beginning at index FROM, and ending at TO (which defaults to FROM+(END-START)).
You 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"
- 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 S. They are in terms of the replicated index space of the substring defined by S, START, and END.
It is an error if START=END -- although this is allowed by special dispensation when FROM=TO.