|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > Assoc. Array Operation > ASA. - Associative Array Operations |
SPR Script Language
ASA.First
Returns the handle to the first node in an associative array.
Intention
The ASA.First command helps you start exploring an associative array in SPR. You give it the array’s handle (like $$TRE), and it finds the very first key-value pair—called a node—and gives you a special number (a node handle) in $$NODE. This node handle lets you peek at that first pair’s key and value with commands like ASA.GetKey and ASA.GetVal. It’s your starting point for walking through the array, one node at a time, using ASA.Next to move forward.
Think of a phonebook array—ASA.First takes you to the first name, like "Alice" → "123-4567". You can then check that entry or move to the next one. Or in a robot script with settings like "Temp" → "23.5", it starts you at the first setting. It’s a fast way to begin looping through your data, perfect for tasks like listing all contacts or checking every sensor reading.
Illustration
🏁 Start Here: In an array with handle $$TRE, ASA.First points you to the first pair, like "Name" → "Alice".
🔗 Node Handle: $$NODE gets a number you can use to dig into that first entry!
Syntax
ASA.First|$$TRE[|$$NOD]
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is the handle of the array you’re looking at. It’s a 5-character variable (like $$TRE or $$ARR) from ASA.New. The command uses this to find the first node.
P2 - $$NOD - (Optional, Variable)
This is where the node handle goes. It’s an optional 5-character variable (like $$NOD). SPR puts a number here—a non-zero value if there’s a first node, or zero if the array is empty. Use this with ASA.GetKey or ASA.GetVal to see the details.
Examples
'***********************************
' ASA.First - Sample 1: Get First Node in a String Array
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|Alice|123-4567
ASA.Set|$$TRE|Bob|987-6543
ASA.First|$$TRE|$$NOD
ASA.GetKey|$$NOD|$$KEY
MBX.First key is $$KEY (should be Alice)
MBX.Ready
'
'***********************************
' ASA.First - Sample 2: Check First in a Quad Array
'***********************************
ASA.New|$$TRE|i
ASA.Set|$$TRE|Red|50
ASA.Set|$$TRE|Blue|75
ASA.First|$$TRE|$$NOD
ASA.GetVal|$$NOD|$$VAL
PRT.First value is $$VAL (should be 50)
MBX.Ready
'
'***********************************
' ASA.First - Sample 3: First in an Empty Extended FP Array
'***********************************
ASA.New|$$TRE|f
ASA.First|$$TRE|$$NOD
PRT.First node handle in empty array: $$NOD (should be 0)
MBX.Ready
'
Remarks
- $$TRE must be valid—use ASA.Validate to check first.
- If the array is empty, $$NODE gets 0—nothing to find!
- The “first” node depends on how SPR sorts the array internally—usually alphabetical by key, but don’t count on a specific order.
- Use with ASA.Next to loop through all nodes, or pair with ASA.Last to see both ends.
Limitations
- $$TRE must be 5 characters—wrong lengths might mess it up.
- If $$TRE isn’t valid, $$NODE might get junk—no error shown.
- Only gives the node handle—you need other commands to see the key or value.
See also:
• ASA.New
• ASA.Next