Programmer Guide/Command Reference/FIND: Difference between revisions

From STX Wiki
Jump to navigationJump to search
m (1 revision: Initial import)
No edit summary
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
{{DISPLAYTITLE:{{SUBPAGENAME}}}}
==FIND==
The <code>FIND</code> command searches a table item for a particular entry and returns the zero-based index of this entry (if found), or the empty string (if unfound, eh, not found, in which case an appropriate return code <code>$RC</code> will be set, too). Note that the <code>FIND</code> command can only be used with [[Programmer_Guide/Concepts/Simple_table|simple tables]], and with string and name fields of [[Programmer_Guide/Concepts/Extended_table|extended tables]].


The <code>FIND</code> command searches a table item for a particular entry and returns this entry's index (if found). The FIND command can only be used with simple tables or the extended table string/name fields.
#pos := FIND <var>table entry field</var> [ <var>mask taggedonly respectcase</var> ]


<code>#pos := FIND <var>table entry field</var> [<var>mask</var> <var>tag case</var>]</code>
;<var>table</var>: the name of the table item to search
;<var>entry</var>: the zero-based index of the item where the search should start, the asterisk, <code>*</code> (or, obviously, the index 0) indicating that the whole table is to be searched
;<var>field</var>: for an [[Programmer_Guide/Concepts/Extended_table|extended tables]], this has to be the zero-based index, or the name of, of the string field, or the name field, to be searched. For [[Programmer_Guide/Concepts/Simple_table|simple tables]], this parameter is ignored (but has to be present!), and should be set to <code>*</code>.
;<var>mask</var>: the search mask (wildcards are possible)
;<var>taggedonly</var>: If set to <code>0</code> (default), ''all'' entries of the table will be searched. if set to <code>1</code>, only ''tagged'' entries will be searched.
;<var>respectcase</var>: if set to <code>0</code> (default), the search will be case-insensitive. If set to <code>1</code>, the search will case-sensitive.


-> #pos = 'entryindex' or empty if not found
For more complex query operations, you should consider the <code>[[Programmer_Guide/Command_Reference/QUERY|QUERY]]</code>, or even the <code>[[Programmer_Guide/Shell_Items/Table/SET_TABLE#FIND|SET table FIND]]</code> command (q.v.). ''N.B.:'' It is important to not mix up these commands, since they work in different ways, and offer different options, and functionality.


;<var>table</var>
[macro FindStringInTable]
#t := new table *
$#t * 'The big red apple was very juicy'
$#t * 'The blue waves were mesmerizing'
$#t * 'The green man said - "You are coming with me"'
$#t * 'The red dwarf star was a million miles away'
#searchStr := 'red'
do forever
    #i := find $#t '$#i' '*' '*$#searchStr*'
    if '$rc' != 0 break
    um 'The table entry $#i ($#t[$#i]) contains the word "$#searchStr"'
end
delete /Var #t
exit


:The name of the table item to search.
''See also:''  <code>[[Programmer_Guide/Command_Reference/QUERY|QUERY]]</code>, and <code>[[Programmer_Guide/Shell_Items/Table/SET_TABLE#FIND|SET table FIND]]</code>
 
;<var>entry</var>
 
:<code>*</code> for all entries or the index from which to start searching.
 
;<var>field</var>
 
:Index or name of string/name field. This parameter is ignored for simple tables and should be set to <code>*</code>.
 
;<var>mask</var>
 
:The search mask (wildcards are possible).
 
;<var>tag</var>
 
:Search all (<code>0</code>) or tagged (<code>1</code>) fields. The default is <code>0</code>.
 
;<var>case</var>
 
:Ignore (<code>0</code>) or respect (<code>1</code>) case. The default is <code>0</code>.
 
<pre>
[macro FindStringInTable]
#t := new table *
$#t * 'The big red apple was very juicy'
$#t * 'The blue waves were mesmerizing'
$#t * 'The green man said - "You are coming with me"'
$#t * 'The red dwarf star was a million miles away'
#searchStr := 'red'
do forever
    #i := find $#t '$#i' '*' '*$#searchStr*'
    if '$rc' != 0 break
    um 'The table entry $#i ($#t[$#i]) contains the word "$#searchStr"'
end
delete $#t
exit
</pre>

Latest revision as of 14:15, 5 April 2016

The FIND command searches a table item for a particular entry and returns the zero-based index of this entry (if found), or the empty string (if unfound, eh, not found, in which case an appropriate return code $RC will be set, too). Note that the FIND command can only be used with simple tables, and with string and name fields of extended tables. 

#pos := FIND table entry field [ mask taggedonly respectcase ]
table
the name of the table item to search
entry
the zero-based index of the item where the search should start, the asterisk, * (or, obviously, the index 0) indicating that the whole table is to be searched
field
for an extended tables, this has to be the zero-based index, or the name of, of the string field, or the name field, to be searched. For simple tables, this parameter is ignored (but has to be present!), and should be set to *.
mask
the search mask (wildcards are possible)
taggedonly
If set to 0 (default), all entries of the table will be searched. if set to 1, only tagged entries will be searched.
respectcase
if set to 0 (default), the search will be case-insensitive. If set to 1, the search will case-sensitive.

For more complex query operations, you should consider the QUERY, or even the SET table FIND command (q.v.). N.B.: It is important to not mix up these commands, since they work in different ways, and offer different options, and functionality. 

[macro FindStringInTable]
#t := new table *
$#t * 'The big red apple was very juicy'
$#t * 'The blue waves were mesmerizing'
$#t * 'The green man said - "You are coming with me"'
$#t * 'The red dwarf star was a million miles away'
#searchStr := 'red'
do forever
    #i := find $#t '$#i' '*' '*$#searchStr*'
    if '$rc' != 0 break
    um 'The table entry $#i ($#t[$#i]) contains the word "$#searchStr"'
end
delete /Var #t
exit

See also: QUERY, and SET table FIND

Retrieved from "https://mediawiki.kfs.oeaw.ac.at/stx/docs/wiki/index.php?title=Programmer_Guide/Command_Reference/FIND&oldid=8984"

Navigation menu

Personal tools