|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > Assoc. Array to/from Variable > ASA. - Associative Array Operations |
SPR Script Language
ASA.Restore
Restores an associative array from a serialized string.
Intention
The ASA.Restore command restores data from a serialized string (created with ASA.Store) into an associative array. You provide the array handle and the string containing the serialized data. This allows you to recreate an array that was previously saved, making it possible to persist complex data structures between different parts of your script or after clearing an array.
Think of it as bringing back an entire set of key-value pairs at once. For example, you might store configuration settings in a string variable and then restore them to an array when needed, or save the current state of your application before performing operations that could be reversed.
Illustration
📥 Restore Data: When you have a string like $$STR containing serialized array data, ASA.Restore loads it into the array with handle $$TRE.
🔄 Complete Rebuild: The entire array structure is recreated exactly as it was when stored.
Syntax
ASA.Restore|$$TRE|$$STR
ASA.Restore|$$TRE
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is the handle of the target associative array. It must be a 5-character variable that has been created with ASA.New. The array identified by this handle will be populated with the data from the serialized string.
P2 - $$STR - (Variable or Value, Optional)
This is the serialized string containing the array data, previously created with ASA.Store. If this parameter is omitted, the command will take the string from the top of the stack.
Examples
'***********************************
' ASA.Restore - Sample 1: Basic Usage
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|KeyA|ValA
ASA.Set|$$TRE|KeyB|ValB
ASA.Store|$$TRE|$$STR
ASA.Clear|$$TRE
ASA.Count|$$TRE|$$CNT
PRT.Count after clearing: $$CNT
ASA.Restore|$$TRE|$$STR
ASA.Count|$$TRE|$$CNT
PRT.Count after restore: $$CNT
'
'***********************************
' ASA.Restore - Sample 2: Using Stack
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|Name|Alice
ASA.Store|$$TRE
STK.$$SAVED=
ASA.Clear|$$TRE
STK.$$SAVED
ASA.Restore|$$TRE
ASA.Get|$$TRE|Name|$$VAL
PRT.Restored name: $$VAL
'
'***********************************
' ASA.Restore - Sample 3: Complex Sequence
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|KeyC|ValC
ASA.Set|$$TRE|KeyA|ValA
ASA.Set|$$TRE|KeyB|ValB
ASA.Store|$$TRE|$$STR
ASA.Clear|$$TRE
ASA.Restore|$$TRE|$$STR
ASA.Count|$$TRE|$$CNT
PRT.Restored count: $$CNT
'
Remarks
- ASA.Restore populates the array with all key-value pairs from the stored data.
- Any existing content in the array will be preserved unless keys conflict.
- The serialized string contains type information, so the restored values will have the same types as when stored.
- When the second parameter is omitted, the command takes the serialized string from the stack.
Limitations
- The target array ($$TRE) must exist—create it first with ASA.New if not.
- The serialized string must be valid (created with ASA.Store)—otherwise, the restore may fail or produce unexpected results.
- When using the stack version, ensure something is actually on the stack, or the restore will fail.
See also:
• ASA.New