getNextToken()

Die Systemfunktion 'strLib.getNextToken()' durchsucht eine Unterzeichenfolge nach einem Token und kopiert dieses Token in ein Zielelement.

Tokens sind Zeichenfolgen, die durch Begrenzungszeichen voneinander getrennt sind. Wenn beispielsweise Leerzeichen (" ") und Komma (",") als Begrenzer definiert sind, kann die Zeichenfolge "CALL PROGRAM ARG1,ARG2,ARG3" in die fünf Tokens "CALL", "PROGRAM", "ARG1", "ARG2" und "ARG3" unterteilt werden. Die Funktion ruft die Tokens einzeln nacheinander ab. Der Abruf basiert auf einem Indexwert, der auf die Position des jeweiligen Tokens in der Zeichenfolge verweist.

Syntax

Die Funktion 'strLib.getNextToken()' ist überlastet, sodass Sie denselben Funktionsnamen mit unterschiedlichen Konfigurationen von Parametern und Rückgabewerten aufrufen können. Das folgende Format der Funktion stellt die bevorzugte Variante dar:

  strLib.getNextToken(
    Quelle STRING | CHAR | DBCHAR | MBCHAR | UNICODE inOut,
    Index INT inOut,
    Begrenzungszeichen STRING | CHAR | DBCHAR | MBCHAR | UNICODE in)
  returns (Token STRING? | CHAR? | DBCHAR? | MBCHAR? | UNICODE?)
Quelle
Bei der Eingabe kann es sich um einen beliebigen Wert handeln, der mit einem der vorstehenden Typen zuordnungskompatibel ist.
Index
Eine Variable vom Typ INT, die das Startbyte angibt, an dem die Suche nach einem Token beginnen soll, wobei das erste Byte in Quelle den Wert 1 hat. Wird ein Token gefunden, wird der Wert in Index in den Index des ersten Bytes geändert, das auf das Token folgt. Wird kein Token gefunden, bleibt Index unverändert.
Begrenzungszeichen
Mindestens ein Begrenzungszeichen. Mehrere Begrenzungszeichen werden nicht durch ein Zeichen voneinander getrennt. Dies muss eine Variable oder ein Literal desselben Typs wie Quelle sein.
Token
Wird ein Token gefunden, wird es als derselbe Typ zurückgegeben wie der Typ, der Quelle zugeordnet wurde. Wird kein Token gefunden, gibt die Funktion einen Nullwert zurück.
Ergebnis
Eine ganze Zahl (INT), die die Anzahl der Zeichen im Token angibt. Die folgenden Zeichen für Ergebnis haben eine besondere Bedeutung:
null
Die Funktion hat kein Token gefunden.
-1
Das Token wurde beim Kopieren in Ziel abgeschnitten.

Das folgende Format ist zwecks Kompatibilität mit früheren Versionen verfügbar:

  strLib.getNextToken(
    Ziel CHAR | DBCHAR | MBCHAR | UNICODE inOut,
    Quelle CHAR | DBCHAR | MBCHAR | UNICODE in,
    Index INT inOut,
    Länge_der_Unterzeichenfolge INT inOut,
    Begrenzungszeichen STRING in)
  returns (Ergebnis INT)
Ziel
Wenn die Funktion ein Token findet, stellt sie dieses Token in die Zielvariable. Das Ziel muss mit mindestens einem der gezeigten Typen zuordnungskompatibel sein.
Quelle
Die Eingabe muss denselben Typ haben wie Ziel.
Index
Eine Variable vom Typ INT, die das Startbyte in Quelle angibt, an dem die Suche nach einem Token beginnen soll, wobei das erste Byte den Wert 1 hat. Wird ein Token gefunden, wird der Wert in Index in den Index des ersten Bytes geändert, das auf das Token folgt. Wird kein Token gefunden, bleibt Index unverändert.
Länge_der_Unterzeichenfolge
Eine ganze Zahl (INT), die die Anzahl der Byte in der geprüften Unterzeichenfolge von Quelle angibt. Wird ein Token gefunden, wird der Wert in Länge_der_Unterzeichenfolge in die Anzahl der Byte in der Unterzeichenfolge geändert, die nach dem zurückgegebenen Token beginnt.
Begrenzungszeichen
Mindestens ein Begrenzungszeichen. Mehrere Begrenzungszeichen werden nicht durch ein Zeichen voneinander getrennt. Bei der Eingabe kann es sich um eine beliebige Variable oder einen beliebigen Ausdruck handeln, die/der mit dem Typ STRING zuordnungskompatibel ist.
Ergebnis
Eine ganze Zahl (INT), die die Anzahl der Zeichen im Token angibt. Die folgenden Zeichen für Ergebnis haben eine besondere Bedeutung:
0
Die Funktion hat kein Token gefunden.
-1
Das Token wurde beim Kopieren in Ziel abgeschnitten.

Beispiel

In diesem Beispiel verwendet das Programm den aktualisierten Wert von i, um eine Zeichenfolge in einer Schleife zu durchlaufen und die Tokens in einer Feldgruppe zu speichern.

   commandLine string = "CALL PROG1 arg1,arg2";
   delimiters string = " ,"; // Leerzeichen und Komma als Begrenzungszeichen
   i int = 1;
   max int;
   tokens string[0];
   token string? = "";
 
   function main()
      max = strLib.byteLen(commandLine);
      
      // Verarbeitung endet, wenn die Funktion 'getNextToken' eine Null zurückgibt
      while(i < max && token != null)
         token = StrLib.getNextToken(commandLine, i, delimiters);
         if (token != null)        
            tokens.appendElement(token);
         end
      end
    end

Fehlerbedingungen

Das bevorzugte Format (drei Parameter) der Funktion gibt die Ausnahmebedingung 'egl.core.IndexOutOfBoundsException' zurück, wenn eine der folgenden Bedingungen zutrifft:
  • Index ist kleiner als 1.
  • Index ist größer als die Länge der Quellenzeichenfolge.
  • Index ist gerade, und Quelle hat den Typ UNICODE oder DBCHAR.
Das Kompatibilitätsformat (fünf Parameter) der Funktion löst im Falle eines Fehlers eine Laufzeitausnahmebedingung (RuntimeException) aus, sofern die Ausführung nicht im V6-Ausnahmemodus erfolgt. Die Ausführung erfolgt im V6-Ausnahmemodus, wenn alle folgenden Bedingungen erfüllt sind:
  • Die Programmeigenschaft 'v60ExceptionCompatibility' ist auf YES gesetzt.
  • Eine der folgenden Bedingungen ist erfüllt:
    • Die Systemvariable 'vgvar.handleSysLibErrors' ist auf 1 gesetzt. ODER
    • Die Funktion wurde über einen try-Block aufgerufen.
Im V6-Ausnahmemodus werden die folgenden Werte in 'sysVar.errorCode' zurückgegeben:
8
Index ist kleiner als 1 oder größer als die Anzahl der Byte in der geprüften Unterzeichenfolge.
12
Länge_der_Unterzeichenfolge ist kleiner als 0.
20
Der Wert in Index für eine Zeichenfolge vom Typ DBCHAR oder UNICODE verweist auf die Mitte eines Doppelbytezeichens.
24
Der Wert in Länge_der_Unterzeichenfolge für eine Zeichenfolge vom Typ DBCHAR oder UNICODE ist ungerade (Doppelbytelängen müssen immer gerade sein).

Hinweise zur Kompatibilität

Tabelle 1. Hinweise zur Kompatibilität
Plattform Problem
JavaScript-Generierung Die Funktion 'strLib.getNextToken()' wird nicht unterstützt.

Feedback