Scripting > UNICOM Intelligence Function Library > List functions > Rot
 
Rot
This function returns an array containing copies of items from the input list, in a rotated order. The optional Count parameter defines how many items from the input list are included in the returned list.
Syntax
Rot(List [, Count [, Policy [, Seed]]])
Parameters
List
Type: None
Array, collection, or Categorical value to operate on.
Count
Type: Long
Optional. Number of items to return. If omitted, negative, or greater than the number of input items, all items are returned.
Policy
Type: Long
Optional. Controls the way the rotation is chosen. The default is 2.
Seed
Type: Long
Optional. The state to be used for the rotation. The default is 0.
(return)
Type: None
An array consisting of a copy of the input list.
Remarks
An error occurs if List is a collection that doesn’t support the For Each...Next syntax. When List is a collection object, the return value is an array that contains copies of the objects in the collection and the input collection object is unchanged. Because the return value is an array, it does not have a Count property.
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 first item in the rotated list will be the third item, 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, because the offset is 4 (which is 9 mod 5).
The Rot function is similar to using the rot keyword in Quancept.
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 mrScriptBasic example uses a loop to call the Rot function repeatedly using a Categories collection object as the input. Note that the function returns an array that contains copies of the objects in the Categories collection and does not actually change the order of the objects in the Categories collection. Because the return value is an array, it does not have a Count property.
Dim MyDocument, MyCategories, MyElement
Dim Rotated, Counter

Set MyDocument = CreateObject("MDM.Document")

MyDocument.Open("C:\Program Files\IBM\SPSS\DataCollection\7\DDL\Data\Data Collection File\museum.mdd", , _
MDMLib.openConstants.oREAD)

Set MyCategories = MyDocument.Fields["museums"].Categories

For Each MyElement in MyCategories
Debug.Log(MyElement.Name)
Next

For Counter = 0 To 6
Debug.Log(mr.NewLine)
Set Rotated = MyCategories.Rot(, 2)
For Each MyElement in Rotated
Debug.Log(myElement.Name)
Next
Next
Here is the output:
National_Museum_of_Science
Museum_of_Design
Institute_of_Textiles_and_Fashion
Archeological_Museum
National_Art_Gallery
Northern_Gallery
Other
Not_answered

Museum_of_Design
Institute_of_Textiles_and_Fashion
Archeological_Museum
National_Art_Gallery
Northern_Gallery
Other
Not_answered
National_Museum_of_Science

Institute_of_Textiles_and_Fashion
Archeological_Museum
National_Art_Gallery
Northern_Gallery
Other
Not_answered
National_Museum_of_Science
Museum_of_Design

Archeological_Museum
National_Art_Gallery
Northern_Gallery
Other
Not_answered
National_Museum_of_Science
Museum_of_Design
Institute_of_Textiles_and_Fashion

National_Art_Gallery
Northern_Gallery
Other
Not_answered
National_Museum_of_Science
Museum_of_Design
Institute_of_Textiles_and_Fashion
Archeological_Museum

Northern_Gallery
Other
Not_answered
National_Museum_of_Science
Museum_of_Design
Institute_of_Textiles_and_Fashion
Archeological_Museum
National_Art_Gallery

Other
Not_answered
National_Museum_of_Science
Museum_of_Design
Institute_of_Textiles_and_Fashion
Archeological_Museum
National_Art_Gallery
Northern_Gallery

Not_answered
National_Museum_of_Science
Museum_of_Design
Institute_of_Textiles_and_Fashion
Archeological_Museum
National_Art_Gallery
Northern_Gallery
Other
See also
RotSequence
List functions