This shows you the differences between two versions of the page.
— |
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:)]] |