RotSequence
This function returns an array containing values selected from a given series of integers in a “rotated” order.
Syntax
RotSequence(<start>, <end> [, <step> [, <count>[, <policy>[, <seed>]]]])
Parameters
<start>
Type: Long
The first possible value.
<end>
The last possible value.
Long
<step>
(Optional.) The increment between consecutive possible values. The default value is 1.
Long
<count>
Type: Long
(Optional.) The number of items to return. If omitted, negative, or greater than the number of possible values, all items are returned.
<policy>
(Optional.) Controls the way the rotation is performed. The default value is 2.
Long
<seed>
Type: Long
(Optional.) The state to be used for the rotation. The default value is the value acquired from the
GetRotationSeed function.
(return)
Type: None
An array containing a rotated selection from the set of possible numbers.
Notes
The RotSequence function returns an array containing numbers from the sequence Start, Start + Step, Start + Step * 2, ... , Start + Step * N (where N is the maximum integer such that the sequence doesn’t pass End) in a “rotated” order. Step can be positive or negative. If Step is 0, Count copies of Start are returned, unless Count is omitted or negative, in which case an empty array is returned. If Step is positive and Start > End, or if Step is negative and Start < End, an empty array is returned.
Note that the Start, End, and Step arguments define the potential set of numbers to return (for example, a setting of (1, 10, 2) produces the set {1, 3, 5, 7, 9}, while (10, 1, -2) produces {10, 8, 6, 4, 2}). Then the Policy and Seed parameters and the rotation state determine in which order those numbers are returned. Finally, the Count argument controls how much of that ordered set is returned.
This function uses the rotation state stored by the mrScriptBasic engine or Evaluate component and passed as a hidden parameter. However, when both Policy and Seed are nonzero, the rotation state is set to <seed> before the Policy is applied. The resulting rotation state determines which item from the original list is to appear first in the rotated list.
The rotation state is used to calculate the number of items by which the list should be “rotated”. This is called the offset and is calculated as follows:
Rotation_state mod Number_of_items_in_list
For example, if the rotation state is 9 and there are 7 items in the list, the rotated list will start with the third item from the original list, because the offset is 2 (which is 9 mod 7). However, if there were 5 items in the list, the rotated list would start with the fifth item from the original list, because the offset is 4 (which is 9 mod 5).
Possible values for Policy
0
No rotation and the rotation state is set to 0.
1
The rotation state is used without changing it.
2
The rotation state is incremented by one and used.
3
Use the starting point of the random number generator and update both the rotation state and the random number generator starting point.
Example
This example shows using RotSequence in an SQL query.
SELECT Respondent.Serial,
RotSequence(1, 5, 1, 5, 2) AS RotSequence
FROM vdata
Here are the results for the first seven respondents:
Respondent.Serial RotSequence
----------------- -------------
1 {2,3,4,5,1}
2 {3,4,5,1,2}
3 {4,5,1,2,3}
4 {5,1,2,3,4}
5 {1,2,3,4,5}
6 {2,3,4,5,1}
7 {3,4,5,1,2}
In this example, the <count> parameter is set to the same value as the number of input values. This is designed to make it clear how the function works. In a real example, you might return fewer values than are input. For example:
SELECT Respondent.Serial,
RotSequence(1, 14, 2, 5, 2) AS RotSequence
FROM vdata
Here are the results for the first seven respondents:
Respondent.Serial RotSequence
----------------- -------------
1 {3,5,7,9,11}
2 {5,7,9,11,13}
3 {7,9,11,13,1}
4 {9,11,13,1,3}
5 {11,13,1,3,5}
6 {13,1,3,5,7}
7 {1,3,5,7,9}
See also