(rotated: 1, 'A','B','C','D')is equal to
(rotated: -2, 'A','B','C','D')is equal to
Sometimes, you may want to cycle through a number of values, without repeating any until you reach the end. For instance, you may have a rotating set of flavour-text descriptions for a thing in your story, which you'd like displayed in their entirety without the whim of a random picker. The (rotated:) macro allows you to apply this “rotation” to a sequence of data, changing their positions by a certain number without discarding any values.
Remember that, as with all macros, you can insert all the values in an existing
array using the
(set: $a to (rotated: 1, ...$a)) is a common means of
replacing an array with a rotation of itself.
Think of the number as being an addition to each position in the original sequence - if it's 1, then the value in position 1 moves to 2, the value in position 2 moves to 3, and so forth.
Incidentally… you can also use this macro to rotate a string's characters, by doing
something like this:
(string: ...(rotated: 1, ...$str))
To ensure that it's being used correctly, this macro requires three or more items - providing just two, one or none will cause an error to be presented.