|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ASA. - Associative Array > ASA. - Associative Arrays |
SPR Script Language
ASA.- Operation Commands
Fill and Manage Associative Arrays
Overview
The ASA.-Operation commands allow you to work with associative arrays in SPR. Each array can hold data in one of three types (string, quad, or extended) and automatically keeps its string keys in a sorted tree structure (AVL tree). You can store, retrieve, and remove elements; traverse the array in ascending or descending key order; and dynamically allocate or free the arrays when needed.
Once you create an array withASA.New(which generates a unique handle),you can interact with it using commands likeASA.Set(add or update a key) andASA.Get(retrieve the value for a key). When you’re finished, callASA.End(orASA.EndAllfor all arrays) to free the memory.
An associative array is a structure that allows you to associate a string key with a value.SPR’s ASA commands store these pairs in a self-balancing tree for efficient lookups and iteration.
•Keys are strings, while values can be strings, quad integers, or extended floats depending on how you create the array.
•Automatic sorting of keys—let’s you traverse them in ascending or descending order.
•Commonly used like a dictionary or phonebook.
•You can also store multiple arrays at once, each with its own handle.
A handle is a unique identifier that references a specific associative array. It is generated when the array is created using ASA.Newand is used to interact with that array in subsequent commands. Handles are essential if you need to manage multiple arrays simultaneously. Once an array is deallocated using ASA.Endor ASA.EndAll, its handle becomes invalid.
This script demonstrates how to create an array, add elements, retrieve elements, and deallocate the array.
'***********************************
' ASA.-Operation Sample 1: Basic Operations
'***********************************
ASA.New|$$TRE|s
DBP.New associative array created with this handle: $$TRE
' Add key-value pairs
ASA.Set|$$TRE|Alice|555-1001
ASA.Set|$$TRE|Bob|555-2002
ASA.Set|$$TRE|Carol|555-3003
' Check the number of elements
ASA.Count|$$TRE|$$CNT
DBP.Number of entries in $$TRE: $$CNT
' Retrieve a value by key
ASA.Get|$$TRE|Bob|$$VAL
DBP.Bob's number is $$VAL
' Check if a key exists
ASA.Got|$$TRE|Diana|$$RES
IVS.$$RES=1
DBP.Diana found
ELS.
DBP.Diana not found
EIF.
' Remove a key
ASA.Del|$$TRE|Alice
' End the array
ASA.End|$$TRE
DBP.Array deallocated.
ENR.
This script shows how to create and manage multiple arrays with different data types.
'***********************************
' ASA.-Operation Sample 2: Multiple Arrays
'***********************************
' Create a string array
ASA.New|$$TRE_STR|s
ASA.Set|$$TRE_STR|KeyA|ValA
ASA.Set|$$TRE_STR|KeyB|ValB
' Create a quad array
ASA.New|$$TRE_QUAD|i
ASA.Set|$$TRE_QUAD|Num1|100
ASA.Set|$$TRE_QUAD|Num2|200
' Create an extended float array
ASA.New|$$TRE_FLOAT|f
ASA.Set|$$TRE_FLOAT|F1|1.11
ASA.Set|$$TRE_FLOAT|F2|2.22
' Retrieve and display elements from each
ASA.Get|$$TRE_STR|KeyB|$$RES
DBP.String array KeyB: $$RES
ASA.Get|$$TRE_QUAD|Num2|$$RES
DBP.Quad array Num2: $$RES
ASA.Get|$$TRE_FLOAT|F2|$$RES
DBP.Float array F2: $$RES
' Deallocate all arrays
ASA.EndAll
DBP.All arrays deallocated.
ENR.
This script demonstrates how to validate an array handle and check the array’s data type.
'***********************************
' ASA.-Operation Sample 3: Validation and Type Checking
'***********************************
ASA.New|$$TRE|i
ASA.Set|$$TRE|TestKey|12345
' Validate the handle
ASA.Validate|$$TRE|$$RES
DBP.Array validation result: $$RES
' Check the array type
ASA.GTy|$$TRE|$$TYP
DBP.Type of array: $$TYP (Expected: i for quad)
' Deallocate the array
ASA.End|$$TRE
DBP.Array deallocated.
ENR.
This script demonstrates how to delete specific keys from an array.
'***********************************
' ASA.-Operation Sample 4: Deleting Elements
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|First|Value1
ASA.Set|$$TRE|Second|Value2
ASA.Set|$$TRE|Third|Value3
' Delete "Second"
ASA.Del|$$TRE|Second
' Retrieve to confirm "Second" is gone
ASA.Got|$$TRE|Second|$$RES
IF.$$RES=1
DBP.Second key still exists? $$RES
ELSE.
DBP.Successfully deleted "Second"
EIF.
ASA.End|$$TRE
DBP.Array deallocated.
ENR.
This script demonstrates how to clear an array and reuse it for new elements.
'***********************************
' ASA.-Operation Sample 5: Clearing and Reusing
'***********************************
ASA.New|$$TRE|s
ASA.Set|$$TRE|OldKey|OldVal
' Clear the array
ASA.Clear|$$TRE
DBP.Array cleared.
' Reuse with new entries
ASA.Set|$$TRE|NewKey|NewVal
ASA.Get|$$TRE|NewKey|$$VAL
DBP.NewKey => $$VAL
' Deallocate the array
ASA.End|$$TRE
DBP.Array deallocated.
ENR.
The ASA.-Operation commands provide a flexible, powerful system for storing and manipulating key-value data. Whether you need a small dictionary of strings or a larger structure of numeric data, these commands let you efficientlyorganize, search, and traverse. Use the examples above as a starting point for integrating associative arrays into your scripts.
See also:
• ASA.Count - Retrieve the number of items
• ASA.Validate - Check if a handle is still valid
• ASA.Clear - Remove all keys and values
• ASA.EndAll - Deallocate all existing arrays at once