|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > Assoc. Array Clone > ASA. - Associative Array Operations |
SPR Script Language
ASA.Clone
Creates a copy of an existing associative array.
Intention
The ASA.Clone command duplicates an associative array in SPR. You give it the handle of the array you want to copy (like $$TRE), and it creates a new, identical array, putting its handle in $$NEW. This new array has all the same key-value pairs as the original but is separate—changes to one won’t affect the other. It’s perfect for making backups or working copies of your data.
Imagine a phonebook array with "Alice" → "123-4567"—ASA.Clone makes a twin you can edit without touching the original. Or in a robot script, clone an array of settings like "Speed" → "3.14" to test changes safely. It’s a quick way to keep your original data intact while experimenting or preserving a snapshot.
Illustration
📋 Duplicate: From an array with handle $$TRE holding "Name" → "Alice", ASA.Clone makes a new array with the same data.
🔗 New Handle: $$NEW gets a fresh handle to the cloned array!
Syntax
ASA.Clone|$$TRE[|$$NEW]
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is the handle of the array you want to copy. It’s a 5-character variable (like $$TRE or $$ARR) from ASA.New. The command duplicates this array.
P2 - $$NEW - (Optional, Variable, 5 characters max)
This is where the new array’s handle goes. It’s an optional 5-character variable (like $$NEW). SPR puts a non-zero number here if the clone succeeds, or 0 if it fails (e.g., if $$TRE isn’t valid). Use this to work with the new array.
Examples
'***********************************
' ASA.Clone - Sample 1: Clone a String Array
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|Alice|123-4567
ASA.Clone|$$TRE|$$NEW
ASA.Get|$$NEW|Alice|$$VAL
MBX.Cloned value is $$VAL (should be 123-4567)
MBX.Ready
'
'***********************************
' ASA.Clone - Sample 2: Clone a Quad Array
'***********************************
ASA.New|$$TRE|i
ASA.Set|$$TRE|Red|50
ASA.Clone|$$TRE|$$NEW
ASA.Get|$$NEW|Red|$$VAL
PRT.Cloned Red count is $$VAL (should be 50)
MBX.Ready
'
'***********************************
' ASA.Clone - Sample 3: Clone an Extended FP Array
'***********************************
ASA.New|$$TRE|f
ASA.Set|$$TRE|Speed|3.14
ASA.Clone|$$TRE|$$NEW
ASA.Get|$$NEW|Speed|$$VAL
PRT.Cloned Speed is $$VAL (should be 3.14)
MBX.Ready
'
Remarks
- $$TRE must be valid—use ASA.Validate first if unsure.
- The clone keeps the same datatype (String, Quad, Extended) as the original.
- Both arrays are independent—use ASA.End on each when done.
- If cloning fails (e.g., memory issue), $$NEW gets 0.
Limitations
- $$TRE must be 5 characters—wrong lengths might cause errors.
- If $$TRE isn’t valid, cloning fails quietly—no error beyond $$NEW being 0.
- Requires enough memory—large arrays might fail if space is tight.
See also:
• ASA.New
• ASA.End
• ASA.Get