stk_where

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.

Parameter=outcount (integer)

OUTPUT: The number of matches found in the stack.

Bugs

There are no known bugs for this tool.