|
<< Click to Display Table of Contents >> Navigation: 3. Script Language > String commands > String Manipulation |
Intention
The `GPF.` command provides a straightforward way to filter a string by keeping only the characters specified in a second string. All characters in the input string that are *not* present in the "keep characters" string will be removed. It essentially performs a `RETAIN$, ANY` operation.
Syntax
GPF.P1|P2[|P3]
The command takes either 2 or 3 parameters separated by the pipe symbol (`|`).
Parameter Forms:
-GPF.P1|P2(2 Parameters - In-Place Modification)- P1: Input/Output Variable (`$$VAR`) containing the string to filter.- P2: Keep Characters (`$$VAR` or literal string) - Characters to retain in P1.- Output: The variable specified in P1 is modified directly (in-place).
-GPF.P1|P2|P3(3 Parameters - Output to P3)- P1: Input Variable (`$$VAR`) containing the string to filter.- P2: Keep Characters (`$$VAR` or literal string).- P3: Output Variable (`$$VAR`) where the filtered result will be stored.- Output: The result is stored in the variable specified in P3. P1 remains unchanged.
-(Note: While `$tos$` might technically work for parameters depending on internal handling, the primary design indicated by the code focuses on variable input/output.)
Parameters Details
Param |
Type |
Description |
P1 |
Input Variable (`$$VAR`) |
Required. The variable containing the string to be filtered. The content of this variable is resolved using `Vari_Bin`, meaning nested variables or system variables within its content are *not* expanded further by `GPF.`. If only 2 parameters are provided, this variable will be overwritten with the result. Example: $$SRC |
P2 |
Keep Characters (Variable or String) |
Required. A string containing all the characters that should be kept in the input string (P1). This can be a variable (`$$VAR`) or a literal string. All characters from P1 that are *not* present in P2 will be removed. Example: $$DIG = "0123456789" Example: "abcABC" |
P3 |
Output Variable (`$$VAR`) |
Optional. If provided, this variable will receive the filtered result. The input variable (P1) will remain unchanged in this case. Example: $$RES |
Execution Flow
The `GPF.` command executes as follows:
The command verifies if 2 or 3 parameters were provided.
It determines the target output variable: P3 if provided, otherwise P1.
The content of the input variable (P1) is retrieved, applying `Vari_Bin` resolution (prevents further expansion).
The "Keep Characters" string (P2) is retrieved.
The core filtering operation `Retain$(InputString, ANY KeepChars)` is performed.
The resulting filtered string is stored in the target output variable (P3 or P1).
Examples
Example 1: Keep Only Digits (In-Place)
' Goal: Remove non-digit characters from $$SRC
VAR.$$SRC="ID: 987-654 Status: OK"
VAR.$$DIG="0123456789" ' Characters to keep
' Use 2 parameters: Input/Output is $$SRC (P1), Keep chars are in $$DIG (P2)
GPF.$$SRC|$$DIG
PRT.Result: $$SRC
' Output: Result: 987654
ENR.
Example 2: Keep Only Letters (Output to P3)
' Goal: Extract only letters, store result in $$RES
VAR.$$INP="ABC-123 def-456 GHI"
VAR.$$LET="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
VAR.$$RES= ' Clear or initialize result variable
' Use 3 parameters: Input $$INP (P1), Keep $$LET (P2), Output $$RES (P3)
GPF.$$INP|$$LET|$$RES
PRT.Original: $$INP
PRT.Result: $$RES
' Output:
' Original: ABC-123 def-456 GHI
' Result: ABCdefGHI
ENR.
Example 3: Using Literal String for Keep Characters
' Goal: Keep only hexadecimal characters (0-9, A-F, a-f)
VAR.$$SRC="Address: 0xFF00AA - Value GG"
' Use 2 parameters: In-place modify $$SRC (P1)
' P2 is a literal string containing hex chars
GPF.$$SRC|"0123456789ABCDEFabcdef"
PRT.Result: $$SRC
' Output: Result: 0xFF00AAae
ENR.
Example 4: Keeping Specific Symbols
' Goal: Keep only parentheses and commas from a string
VAR.$$INP="(Value A, B, C)"
VAR.$$SYM="(),"
VAR.$$RES=
' Use 3 parameters: Output to $$RES
GPF.$$INP|$$SYM|$$RES
PRT.Result: $$RES
' Output: Result: (,,)
ENR.
Remarks
·`GPF.` is a simplified version of the retain/keep functionality found in `GFS.` (specifically, similar to `GFS.z` when the filter set is defined).
·The comparison is case-sensitive, based on the standard `Retain$` function behavior. "A" in P2 will keep "A" in P1 but not "a".
·The input variable (P1) is resolved using `Vari_Bin`, preventing accidental expansion of system variables (like `$DATE$`) or nested variables (`$$VAR` containing `$$OTH`) within the string being filtered.
·Remember the SPR-Script variable naming convention: `$$` followed by exactly 3 characters (e.g., `$$SRC`, `$$RES`).
·If you need more complex filtering (e.g., removing specific characters, combining multiple sets, immediate actions like removing control chars), use the more versatile `GFS.` command.
See also:
• Variable Commands (VAR., VAB., etc.)