User Tools

Site Tools


harlowe:rotated

Differences

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

Link to this comparison view

harlowe:rotated [2017/10/09 20:39] (current)
Line 1: Line 1:
 +**(rotated: // [[harlowe:​Number|Number]],​ <span class=parameter_optional>​[</​span>​...Any<​span class=parameter_optional>​]</​span>//​) -> //​[[harlowe:​Array|array]]//​**
  
 +Similar to the [[harlowe:​a|(a:​)]] macro, but it also takes a [[harlowe:​number|number]] at the start, and moves
 +each item forward by that number, wrapping back to the start
 +if they pass the end of the [[harlowe:​array|array]].
 +
 +=== Example usage: ===
 +
 +  * ''​%%(rotated:​ 1, '​A','​B','​C','​D'​)%%''​ is equal to ''​%%(a:​ '​D','​A','​B','​C'​)%%''​.
 +  * ''​%%(rotated:​ -2, '​A','​B','​C','​D'​)%%''​ is equal to ''​%%(a:​ '​C','​D','​A','​B'​)%%''​.
 +
 +=== Rationale: ===
 +
 +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 ''​%%...%%''​ syntax: ''​%%(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 [[harlowe:​string|string]]'​s characters, by doing
 +something like this: ''​%%(string:​ ...(rotated:​ 1, ...$str))%%''​
 +
 +=== Details: ===
 +
 +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.
 +
 +=== See also: ===
 +
 +[[harlowe:​sorted|(sorted:​)]]
harlowe/rotated.txt ยท Last modified: 2017/10/09 20:39 (external edit)