find()

11.16 find()

This function searches for a specified value in a list of values and returns the first found index where this search value can be found.

The search never includes the default element (e.g. index [0] or [0,0]).

By specifying a start and end index, the search can be restricted. The valid values are:

No value specified.
integer value in the range 1 … field size (but must be > 0) for collections with data types vector, refvec, list or hash.
index value in the range from [1,1] to [rowcount,colcount] where rowcount and colcount must also be > 0.
Valid index of a hash.

When searching for strings it is also possible to search case-insensitive or for the first occurrence as prefix.

Since the indices of hashes are not subject to any order, only an integer value in the range 1 … itemcount() should be specified as index, which indicates the position of the start or end element.

For two-dimensional arrays (similar to the :find() method for .content[] at the tablefield), specifying an index range [Sy,Sx] to [Ey,Ex] restricts the search scope to the range [min(Sy,Ey),min(Sx,Ex)] … [max(Sy,Ey),max(Sx,Ex)]. Thus the restriction to rows and columns is easily possible.

Definition

anyvalue find
(
      anyvalue ListValue  input,
      anyvalue Value      input
  { , anyvalue StartIndex input
  { , anyvalue EndIndex   input } }
  { , boolean  CaseSensitive := false       input }
  { , enum     MatchType     := match_exact input }
)

Parameters

anyvalue ListValue input

In this parameter, a list value is expected in which to search.

anyvalue Value input

The value specified in this parameter is searched for. Only values are compared whose types are equal or can be converted (a text is converted to a string for this purpose).

anyvalue StartIndex input

This optional parameter specifies the start index from which to search for the value in the collection. If no value is specified here, 1 is assumed for one-dimensional and [1,1] for two-dimensional collections.

anyvalue EndIndex input

This optional parameter specifies the end index up to which the collection shall be searched for the value. This argument is only permitted if a start index has also been specified.

boolean CaseSensitive := false input

This optional parameter only applies to string values and defines whether the search should be case-sensitive or not. The default value is false.

enum MatchType := match_exact input

This optional parameter only applies to string values and defines how to search for strings.

Value range

match_begin: Finds the first string that starts with the search string.
match_exact: Finds the first string that exactly matches the string that is searched for.
match_first: Finds the string whose beginning has the largest match with the search string. If there is a string that matches the search string exactly, its index will be returned.
match_substr: Finds the first string that contains the string that is searched for.

Return value

0: Item was not found in the passed list (data types list, vector, refvec).
[0,0]: Item was not found in the passed matrix.
nothing: Item was not found in the passed associative array (data type hash).
otherwise: Index of the item in the passed collection. The value returned has the index data type of the collection passed.

Fault behavior

The function call fails if the ListValue parameter is not a collection, the index ranges are outside the valid range, or another invalid parameter value exists.

Remark

If the StartIndex and EndIndex parameters have a data type other than integer when searching in hashes, the position of the start and end elements is calculated from the specified indexes. In this respect, searching in hashes with the find() function differs from searching in associative arrays with the :find() method.

Example

dialog D

on dialog start
{
  variable hash Hash := [
    "030"  => "berlin",
    "0711" => "stuttgart",
    "089"  => "munich" ];
  variable matrix Matrix := [
    [1,1] => "area code", [1,2] => "call number",
    [2,1] => 089,         [2,2] => 713400,
    [3,1] => 0711,        [3,2] => 805439 ];
  variable anyvalue Idx;

  Idx := find(Hash, "stuttgart");
  if Idx <> nothing then
    print "Found: stuttgart => " + Idx;
    Idx := find(Matrix, atoi(Idx), [2,1], [3,1]);
    if Idx <> [0,0] then
      print "Call: " + Matrix[first(Idx),2];
    endif
  endif
  exit();
}