2.15 :find()

This method searches in predefined and user-defined indexed attributes (one-dimensional, two-dimensional and associative arrays) for a specific value and returns the first index where this search value is 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 (void).
  • integer value in the range 1 … field size (but must be > 0) for (associative) arrays.
  • index value in the range from [1,1] to [rowcount,colcount] where rowcount and colcount must also be > 0.

All other values will cause a fail.

This implies that searching a complete array should be carried out without a start and end index, because a start or end index of [0] or [0,0] would cause a fail.

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

The search is only performed in the range 1 … n or [1,1] … [n,m], i.e. indexes of 0 are not allowed.

Since the indices of associative arrays are not subject to any order, only an integer value in the range 1 … itemcount[<attribute>] can be specified as index, which indicates the position of the start or end element.

For two-dimensional arrays (.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.

The search is performed in the direction of the specified indices and taking .direction into account (only for two-dimensional arrays). Specifying 10, 1 instead of 1, 10 as start and end indexes therefore reverses the search direction. A vertically aligned two-dimensional array is searched in the order rows/columns, with horizontal alignment this is exactly the opposite. The index of the first field matching the value is returned.

Definition

anyvalue :find
(
  {   attribute Attribute input, }
      anyvalue  Value     input
  { , anyvalue  StartIdx  input
  { , anyvalue  EndIdx    input } }
  { , boolean   CaseSensitive := false       input }
  { , enum      CompareMode   := match_exact input }
)

Parameters

attribute Attribute input

This parameter specifies the predefined or user-defined attribute where the value is searched for.

If this parameter is not specified then for poptext and spinbox the .text[integer] attribute is searched and for all other objects the .content[] attribute.

anyvalue Value input

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

If this value is a string or a text resource, the parameters CaseSensitive and CompareMode are also applied for the search.

anyvalue StartIdx input
This optional parameter specifies the start index from which to search for the value in the indexed attribute. If no value is specified here, 1 is assumed for one-dimensional and [1,1] for two-dimensional attributes.
anyvalue EndIdx input
This optional parameter specifies the end index up to which the indexed attribute 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 CompareMode := 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 one-dimensional, non-associative attribute.
[0,0]
Item was not found in the passed two-dimensional attribute.
nothing
Item was not found in the passed associative array.
otherwise
Index of the searched item in the passed attribute. The value returned has the index data type of the passed attribute.

Fault behavior

Invocation of the method fails if the attribute is not known or the range defined by StartIdx and EndIdx is not within the valid index range.

Objects with this method

Example 

window Wn
{
  .title "Example for method :find()";

  child listbox Lb
  {
    .content[1] "McCusker";
    .content[2] "McNeill";
    .content[3] "Pinter";
    .content[4] "Tilly";
    .content[5] "Miller";
    .content[6] "Meyer";
    .content[7] "Davis";

    rule void Showfind (string What input)
    {
      variable integer Index;
      
      !! Observes upper/lower case and searches for the first matching string.
      Index := Lb:find(What, true, match_begin);
      if (Index = 0) then
        Et_find.content := "No item found";
      else
        Lb.activeitem := Index;
        Et_find.content := "Next matching string";
      endif
    }
  }

  child pushbutton Pb_find
  {
    .text "Search item";

    on select
    {
      Lb:Showfind(Et_find.content);
    }
  }

  child edittext Et_find
  {
     .content "Which item";
  }
}

See also

Built-in function find()