|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > Assoc. Array Management > ASA. - Associative Array Operations |
SPR Script Language
ASA.End
Destroys an associative array, freeing its memory and invalidating its handle.
Intention
The ASA.End command cleans up an associative array you’ve made with ASA.New. It takes the handle (stored in a variable like $$TRE) and tells SPR to erase the array from memory. This is important because if you don’t clean up, your script might use up too much memory over time—like leaving trash around after a party! Once ASA.End runs, the handle becomes invalid, so you can’t use it anymore with commands like ASA.Set or ASA.Get. You can use this command when you’re done with a phonebook, a list of robot settings, or any key-value data you don’t need anymore.
Think of it like this: if you made a phonebook with ASA.New and added names and numbers, ASA.End throws that phonebook away when you’re finished. Or if your robot script stored sensor readings (like "Temp" → "23.5"), this command clears it out after you’ve used the data. It’s quick, keeps your script tidy, and makes sure SPR doesn’t slow down from old arrays hanging around.
Illustration
🗑️ Clean Up: An array with handle $$TRE holding pairs like "Name" → "Alice" gets wiped out.
🚫 Handle Done: After ASA.End, $$TRE can’t be used anymore—it’s like the array never existed!
Syntax
ASA.End|$$TRE[|$$RES]
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is the handle of the associative array you want to destroy. It must be a 5-character variable (like $$TRE or $$ARR) that was set by ASA.New. After this command runs, the array is gone, and $$TRE becomes invalid.
P2 - $$RES - (Optional, Variable, 5 characters max)
This variable can store the result of the operation. It’s optional, but if you use it (e.g., $$RES), SPR puts a number there: usually 0 if it worked, or something else if there was a problem. You don’t have to use this unless you want to check if the cleanup went okay.
Examples
'***********************************
' ASA.End - Sample 1: Destroy a String Array
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|Name|Alice
ASA.End|$$TRE
MBX.Text|Array with handle $$TRE is destroyed
MBX.Ready
'
'***********************************
' ASA.End - Sample 2: Destroy a Quad Array with Result
'***********************************
ASA.New|$$TRE|i
ASA.Set|$$TRE|Count|100
ASA.End|$$TRE|$$RES
PRT.Array destroyed, result: $$RES
MBX.Ready
'
'***********************************
' ASA.End - Sample 3: Destroy an Extended FP Array
'***********************************
ASA.New|$$TRE|f
ASA.Set|$$TRE|Speed|2.5
ASA.End|$$TRE|$$RES
PRT.Array with handle $$TRE is gone
PRT.Cleanup result: $$RES
MBX.Ready
'
Remarks
- The handle in $$TRE must be valid (from ASA.New) or the command might fail silently.
- After ASA.End, trying to use $$TRE with other ASA commands will cause errors—check with ASA.Validate if you’re unsure.
- The optional $$RES is useful for debugging; 0 means success, anything else might mean the handle wasn’t valid.
- Use ASA.End for each array you create, or use ASA.EndAll to clear all arrays at once.
Limitations
- $$TRE must be exactly 5 characters; longer or shorter names might break the script.
- If $$TRE isn’t a valid handle, the command might not warn you unless you check $$RES.
- You can’t undo this—once the array is gone, it’s gone for good!
See also:
• ASA.New
• ASA.Set