Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/stk_where.html
AHELP for CIAO 4.16

stk_where

Context: Tools::Stacks

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