|
<< 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.New
Creates a new associative array and returns its handle.
Intention
The ASA.New command sets up a fresh associative array in SPR. An associative array is like a dictionary or a phonebook: it links keys (like words or names) to values (like definitions or phone numbers). When you run this command, SPR gives you a special number called a handle, stored in a variable like $$TRE. This handle is your key to working with the array—adding data, finding values, or deleting entries. You can choose what kind of values the array holds: text (like "Alice"), big whole numbers (like 1234567890), or precise decimals (like 3.14159). This makes ASA.New the first step for tasks like building a list of settings (e.g., "Volume" → "50"), tracking inventory (e.g., "Apples" → "10"), or saving robot positions (e.g., "X" → "1.5"). It’s simple but powerful for organizing data in your SPR scripts!
For example, imagine you’re making a script to store a phonebook. You use ASA.New to start the phonebook, then add entries like "Alice" → "123-4567" with ASA.Set. Later, you can look up Alice’s number with ASA.Get. Or, if you’re tracking robot sensor data, you might store "Temperature" → "23.5" and use the handle to check it anytime. The command is fast and sets everything up so you can focus on what your script needs to do.
Illustration
🌟 New Associative Array: A fresh array with handle $$TRE can hold pairs like "Name" → "Alice" or "Speed" → "10.5".
🔑 Handle: $$TRE gets a number (not zero), ready for commands like ASA.Set to fill it up.
Syntax
ASA.New|$$TRE[|$$TYP]
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is where SPR puts the handle for your new array. It has to be a variable name exactly 5 characters long, like $$TRE or $$ARR. After running ASA.New, this variable gets a number bigger than zero if it works. You’ll use this handle with other ASA commands to add or get data.
P2 - $$TYP - (Optional, String: "s", "i", "f")
This tells SPR what kind of values you want to store. You can pick:
- "s": Strings, for text like names ("Alice") or messages ("Hello").
- "i": Quad Integers, for big whole numbers like counts (1234567890).
- "f": Extended Floating Point, for precise decimals like measurements (3.14159).
If you skip this, SPR usually picks "s" (Strings) as the default, but it’s good to set it so you know what you’re working with.
Examples
'***********************************
' ASA.New - Sample 1: Create a String Associative Array
'***********************************
ASA.New|$$TRE|s
MBX.Text|New String Array Handle: $$TRE
ASA.Set|$$TRE|Name|Alice
ASA.Get|$$TRE|Name|$$VAL
MBX.Text|Value for 'Name': $$VAL
ASA.End|$$TRE
MBX.Ready
'
'***********************************
' ASA.New - Sample 2: Create a Quad Integer Associative Array
'***********************************
ASA.New|$$TRE|i
PRT.|New Quad Array Handle: $$TRE
ASA.Set|$$TRE|Age|25
ASA.Get|$$TRE|Age|$$VAL
PRT.Value for 'Age': $$VAL
ASA.End|$$TRE
MBX.Ready
'
'***********************************
' ASA.New - Sample 3: Create an Extended FP Associative Array
'***********************************
ASA.New|$$TRE|f
PRT.New Extended FP Array Handle: $$TRE
ASA.Set|$$TRE|Pi|3.14159
ASA.Get|$$TRE|Pi|$$VAL
PRT.Value for 'Pi': $$VAL
ASA.End|$$TRE
MBX.Ready
'
Remarks
- The handle variable (e.g., $$TRE) must be 5 characters max and will store a non-zero integer if successful, or zero if creation fails.
- The datatype ("s", "i", "f") determines how values are stored and retrieved; subsequent commands like ASA.Set and ASA.Get must match this type.
- Use ASA.Validate to confirm the handle’s validity before further operations.
- Always free the array with ASA.End when done to avoid memory leaks.
Limitations
- The handle variable must not exceed 5 characters; longer names may cause runtime errors.
- $$TYP must be "s", "i", or "f"; invalid values may result in errors or undefined behavior.
- Only one datatype per array; mixing types (e.g., String keys with Quad values) isn’t supported.
See also:
• ASA.End
• ASA.Set
• ASA.Get