11.16 find()

Diese Funktion sucht einen angegebenen Wert in einer Werteliste und gibt den ersten gefundenen Index zurück an der dieser Suchwert zu finden ist.

Die Suche schließt dabei niemals das Standardelement (also z.B. Index [0] oder [0,0]) ein.

Durch Angabe eines Start- und Endindex kann die Suche beschränkt werden. Die gültigen Werte sind:

  • Kein Wert angegeben.
  • integer-Wert im Bereich von 1 … Feldgröße (muss aber > 0 sein) für Sammlungen mit den Datentypen vector, refvec, list oder hash.
  • index-Wert im Bereich von [1,1] bis [rowcount,colcount] wobei auch hier rowcount und colcount > 0 sein müssen.
  • Gültiger Index in einem hash.

Bei der Suche nach Strings kann auch case-insensitive oder nach dem ersten Vorkommen als Präfix gesucht werden.

Da die Indizes von Hashes keiner Ordnung unterworfen sind, sollte als Index nur ein integer-Wert im Bereich 1 … itemcount() angegeben werden, der die Position des Start- bzw. End-Elements angibt.

Bei zweidimensionalen Feldern (analog zur :find()-Methode für .content[] am tablefield) bewirkt die Angabe eines Indexbereichs [Sy,Sx] bis [Ey,Ex] die Einschränkung des Suchbereichs auf den Bereich [min(Sy,Ey),min(Sx,Ex)] … [max(Sy,Ey),max(Sx,Ex)]. Somit ist die Einschränkung auf Zeilen und Spalten problemlos möglich.

Definition

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

Parameter

anyvalue ListValue input
In diesem Parameter wird ein Listenwert erwartet in dem gesucht wird.
anyvalue Value input
Nach dem in diesem Parameter angegebenen Wert wird gesucht. Grundsätzlich werden nur Werte verglichen, deren Typen gleich bzw. überführbar sind (ein text wird hierzu in einen string überführt).
anyvalue StartIndex input
In diesem optionalen Parameter wird der Startindex angegeben, ab dem in der Sammlung nach einem Wert gesucht werden soll. Wird hier kein Wert angegeben, wird 1 bei eindimensionalen bzw. [1,1] bei zweidimensionalen Sammlungen angenommen.
anyvalue EndIndex input
In diesem optionalen Parameter wird der Endindex angegeben, bis zu dem in der Sammlung nach einem Wert gesucht werden soll. Die Angabe ist nur zulässig, wenn auch ein Startindex angegeben wurde.
boolean CaseSensitive := false input
Dieser optionale Parameter findet nur bei string-Werten Beachtung und definiert, ob die Suche unter Beachtung der Groß-/Kleinschreibung erfolgen soll oder nicht. Der Standardwert ist false.
enum MatchType := match_exact input

Dieser optionale Parameter findet nur bei string-Werten Beachtung und definiert wie nach einem String gesucht werden soll.

Wertebereich

match_begin

Findet den ersten String, der mit dem Suchstring beginnt.

match_exact

Findet den ersten String, der mit dem gesuchten String exakt übereinstimmt.

match_first

Findet den String, dessen Anfang die größte Übereinstimmung mit dem Suchstring aufweist. Gibt es einen exakt mit dem Suchstring übereinstimmenden String, wird dessen Index zurückgegeben.

match_substr

Findet den ersten String, der den gesuchten String enthält.

Rückgabewert

0
Element wurde in der übergebenen Liste (Datentypen list, vector, refvec) nicht gefunden.
[0,0]
Element wurde in der übergebenen Matrix nicht gefunden.
nothing
Element wurde in dem übergebenen assoziativen Feld (Datentyp hash) nicht gefunden.
sonst
Index des Elements in der übergebenen Sammlung. Der zurückgegebene Wert hat den Index-Datentyp der übergebenen Sammlung.

Fehlerverhalten

Der Aufruf der Funktion schlägt fehl, wenn der ListValue-Parameter keine Sammlung ist, die Indexbereiche außerhalb des gültigen Bereichs liegen oder ein anderer ungültiger Parameterwert vorliegt.

Anmerkung

Wenn beim Durchsuchen von Hashes die Parameter StartIndex und EndIndex einen anderen Datentyp als integer haben, wird die Position der Start- und End-Elemente aus den angegebenen Indizes berechnet. Hierin unterscheidet sich das Durchsuchen von Hashes mit der Funktion find() vom Durchsuchen eines assoziativen Arrays mit der Methode :find().

Beispiel 

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();
}

Siehe auch

Eingebaute Funktion sort()

Methode :find()