Synopsis
stk_where finds the location of an item in a stack
Syntax
stk_where infile match [simple] [case] [echo] [verbose] [outnum] [outcount]
Description
stk_where will search the specified stack for the user specified string. The location of the string in the stack is returned in the 'outnum' parameter.
There are several modifiers to the search criteria. The 'case' parameter controls whether or not a case-insensitive search is done. The 'simple' parameter controls whether an exact match has to be made or whether the user string can be a sub-string of the match. In addition, full regular-expression searching is allowed.
The number of matches found in the stack is stored in the 'outcount' parameter. If there is more than 1 then a warning is generated; the 'outnum' will contain the location of the 1st match. If there are no matches found, then the value of 'outnum' will be INDEF. If the tool cannot open the stack or parse the match value then 'outnum' will be set to INDEF and 'outcount' will be 0.
If the 'echo' parameter is set to yes, then the value of 'outnum' is printed to the screen (stdout).
Examples
Example 1
stk_where infile="red,orange,yellow,green,blue,violet" match="blue" pget stk_where outnum outcount 5 1
Finds where in the 'infile' list the value 'blue' occurs. We use 'pget' to get the location 'outnum' and the number of matches.
Example 2
stk_where infile="red,orange,yellow,green,blue,violet" match="BLUE" case=yes
Similar to above, but uses case-insensitive search.
Example 3
stk_where infile="red,orange,yellow,green,blue,violet" match="g" simple- echo+ # stk_where (CIAO): WARNING: 2 matches found; only reporting 1st 2
The default is to perform a simple exact-string match. Setting simple=no ('simple-' is short-hand); then any sub-string matches are reported. In this case we match the letter 'g' in the stack. There are two matches: "orange" and "green". Using echo=yes the value is printed to the screen.
Example 4
stk_where infile="red,orange,yellow,green,blue,violet" match="^g" simple- echo+ 4
Similar to above, but using regular-expression matching we can select that we want "g" to be the first character (that's what the carrot, "^" means). Now there is only 1 match found.
Parameters
name | type | ftype | def | min | max | reqd | stacks |
---|---|---|---|---|---|---|---|
infile | file | input | yes | yes | |||
match | string | yes | |||||
simple | boolean | yes | no | ||||
case | boolean | no | no | ||||
echo | boolean | no | no | ||||
verbose | integer | 0 | 0 | 5 | no | ||
outnum | integer | ||||||
outcount | integer |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input stacks=yes)
The string used to build a stack.
Most stacks are stored as external files using the "@filename.lis" kind of syntax.
Parameter=match (string required)
The string to find in the stack.
The string can contain regular-expression syntax or a simple string that will be exactly matched.
Parameter=simple (boolean not required default=yes)
Perform a simple search of complex regular expression search
If simple=yes then the match string must match exactly the entire line in the stack. If simple=no, then any sub-string matches are also reported.
Parameter=case (boolean not required default=no)
Determines whether case-sensitive (=no) or case-insensitive (=yes) search is performed.
Parameter=echo (boolean not required default=no)
The location of the element in the stack.
The location in the stack that a match was found. If no matches were found (or there was a problem opening the stack) the value will be INDEF. If there was more than 1 match found, then the value will be the location of the first. Note: stack's count from 1 to N.
Parameter=verbose (integer not required default=0 min=0 max=5)
Tool chatter level
Parameter=outnum (integer)
OUTPUT: The location of the element in the stack.
The location in the stack that a match was found. If no matches were found (or there was a problem opening the stack) the value will be INDEF. If there was more than 1 match found, then the value will be the location of the first. Note: stack's count from 1 to N.
Parameter=outcount (integer)
OUTPUT: The number of matches found in the stack.
Bugs
There are no known bugs for this tool.
See Also
- concept
- stack
- tools::stacks
- stk_build, stk_count, stk_read_num