|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > ARS. - Array's > ARS. - Sorting Operations |
📘 SPR Array Sorting Commands Manual
This guide takes you deep into SPR’s array sorting toolkit: ARS.Sort, ARS.Reverse, ARS.DualSort, and ARS.SortByTag. These commands empower you to organize, flip, and customize array data with precision—whether it’s a standalone list or paired datasets. Packed with detailed explanations, practical examples, and real-world scenarios, this manual helps you unlock the full potential of SPR arrays. Ready to sort things out? Let’s jump in! 🚀
•Overview of Sorting Commands
•ARS.Sort: Features and Usage
•ARS.Reverse: Features and Usage
•ARS.DualSort: Features and Usage
•ARS.SortByTag: Features and Usage
•Practical Code Examples
•Real-World Use Cases
SPR’s ARS module provides four essential sorting commands to tame your arrays:
•ARS.Sort: Orders a single array from smallest to largest—your go-to for basic tidying up.
•ARS.Reverse: Flips an array’s order, perfect for switching perspectives.
•ARS.DualSort: Sorts one array and syncs another, keeping paired data in lockstep.
•ARS.SortByTag: Sorts an array using a separate numeric guide, for tailored control.
These commands operate on SPR’s dynamic arrays, which can hold Integer values (whole numbers), FP (Floating Point) values (decimals), or String values (text). Each command has unique strengths, detailed below, to help you manage data effectively. 🔧
What It Does: The ARS.Sort command takes an array—let’s call it $$ARR—and rearranges its elements in ascending order. For Integer or FP arrays, this means smallest to largest numbers (e.g., [5, 2, 8] becomes [2, 5, 8]). For String arrays, it’s alphabetical order (e.g., [Cat, Ann, Ben] becomes [Ann, Ben, Cat]). It’s a straightforward, in-place operation that modifies $$ARR directly.
Why It’s Needed: Sorting is a fundamental task in data handling—like organizing a messy desk 📚. Imagine you’ve got a list of numbers or names in random order; without sorting, finding the smallest value, ranking items, or presenting data cleanly is a hassle. ARS.Sort automates this, saving time and ensuring consistency. It’s the backbone for tasks where order matters, from statistics to user interfaces.
When to Use It: Reach for ARS.Sort when you need a single array in a predictable sequence. Examples include sorting sales figures to find top performers, arranging timestamps for a timeline, or alphabetizing a contact list. It’s your quick fix for standalone data that needs structure! 🌈
' Syntax:
ARS.Sort|$$ARR
Parameters:
•$$ARR: The array handle to sort (can be Integer, FP, or String).
Features:
•Supports all array types—Integer, FP, and String—for maximum flexibility. 🎉
•Sorts directly within $$ARR, no extra memory needed—efficient and fast! ⚡
•Needs at least one element in $$ARR to work—empty arrays won’t sort.
What It Does: ARS.Reverse flips the order of an array—say, $$ARR—turning [1, 2, 3] into [3, 2, 1] or [Ann, Ben] into [Ben, Ann]. It’s a simple yet powerful transformation that works on any type—Integer, FP, or String.
Why It’s Needed: Sometimes, you need to see data from the opposite end—like reading a book backwards 📖. After sorting with ARS.Sort, you might want descending order (largest to smallest) instead. Or maybe you’re processing a stack-like sequence where the last item should come first. ARS.Reverse gives you that flip without manual reordering, making it a time-saver for dynamic data views.
When to Use It: Use ARS.Reverse to switch perspectives—think top scores first, latest events first, or reversing a playlist order. Pair it with ARS.Sort for descending sorts, or use it alone to invert any list. It’s a handy twist for creative data handling! 🔄
' Syntax:
ARS.Reverse|$$ARR
Parameters:
•$$ARR: The array handle to reverse (type: Integer, FP, or String).
Features:
•Works across all types—Integer, FP, String—no exceptions! 🌟
•In-place reversal keeps things lean and efficient.
•Combines with ARS.Sort for descending order—think big-to-small rankings! 📉
What It Does: ARS.DualSort sorts a source array ($$SRC) in ascending order and mirrors that exact rearrangement in a target array ($$TGT). For example, if $$SRC is [3, 1, 4] and $$TGT is [A, B, C], after sorting, $$SRC becomes [1, 3, 4] and $$TGT becomes [B, A, C]. It keeps paired data perfectly synced.
Why It’s Needed: Real-world data often comes in pairs—like names and scores, or dates and events. Sorting one without the other breaks their relationship, turning useful info into chaos 🌪️. ARS.DualSort solves this by ensuring both arrays stay aligned, saving you from manual re-matching or data loss. It’s like a dance partner that never misses a step! 💃🕺
When to Use It: Use ARS.DualSort when you’re dealing with two related arrays that need to stay in sync. Think student grades and names, product prices and items, or log times and messages. It’s essential for reports, rankings, or timelines where context is king! 📊
' Syntax:
ARS.DualSort|$$SRC|$$TGT
Parameters:
•$$SRC: Source array handle (type: Integer, FP, or String).
•$$TGT: Target array handle (type: Integer, FP, or String).
Features:
•Mix-and-match types—like $$SRC as String and $$TGT as FP—for versatile pairing. 🎨
•Sorts $$SRC numerically (Integer, FP) or alphabetically (String), syncing $$TGT.
•Both $$SRC and $$TGT must be initialized—empty $$TGT might trip it up. ⚠️
What It Does: ARS.SortByTag sorts a source array ($$SRC) according to the ascending order of a numeric tag array ($$TAG), without touching $$TAG. If $$TAG is [3, 1, 2] and $$SRC is [C, A, B], it reorders $$SRC to [A, B, C] based on $$TAG sorting to [1, 2, 3], while $$TAG stays [3, 1, 2].
Why It’s Needed: Sometimes, your sorting order isn’t based on the data itself but on an external key—like timestamps or priorities 📅. Manually reordering $$SRC to match $$TAG is tedious and error-prone. ARS.SortByTag automates this, preserving the original tags for reference while giving you a perfectly ordered $$SRC. It’s a lifesaver for custom sequences! 🛡️
When to Use It: Grab ARS.SortByTag when you need to sort data by a separate numeric guide. Use it for task lists sorted by priority, measurements by time, or orders by delivery slots—anytime the sort key lives outside your main data. Precision control at its best! 🎯
' Syntax:
ARS.SortByTag|$$TAG|$$SRC
Parameters:
•$$TAG: Numeric tag array handle (type: Integer or FP).
•$$SRC: Source array handle (type: Integer, FP, or String).
Features:
•$$TAG and $$SRC must match in size—like puzzle pieces fitting together. 🧩
•Sorts $$SRC based on $$TAG’s numeric order, leaving $$TAG intact.
•$$TAG must be numeric—String tags aren’t supported here.
Let’s see these commands in action with hands-on examples:
'***********************************
' Sorts an array of numbers
'***********************************
ARS.New|$$NUM|Integer
ARS.Add|$$NUM|5
ARS.Add|$$NUM|2
ARS.Add|$$NUM|8
ARS.Add|$$NUM|1
ARS.Sort|$$NUM
ARS.Get|$$NUM|1|$$VAL
DBP.Smallest number: $$VAL
ARS.End|$$NUM
'
Output: $$NUM sorts to [1, 2, 5, 8]. A neat lineup! 📏
'***********************************
' Reverses an array of names
'***********************************
ARS.New|$$NAM|String
ARS.Add|$$NAM|Ann
ARS.Add|$$NAM|Ben
ARS.Add|$$NAM|Cat
ARS.Reverse|$$NAM
ARS.Get|$$NAM|1|$$VAL
DBP.First name after reverse: $$VAL
ARS.End|$$NAM
'
Output: $$NAM flips to [Cat, Ben, Ann]. A quick turnaround! 🔄
'***********************************
' Sorts scores with names
'***********************************
ARS.New|$$SCR|Integer
ARS.New|$$NAM|String
ARS.Add|$$SCR|85
ARS.Add|$$SCR|92
ARS.Add|$$SCR|78
ARS.Add|$$SCR|95
ARS.Add|$$NAM|Ali
ARS.Add|$$NAM|Bob
ARS.Add|$$NAM|Cha
ARS.Add|$$NAM|Dan
ARS.DualSort|$$SCR|$$NAM
ARS.Get|$$SCR|1|$$VAL1
ARS.Get|$$NAM|1|$$VAL2
DBP.Lowest score: $$VAL1 by $$VAL2
ARS.End|$$SCR
ARS.End|$$NAM
'
Output: $$SCR sorts to [78, 85, 92, 95], $$NAM to [Cha, Ali, Bob, Dan]. Paired perfection! 🤝
'***********************************
' Sorts tasks by priority
'***********************************
ARS.New|$$PRI|Integer
ARS.New|$$TSK|String
ARS.Add|$$PRI|3
ARS.Add|$$PRI|1
ARS.Add|$$PRI|4
ARS.Add|$$PRI|2
ARS.Add|$$TSK|Rev
ARS.Add|$$TSK|Cod
ARS.Add|$$TSK|Tes
ARS.Add|$$TSK|Pla
ARS.SortByTag|$$PRI|$$TSK
ARS.Get|$$TSK|1|$$VAL
DBP.Top task: $$VAL
ARS.End|$$PRI
ARS.End|$$TSK
'
Output: $$TSK sorts to [Cod, Pla, Rev, Tes] based on $$PRI [3, 1, 4, 2]. Custom order achieved! 🎯
Here’s how these commands solve everyday problems:
You’re a teacher with student grades and names. You want them ranked highest to lowest for a leaderboard.
'***********************************
' Rank students by grades
'***********************************
ARS.New|$$GRA|Integer
ARS.New|$$STU|String
ARS.Add|$$GRA|88
ARS.Add|$$GRA|95
ARS.Add|$$GRA|76
ARS.Add|$$GRA|91
ARS.Add|$$STU|Emm
ARS.Add|$$STU|Lia
ARS.Add|$$STU|Noa
ARS.Add|$$STU|Oli
ARS.DualSort|$$GRA|$$STU
ARS.Reverse|$$GRA
ARS.Reverse|$$STU
FOR.$$I|1|4
ARS.Get|$$GRA|$$I|$$GR
ARS.Get|$$STU|$$I|$$NM
DBP.Rank $$I: $$NM with $$GR
NEX.
ARS.End|$$GRA
ARS.End|$$STU
'
Result: [Lia 95, Oli 91, Emm 88, Noa 76]. Top students shine! 🏆
You’re debugging with a log of times and messages, needing them in chronological order.
'***********************************
' Sort logs by time
'***********************************
ARS.New|$$TIM|FP
ARS.New|$$LOG|String
ARS.Add|$$TIM|14.25
ARS.Add|$$TIM|13.50
ARS.Add|$$TIM|15.00
ARS.Add|$$TIM|14.75
ARS.Add|$$LOG|Err
ARS.Add|$$LOG|Sta
ARS.Add|$$LOG|Log
ARS.Add|$$LOG|Sav
ARS.SortByTag|$$TIM|$$LOG
FOR.$$I|1|4
ARS.Get|$$TIM|$$I|$$TM
ARS.Get|$$LOG|$$I|$$LG
DBP.At $$TM: $$LG
NEX.
ARS.End|$$TIM
ARS.End|$$LOG
'
Result: [13.50: Sta, 14.25: Err, 14.75: Sav, 15.00: Log]. Timeline clear! ⏰
You’re running a store, sorting items by price for a catalog.
'***********************************
' Sort inventory by price
'***********************************
ARS.New|$$PRI|FP
ARS.New|$$ITM|String
ARS.Add|$$PRI|19.99
ARS.Add|$$PRI|9.50
ARS.Add|$$PRI|25.00
ARS.Add|$$PRI|15.75
ARS.Add|$$ITM|Lap
ARS.Add|$$ITM|Mou
ARS.Add|$$ITM|Mon
ARS.Add|$$ITM|Key
ARS.DualSort|$$PRI|$$ITM
FOR.$$I|1|4
ARS.Get|$$PRI|$$I|$$PR
ARS.Get|$$ITM|$$I|$$IM
DBP.$$IM costs $$PR
NEX.
ARS.End|$$PRI
ARS.End|$$ITM
'
Result: [Mou 9.50, Key 15.75, Lap 19.99, Mon 25.00]. Shop-ready! 🛒
You’re managing deliveries, prioritizing the latest ones first.
'***********************************
' Sort orders by delivery, descending
'***********************************
ARS.New|$$DEL|FP
ARS.New|$$ORD|Integer
ARS.Add|$$DEL|12.30
ARS.Add|$$DEL|11.45
ARS.Add|$$DEL|13.15
ARS.Add|$$DEL|10.00
ARS.Add|$$ORD|1001
ARS.Add|$$ORD|1002
ARS.Add|$$ORD|1003
ARS.Add|$$ORD|1004
ARS.SortByTag|$$DEL|$$ORD
ARS.Reverse|$$DEL
ARS.Reverse|$$ORD
FOR.$$I|1|4
ARS.Get|$$DEL|$$I|$$TM
ARS.Get|$$ORD|$$I|$$OR
DBP.Order $$OR at $$TM
NEX.
ARS.End|$$DEL
ARS.End|$$ORD
'
Result: [1003 13.15, 1001 12.30, 1002 11.45, 1004 10.00]. Latest first! 🚚
ARS.Sort and ARS.Reverse are your bread-and-butter for single-array order. ARS.DualSort keeps paired data dancing together, and ARS.SortByTag gives you pinpoint control with numeric guides. Mix and match for a data symphony! 🎶
•ARS.Sort and ARS.Reverse: Need an initialized array—empty won’t do!
•ARS.DualSort: Might stumble if $$TGT is empty—keep it filled.
•ARS.SortByTag: $$TAG must be Integer or FP and match $$SRC size.
• ARS.New
• ARS.Add