|
<< 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.Comparison
Sets how strings are compared in the associative array container.
Intention
The ASA.Comparison command configures how string keys are compared within an associative array.
This affects the sorting order of keys and determines whether searches are case-sensitive or not.
You can choose between tree-based comparison Case-insensitive or case-sensitive compare,
with optional collation settings, giving you fine control over how your string keys are ordered and matched.
Illustration
🔤 Setting Tree Comparison: Using ASA.Comparison|$$TRE|$$UCA determines whether "Apple" comes before "apple".
🌐 Language Support: With the proper collation, "café" and "cafe" can be treated as the same or different keys.
Syntax
ASA.Comparison|$$TRE|$$UCA[|$$COL]
Parameter Explanation
P1 - $$TRE - (Variable, 5 characters max)
This is the handle of the array for which you're setting the comparison method. It's a 5-character variable (like $$TRE or $$ARR) from ASA.New. The command applies the comparison settings to this array.
P2 - $$UCA - (Variable or String)
Specifies the comparison method to use. It can be:
$$TRE - Uses the default tree-based string comparison
$$UCA - Uses the Unicode Collation Algorithm for linguistically accurate string comparison
P3 - $$COL - (Optional Variable or String)
An optional collation parameter that must be exactly 256 characters long when provided. It defines specific character ordering rules for the comparison. When used with $$UCA, it allows for fine-tuning string comparisons according to specific language or custom requirements.
Examples
'***********************************
' ASA.Comparison - Sample 1: Default Tree Comparison
'***********************************
ASA.New|$$TRE|s
ASA.Comparison|$$TRE|1
ASA.Set|$$TRE|Apple|Red fruit
ASA.Set|$$TRE|apple|Different due to case
ASA.Count|$$TRE|$$CNT
PRT.Key count: $$CNT ' Will show 2 as keys are different
MBX.Ready
'
'***********************************
' ASA.Comparison - Sample 2: Unicode Collation
'***********************************
ASA.New|$$TRE|s
ASA.Comparison|$$TRE|0
ASA.Set|$$TRE|café|Coffee shop
ASA.Set|$$TRE|cafe|Updated text
ASA.Get|$$TRE|café|$$VAL
PRT.Value for café: $$VAL ' Shows how accented chars are handled
MBX.Ready
'
'***********************************
' ASA.Comparison - Sample 3: Custom Collation
'***********************************
' Create a 256-character collation string (simplified example)
$$COL="...256 character collation string..."
$$UCA=0
ASA.New|$$TRE|s
ASA.Comparison|$$TRE|$$UCA|$$COL
ASA.Set|$$TRE|KeyA|ValueA
ASA.Set|$$TRE|KeyB|ValueB
ASA.Set|$$TRE|KeyC|ValueC
PRT.Keys are now ordered according to custom collation
MBX.Ready
'
Remarks
- $$UCA can affect case sensitivity settings in the comparison.
- Changing comparison settings after keys are already added may affect key ordering and matching.
- For language-specific sorting, using $$UCA with an appropriate collation is recommended.
- Best set comparison settings immediately after creating the array, before adding keys.
Limitations
- $$TRE must be a valid array handle from ASA.New.
- When providing a collation string, it must be exactly 256 characters long.
- Comparison settings apply only to string keys, not numeric or other data types.
- Complex linguistic sorting may have performance implications on large arrays.
See also:
• ASA.New
• ASA.Set
• ASA.Get