|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > Arrays and Data-Structures > !Collections/Fast Arrays > Collection-Commands > Smart Package Robot 's Collection Commands |
MiniRobotLanguage (MRL)
RFC. - Command
Removes an element from a specified Collection/Array.
Intention
RFC. stands for "Remove from Collection". The RFC. command selectively removes an element from a specified collection/Array.
It is the direct complement to the ATC. command, enabling precise management of collection contents by ensuring specific items can be deleted as needed.
RFC. will generally remove the first such Element from a Collection the Element is deleted and the Array/Collection is smaller by 1 Element.
This is perfect for Collections, as they can only contain unique Elements.
To use RFC. for Arrays where there can be multiple equal Elements, specify the "a" Option as P3. In that case all such Elements will be deleted.
The command facilitates the upkeep of collections by allowing for the targeted removal of elements, thereby maintaining the integrity and accuracy of the data within the collection. This operation is vital for dynamic data management where updating collections to reflect current needs is essential.
As Elements in Collections are generally "unique", RFC. will remove one Element.
Sample:
' Generate a prename and assign it to variable $$NAA
TST.Generate PreName|$$NAA
' Add the prename to collection 0
ATC.0|$$NAA
' Generate another prename and assign it to variable $$NAB
TST.Generate PreName|$$NAB
' Display the number of elements before adding a new one
CGC.0|$$NUA
DBP.Before: $$NUA elements in Collection 0. Adding: $$NAB
' Add the second prename to collection 0
ATC.0|$$NAB
' Display the number of elements after addition
CGC.0|$$NUA
DBP.After Adding: Collection 0 contains $$NUA elements.
' Remove the first prename from collection 0
RFC.0|$$NAA
' Display the number of elements after removal
CGC.0|$$NUA
DBP.After Removal: Collection 0 has $$NUA elements.
' Message box notification
MBX.!
' End of script
ENR.
Syntax
RFC.P1|P2[|P3]
Parameter Explanation
P1 - The collection identifier, typically a numeric value or a variable that contains a number from 0 to 1024.
P2 - The element or "word" to be removed from the collection. P2 can contain any characters, also binary data.
P3 - (optional) can be
"a" or "c". If "a" is specified RFC. will work as "Remove from Array" and delete all such Elements that can be in an Array.
If not specified only the first found Element is removed which is normal as in Collection any Element can be only 1 time.
"c" will switch to "case insensitive". Regular operation is case sensitive.
additionally you can specify the following letters to pre-process P2 to match the format of the Elements in the Array.
"f" - floating point number with a range of approximately +/- 3.4*10^-4932 to 1.2*10^4932, and offer 18 digits of precision
"i" - 64-bit Integer number with a range of -9.22x10^18 to 9.22x10^18 ( -2^63 to 2^63 -1)
"t" - Trim String before store.
"l" - Lower-Case-Trim String before store.
"u" - Upper-Case-Trim String before store.
Example
'***********************************
' RFC.-Sample
'***********************************
' Generate a prename and assign it to variable $$NAA
TST.Generate PreName|$$NAA
' Add the generated prename to collection 0
ATC.0|$$NAA
' Generate another prename and assign it to variable $$NAB
TST.Generate PreName|$$NAB
' Get the current count of elements in collection 0 before adding the new name
CGC.0|$$NUA
' Output the count before addition and the prename intended to be added
DBP.Before: Collection 0 has $$NUA elements. Attempting to add: $$NAB
' Add the new prename to collection 0
ATC.0|$$NAB
' Get the updated count of elements in collection 0 after adding the new name
CGC.0|$$NUA
' Output the updated count after the addition attempt
DBP.After Adding: Collection 0 now has $$NUA elements.
' Remove the first generated prename from collection 0
RFC.0|$$NAA
' Get the count of elements in collection 0 after the removal
CGC.0|$$NUA
' Output the final count after removal
DBP.After Removal: Collection 0 has $$NUA elements remaining.
' Alert box indicating the end of processing
MBX.!
' End of script
ENR.
Remarks
-
Limitations:
Currently the Smart Package Robot supports 1025 Collections that are numbered from 0 to 1024 and Type 2 -"Checksum"-Collections from 1025 to 2048.
Type 1 Collections are groups of character strings that are separated by a null byte. Therefore Elements must never Contain a CHR(0) (Null-Byte).
Type 2 Collections will contain a 16 Byte Checksum of an Element and do not have any delimiter.
See also:
• CFV. - Collection from Variable
• CTV. - Collection to Variable
• RFC. - Remove from Collection