Methoden zur Verwendung von Objekten der Klasse String.

Methoden zur Verwendung von Objekten der Klasse String.

String-Objekte werden intern als UTF-8 codiert erwartet.

String-Objekte mit anders kodierten Daten können zu unerwarteten Ergebnissen führen!

Bitte beachten Sie den fundamentalen Unterschied zwischen Strings vom Typ String und char*!

char* ist ein Stück Arbeitsspeicher, das Sie zuvor mit alloc reserviert haben. Der Inhalt dieses Stück Speichers kann bis zur Größe dieses Speichers gefüllt werden, aber nicht weiter! Eine Ascii-0 innerhalb dieses reservierten Speicherbereiches signalisiert das Ende Ihrer Zeichenkette (aber nicht zwangsläufig des Ende des reservierten Speicherbereiches).

Die folgende Tabelle zeigt eine mit der Länge 5 allokierte char*-Zeichenkette. alloc hat dafür die Adresse 1000 gewählt und 5 Bytes für den Inhalt reserviert. Mit strcpy (my_char, "FUN"); wurden vier der Bytes dieses Bereiches gefüllt, drei mit den Zeichen und eins am Ende mit \0 zur Markierung, dass hier der Text endet:
Adresse 1000 1001 1002 1003 1004
Inhalt F U N \0 undefinert

String dagegen ist ein Objekt, das viel einfacher ist. Über die Länge und den Speicherort seines Inhaltes müssen Sie sich keine Gedanken machen. Das macht dieses Objekt vollkommen alleine.
Adresse 1000 ... char* mit Inhalt
Inhalt Interne Objekt-Informationen
...
Aktuelle Größe des Inhaltsspeichers
char*-Adresse auf den Inhalt		 ... FUN\0
Auf der anderen Seite können Sie in der Regel nicht einfach mit char* auf das Objekt zugreifen. Dort liegt der Inhalt nämlich nicht. Um auf den char*-Inhalt eines Strings zuzugreifen, verwenden Sie die Funktion string::get. Eine Vielzahl von cScript-Funktionen sind aber in der Lage, die nötige Umrechnung von String in char* selbständig zu machen. Beachten Sie dazu die jewelige Beschreibung der Funktionsparameter. Steht dort String oder char*, können Sie beide Datentypen verwenden, sonst nur den angegeben Datentypen. Und, bitte!, Konstanten der Art "abcde" sind keine Strings sondern char*!

Zeichenpositionen innerhalb eines Strings werden immer 0-basiert gezählt.

Da UTF-8-Zeichen innerhalb eines Strings aus bis zu 4 Einzel-Bytes bestehen können, gibt es einen Unterschied zwischen dem sogenannten Zeichen- oder UTF-8- und dem "wirklichen" oder Byte-Index eines Zeichens : Weil der Buchstabe ä aus zwei UTF8-Zeichen besteht, hat das n in "Hände" zwar den Zeichenindex 2 aber den Byte-Index 3.

Soweit nichts anders angegeben, verwenden die String-Funktionen den Zeichenindex.

static String string::alloc(char* value = "", ...)

Erzeuge einen neuen selbstverwalteten String. Das Objekt muss mit string::release wieder gelöscht werden.

Name Typ Default Beschreibung
Return String   Ein neues Objekt von Typ String
value String oder char* "" Initialwert des Strings. Der Wert wird kopiert.
Der Wert darf Format-Tags enthalten, mehr dazu dazu siehe hier. Für jeden %-Marker wird (in der richtigen Reihenfolge und vom richtigen Datentyp) eine weitere Eingabevariable erwartet.
seit v4.1 R16516
... Abhängig von den Markierungen - [Ab v4.1 R16516] Werte oder Variablen gemäß den %-Tags in value
 
String		str	= string::alloc ();

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static void string::release(String str)

Löschen eines mit string::alloc erzeugten String-Objektes

Name Typ Default Beschreibung
str String - Lösche dieses Objekt aus dem Speicher 
String		str	= string::alloc ();
 	:
 	:
string::release (str);

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::set(
  String target,
  String format,
  ...)

Setze den Wert des Strings

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
target String - Stringobjekt, dessen Wert gesetzt werden soll
format String oder char* - Neuer Wert des Strings. Der Wert wird kopiert.
Der Wert darf Format-Tags enthalten, mehr dazu dazu siehe hier. Für jeden %-Marker wird (in der richtigen Reihenfolge und vom richtigen Datentyp) eine weitere Eingabevariable erwartet.
... Abhängig von den Markierungen - Werte oder Variablen gemäß den %-Tags in format 
int main(
{
    String str = string::alloc();

    string::set(str, "Hallo Welt");
    showmessage(str);

    string::release (str);

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static char* string::get(String str)

Hole den Inhalt eines Strings als char*.

Name Typ Default Beschreibung
Return char*   Der Inhalt des Objektes als 0-terminierter C-String vo Typ char*.

Der Rückgabewert darf nur gelesen werden! Er darf niemals (in Worten : NIEMALS) direkt geändert werden. Änderungen an diesem char* führen zum sofortigen Absturz von InDesign®.

Mit strcpy kann der Inhalt eines Strings in einen genügend groß allokierten char*-String übernommen werden.
str String - Stringobjekt, dessen Inhalt ermittelt werden soll
#include "internal/text.h"
String		str	= string::alloc ();

textmodel::gettext (str, 0, kEnd);
showmessage (string::get (str));

string::release (str);

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static char* string::data(String str)

Inhalt eines String-Objektes. Das Ergebnis kann 0-Bytes enthalten. "Strings" mit 0-Bytes können sinnvoll sein zum Transport binärer Dateien.

Name Typ Default Beschreibung
Return int   Inhalt eines String-Objektes. Das Ergebnis kann 0-Bytes enthalten.
str String - Gültiger String

Lies eine Binärdatei und schreibe das Ergebnis in eine andere Datei. (Bitte beachten Sie: Das Sktipt dient lediglich zur Demonstration, im Produktivfall würden Sie hier besser die Funktion file::duplicate verwenden!) 

int main ()
{
    String		str		= string::alloc ();
    int 		fileRef;
    int			fileSize;

    // Read file
    fileRef 	= file::open("$DESKTOP/b1.jpg", "r");
    fileSize 	= file::read_str (fileRef, str, 4);
    file::close (fileRef);

    // Write read data to another file
    fileRef = file::open("$DESKTOP/b2.jpg", "w");
    file::write (fileRef, string::data (str), fileSize);
    file::close (fileRef);

    return 0;
}

v4.1 R22123, 28. März 2018

priint:comet InDesign® Plug-Ins, comet_pdf

static int string::length(String str, int countBytes = 1)

Aktuelle Länge des Strings.

Name Typ Default Beschreibung
Return int   Länge des Strings in Bytes oder Buchstaben
str String - Stringobjekt, dessen Länge ermittelt werden soll
countBytes int 1 Welche Länge soll ermittelt werden?

0 : Buchstaben, Mehrbyte-UTF8-Zeichen zählen als ein Zeichen

1 : Bytes 
String		str	= string::alloc ();
int		len;
 	:
textmodel::gettext (str);
len = string::length (str);
 	:
string::release (str);

Version 1.1.5

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::append(
  String target,
  String toAppend,
  ...)

Anfügen an einen String

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
target String - Stringobjekt, an das angefügt werden soll
toAppend String oder char* - Wert, der angefügt werden soll.

Der Wert darf Format-Tags enthalten, mehr dazu dazu siehe hier. Für jeden %-Marker wird (in der richtigen Reihenfolge und vom richtigen Datentyp) eine weitere Eingabevariable erwartet.
... Abhängig von den Markierungen - Werte oder Variablen gemäß den %-Tags in format since v4.1 R22201 
int main()
{
    String 	str = string::alloc("aaa");

    string::append(str, "bbb %d", 123);
    showmessage(str);	//shows "aaabbb 123"

    string::release(str);

    return 0;
}

v4.1 R19023
%-Markierungen seit v4.1 R22201, 10. Apr 2018

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::insert(
  String target,
  int position,
  String input)

Einfügen in einen String

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
target String - Stringobjekt, in das eingefügt werden soll
position int - Position an der eingefügt werden soll
-1: Am Ende
input String oder char* - Wert der eingefügt werden soll 
int main()
{
    String 	target 	= string::alloc();
    String 	input 	= string::alloc();
    int 	length 	= 0;

    string::set(target, "AAACCC");
    string::set(input, "BBB");

    //insert at position 3 (middle)
    string::insert(target, 3, input);
    showmessage(target);		//shows "AAABBBCCC"

    //insert at the end
    length = string::length(target, 0);
    string::insert(target, length, "DDD");
    showmessage(target);		//shows "AAABBBCCCDDD"

    string::release(target);
    string::release(input);

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::erase(
  String input,
  int position,
  int length = -1)

Löschen von Zeichen aus einem String

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
input String - Stringobjekt, aus dem gelöscht werden soll
position int - Position ab der gelöscht werden soll
length int -1 Wieviele Zeichen sollen gelöscht werden (-1 = bis Ende)? 
int main()
{
    String target = string::alloc();

    string::set(target, "Hello World");

    string::erase(target, 4, 1);
    showmessage(target);		//shows "Hell World"

    string::erase(target, 4, -1);
    showmessage(target);		//shows "Hell"

    string::release(target);

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int string::find(
  String searchIn,
  char* searchFor,
  int fromPosition = 0,
  int* matchLength = 0,
  int* matches = 0,
  int compile_options = 0,
  int study_options = 0,
  int exec_options = 0)

Suchen von Strings in einem String

Name Typ Default Beschreibung
Return int   -1 : nicht gefunden

sonst : Position des gesuchten Strings
searchIn String - Stringobjekt, in dem gesucht werden soll
searchFor String oder char* - Suche nach diesem Unterstring. Muss ungleich "" sein.

Der Suchstring darf ein regulärer Ausdruck sein.
Reguläre Ausdrücke werden mit dem Präfix "regexp:" oder "pcre:" gekennzeichnet.
fromPosition int 0 Ab dieser Position soll gesucht werden
matchLength int * 0 (Nur bei Verwendung regulärer Ausdrücke)
Länge des gefundenen Ausdruckes.
matches int * 0 (Nur bei Verwendung regulärer Ausdrücke)
Int-Array mit Angaben über das Ergebnis

Das Array enthält jeweils Startposition und Länge des nächsten gefundenen Ausdruckes. Im ersten Zahlenpaar stehen die Angaben für den gesamten Ausdruck. Die folgenden Paare enthalten jeweils die Angaben des i-ten Unterausdruckes. Unterausdrücke sind die in runde Klammern eingeschlossenen Teile des regulären Ausdruckes, also etwa ([a-z]{3,7}). Abgeschlossen wird das Feld durch das Paar (-1, 0).

Beachten Sie bitte, dass Unterausdrücke durchaus die Länge 0 liefern können. Wird der reguläre Ausdruck ([0-9])([a-z]{0,7})([0-9])) auf den Text "14" angewendet, ist nämlich der zweite Ausdruck leer.

Bei einer Angabe ungleich 0 muss das Array mind. um 4 größer sein als die doppelte Anzahl der Klammerausdrücke im regulären Ausdruck - jeweils zwei int's für den Starteintrag, die n Subentries und die Ende-Markierung.

Eine einfache Definition eines Matches-Arrays für einen regulären Ausdruck mit 4 Untereinträgen. 

int matches [6];
compile_options int 0 Zusatzoptionen beim Kompilieren des regulären Ausdruckes, siehe hier
study_options int 0 Zusatzoptionen beim Untersuchen des kompilierten regulären Ausdruckes, siehe hier
exec_options int 0 Zusatzoptionen beim Suchen des regulären Ausdruckes, siehe hier 
int main()
{
    String myString = string::alloc();
    int position = 0;

    string::set(myString, "123 444 555");
    position = string::find(myString, "444", 0);
    showmessage("Found at %d", position);		//Shows "Found at 4"
    string::release(myString);

    return 0;
}

//find regex with loop
int main()
{
    String myString = string::alloc();
    String foundString = string::alloc();
    int position = 0;
    int matchLength = 0;

    string::set(myString, "ÄÄÄ 123 øøø 444");
    while (1) {
        //find blocks of numbers
        position = string::find(myString, "pcre:[0-9]+", position + matchLength, &matchLength);
        if (position < 0) { break; }
        if (matchLength <= 0) { break; }
        string::set(foundString, string::substring(myString, position, matchLength));

        showmessage("found match (with loop) at %d with length %d: %s", position, matchLength, foundString);
    }
    string::release(myString);
    string::release(foundString);

    return 0;
}

v4.1 R16516
compile_options, study_options, exec_options seit v4.0.5 R20456, 10. Okt 2017

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

get_realindex
get_utf8index

static int string::rfind(
  String searchIn,
  char* searchFor,
  int fromPosition = -1)

Rückwärts-Suche in einem String.

Name Typ Default Beschreibung
Return int   -1 : nicht gefunden

sonst : Position des gesuchten Strings
searchIn String - Stringobjekt, in dem gesucht werden soll
searchFor String oder char* - Suche rückwärts nach diesem Unterstring. Muss ungleich "" sein.

Achtung : Im Gegensatz zu string::find unterstützt die Rückwärtssuche keine regulären Ausdrücke!

fromPosition int 0 Ab dieser Position soll rückwärts gesucht werden

< 0 : Ende des Strings

v5.0 R35400, 27. Sep 2024

priint:comet InDesign® Plug-Ins, comet_pdf

get_realindex
get_utf8index

static String string::replace(
  String input,
  String searchFor,
  String replaceBy,
  int position = 0,
  int replaceAll = 1,
  int compile_options = 0,
  int study_options = 0,
  int exec_options = 0)

Ersetzen von Substrings in einem String

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
input String - Stringobjekt, in dem gesucht werden soll
searchFor String oder char* - Suche nach diesem Unterstring. Muss ungleich "" sein.

Der Suchstring darf ein regulärer Ausdruck sein.
Reguläre Ausdrücke werden mit dem Präfix "regexp:" oder "pcre:" gekennzeichnet.
replaceBy String oder char* - Dieser String ersetzt die gefundenen Unterstrings.
position int 0 Ab dieser Position soll gesucht werden
replaceAll int 1 Sollen alle Vorkommen (1) oder nur das erste gefundene (0) ersetzt werden?.
compile_options int 0 Zusatzoptionen beim Kompilieren des regulären Ausdruckes, siehe hier
study_options int 0 Zusatzoptionen beim Untersuchen des kompilierten regulären Ausdruckes, siehe hier
exec_options int 0 Zusatzoptionen beim Suchen des regulären Ausdruckes, siehe hier 
int main()
{
    String myString = string::alloc();

    string::set(myString, "Hello Leo, how are you today Leo?");
    string::replace(myString, "Leo", "Paul");
    showmessage(myString); //shows "Hello Paul, how are you today Paul?"

    return 0;
}

//replace all white space in a string with underscores
int main()
{
    String myString = string::alloc();

    string::set(myString, "Hello Leo, how are you today Leo?");
    string::replace(myString, "pcre:[\\s]+", "_");
    showmessage(myString); //shows "Hello_Leo,_how_are_you_today_Leo?"

    return 0;
}

v4.1 R16516
compile_options, study_options, exec_options seit v4.0.5 R20456, 10. Okt 2017

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

String string::replace_multis(String str, String repl = 0)

Entferne Mehrfach-Zeichen aus dem String. Die Funktion ersetzt für jedes Zeichen der Zeichenkette repl alle Wiederholungen in span[src]{str}. Mit dem repl-String "abc" werden alle alle "aa", "bb", "cc", "aaa", "bbb", "ccc", ... auf jeweils ein Zeichen verkürzt.

Name Typ Default Beschreibung
Return char*   Der Zeiger auf den Eingabestring wird wieder zurückgegeben.
str char* - Eingabestring
repl char* 0 String mit den einzelnen Zeichen, die ersetzt werden sollen. Der String darf nur reine ASCII-Zeichen enthalten!

0 : Ersetze alle Mehrfach-Leerzeichen durch einfache Leerzeichen

Hier ein Beispiel eines Stringvergleich-Skriptes 

char * prepare_string (char * str)
{
    char		*	result = alloc (strlen (str)+10);

    get_netweight_str (result, str, 1, 1);
    strreplace (result, "\t", "  ");
    strreplace_multis (result, " \t");

    return result;
}

int main ()
{
    return strcmp (prepare_string (gDocumentValue), prepare_string (gDataPoolValue));
}

v4.1, R23900, 1. Oct. 2018

priint:comet InDesign® Plug-Ins, comet_pdf

static char* string::replace_all(
  String str,
  char* search,
  char* repl)

Ersetze alle Vorkommen eines Substrings durch einen anderen Substring.

Name Typ Default Beschreibung
Return char*   Der neue Inhalt des Strings als 0-terminierter C-String.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
str String - Stringobjekt, dessen Inhalt geändert werden soll
search char* oder String - Suchenstring
rep char* oder String - Ersetzenstring 
String		str	= string::alloc ();

textmodel::gettext (str, 0, kEnd);
showmessage (string::replace_all (str, "aa", "a"));

string::release (str);

search und repl als Strings seit v4.1.8 R29550

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::substring(
  String input,
  int position,
  int length = -1)

Extrahieren eines Teilstrings aus einem String

Name Typ Default Beschreibung
Return String   Substring
Das Ergebnis ist nur direkt nach dem Aufruf gültig. Wenn es weiter verwendet werden soll, muss es in einen anderen String kopiert werden
input String - Stringobjekt, aus dem extrahiert wird
position int - Startposition des Teilstrings
length int -1 Länge des Teilstrings (-1 = bis Ende) 
int main ()
{
    String str = string::alloc("Hallo Welt");
    String sub = string::alloc();

    sub = string::substring(str, 0, 5);
    showmessage(sub); //shows "Hallo"

    string::release(str);
    string::release(sub);

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int string::compare(
  String first,
  String second,
  int maxLength = -1,
  int netweight = 0)

Alpha-numerischer Vergleich zweier Strings.

Der Text eines leeren Textplatzhalters ist nicht leer sondern ein unsichtbares Leerzeichen (<0x200B>). (Ein Platzhalter kann keinen leeren Text enthalten, dann wäre auch der Platzhalter weg.) Das showmessage im folgenden Skripttext wird also nie erreicht :

int main ()
{
    String docText = string::alloc();
    textmodel::gettext(docText);

    if (string::compare(docText, "") == 0) {
        showmessage("Empty!");
    }

    string::release(docText);

    return 0;
}

Der Dokumenttext muss in dieser Situation gegen das unsichtbare Leerzeichen (UTF8 = E2 80 8B, Unicode = 200B) geprüft werden :

int main ()
{
    String docText = string::alloc();
    textmodel::gettext(docText);

    if (string::compare(docText, "\xE2\x80\x8B") == 0) {
        showmessage("Empty!");
    }

    string::release(docText);

    return 0;
}

Verwenden Sie für das Abholen des Dokumenttextes ein TaggedText-Format, wird das unsichtbare Leerzeichen Unicode-codiert, allerdings ist der TaggedText etwas länger und enthält das Absatzformat, was einen direkten Vergleich erschwert, da es unterschiedlich sein kann :

#include "internal/text.h" int main ()
{
    String docText = string::alloc();
    textmodel::gettext(docText, 0, -1, kExportTT);

    if (string::compare(docText, "%!TT<ParaStyle:NormalParagraphStyle><0x200B>") == 0) {
        showmessage("Empty!");
    }

    string::release(docText);

    return 0;
}

Zum Vergleich der "Netto"-Strings können Sie die Funktion mit netWeight = 1 verwenden.

Name Typ Default Beschreibung
Return int   < 0 : first < second
Return int   = 0 : first == second
Return int   > 0 : first > second
first String oder char* - Erster String im Vergleich
second String oder char* - Zweiter String im Vergleich
maxLength int -1 Vergleiche die Strings bis zu dieser Länge.
Ist einer der Strings kürzer als maxLength, wird der Vergleich bereits am Ende dieses Strings abgebrochen.
netweight int 0 "Netto"inhalte der Strings vergleichen.

Die Netto-Werte der Strings werden wie folgt beberechnet :
  • Leerstrings werden durch ein unsichtbares Leerzeichen (Unicode 0x200B) ersetzt.
  • UTF-8-Zeichen werden einheitlich in <0xXXXX>-Tags übersetzt.
  • Beginnt der Text mit %!TT wird (wenn vorhanden) das direkt darauf folgende ParaStyle-Tag entfernt.
  • Alle weiteren ParaStyles werden durch Absatztrenner ersetzt.
  • Alle <nl:> werden durch Absatztrenner ersetzt.
  • Alle übrigen TaggedText-Tags werden aus dem Text entfernt.
  • Alle doppelten Anführungszeichen werden durch " ersetzt und alle einfachen durch '.
  • Alle Arten Leerzeichen (Unicode 0x2000 - 0x200F) werden jeweils durch Blank ersetzt.
  • Alle Arten Trennzeichen (Unicode 0x2010 - 0x2016) werden jewels durch Minus ersetzt.
#include "internal/text.h"

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::upper(String input)

String in Großbuchstaben umwandeln.

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
input String - String, der in Großbuchstaben umgewandelt werden soll.

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::lower(String input)

String in Kleinbuchstaben umwandlen.

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
input String - String, der in Kleinbuchstaben umgewandelt werden soll.

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::reverse(String input)

Spiegle einen String

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
input String - String der umgekehrt werden soll.

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf

static String string::trim(String input, char toTrim = 0)

Entferne alle Auftreten eines bestimmten Zeichens am Anfang und am Ende einer Zeichenkette.

Name Typ Default Beschreibung
Return String   Geänderter Eingabestring
input String - String der getrimmt werden soll.
toTrim char 0 Zeichen, das entfernt werden soll. Es sind nur Ein-Byte-Zeichen mit einem Ascii-Wert < 128 erlaubt. Höherwertige Ascii- oder Unicode-Zeichen können zum Absturz von InDesign® führen.

0 : Entferne alle unsichtbaren Zeichen (Blanks, Tabs, Zeilentrenner, ...) am Anfang und am Ende des Strings

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int (
  String input,
  char delimiter,
  int checkIfEmpty = 0)

Bei der Verwendung von UTF-8-Strings ist die Funktion extrem toxisch und sollte dringend durch string::get_token_count ersetzt werden:

  1. Ändern Sie den Funktionsnamen in string::get_token_count.
  2. Ändern die die einfachen Anführungszeichen um den Trenner in doppelte Anführungszeichen.

Bitte verwenden Sie die Funktion string::get_token_count.

static String (
  String input,
  char delimiter,
  int tokenIndex)

Bei der Verwendung von UTF-8-Strings ist die Funktion extrem toxisch und sollte dringend durch string::get_token ersetzt werden:

  1. Ändern Sie den Funktionsnamen in string::get_token.
  2. Ändern die die einfachen Anführungszeichen um den Trenner in doppelte Anführungszeichen.

Bitte verwenden Sie die Funktion string::get_token.

static int string::get_token_count(String str, String delimiter)

Aus wievielen, nach einem bestimmten Wort getrennten Teilen (den sogenannenten Tokens) besteht eine Zeichenkette? Übliche Anwendungen sind tabulatorgetrennte Textzeilen oder Dateipfade. Zur Vereinfachung der Aufrufe dürfen beide Zeichenketten sowahl als String als auch als char* angegeben werden.

Name Typ Default Beschreibung
Return int   Anzahl der durch delimiter getrennten Tokens im Eingabenstring.
str String oder char* - Zu durchsuchender String
delimiter String oder char* - Trenner. Der Trenner darf UTF-8-Zeichen enthalten und mehrere Zeichen lang sein.

Das Beispiel zählt verschieden Tokens im String 'Matthias'. 

String	str = string::alloc ();

...

string::set (str, "Matthias");
string::get_token_count (str, "a") // returns 3
string::get_token_count (str, "i") // returns 2
string::get_token_count (str, " ") // returns 1

v4.1.8 R29200, 4 Okt. 2021

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::get_token(
  String str,
  String delimiter,
  int nth)

Hole das n-te Wort des durch einen festgelegten Trenner unterteilten Strings. übliche Anwendungen sind tabulatorgetrennte Textzeilen oder Dateipfade. Zur Vereinfachung der Aufrufe dürfen beide Zeichenketten sowahl als String als auch als char* angegeben werden. Beachten Sie aber bitte, dass das Ergebnis in jedem Fall vom Typ String ist.

Name Typ Default Beschreibung
Return String   Gefundes Token. Wurde kein weiteres Token gefunden, ist das Ergebnis leer. Das Ergebnis ist nur direkt nach dem Aufruf gültig. Wenn es weiter verwendet werden soll, muss es in einen anderen String kopiert werden.
str String oder char* - Zu durchsuchender String
delimiter String oder char* - Trenner. Der Trenner darf UTF-8-Zeichen enthalten und mehrere Zeichen lang sein.
nth int - 0-basierter Index des Tokens

Ermittle verschiedene Tokens eines Wortes: 

int main ()
{
    String	str = string::alloc ("Matthias");

    wlog ("", "'%s' ?= 'M'\n", 			string::get_token (str, "a", 0));	// ergibt M
    wlog ("", "'%s' ?= 'tthi'\n",		string::get_token (str, "a", 1));	// ergibt tthi
    wlog ("", "'%s' ?= 's'\n", 			string::get_token (str, "a", 2));	// ergibt s
    wlog ("", "'%s' ?= ''\n", 			string::get_token (str, "a", 3));	// ergibt den Leerstring
    wlog ("", "'%s' ?= 'Matthias'\n", 	string::get_token (str, "x", 0));	// ergibt Matthias
    wlog ("", "'%s' ?= ''\n", 			string::get_token (str, "x", 3));	// ergibt den Leerstring

    return 0;
}

v4.1.8 R29200, 4 Okt. 2021

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static int string::to_int(String input)

Umwandlung eines Ganzzahlen-Zahlenstring in eine Zahl. Der String darf auch Hexadezimal- oder Oktalzahlen enthalten. Hexadezimalzahlen beginnen mit "0x".

Name Typ Default Beschreibung
Return int   Zahlenwert des Strings
input String - Zahlenstring 
//Different formats for representing the same number
int main()
{
    String myString = string::alloc();
    int stringValue = 0;

    string::set(myString, "255");
    stringValue = string::to_int(myString);
    showmessage("%d", stringValue);		//shows 255

    string::set(myString, "0xff");
    stringValue = string::to_int(myString);
    showmessage("%d", stringValue);		//shows 255

    string::set(myString, "0xFF");
    stringValue = string::to_int(myString);
    showmessage("%d", stringValue);		//shows 255

    string::set(myString, "0xFFTTT");
    stringValue = string::to_int(myString);
    showmessage("%d", stringValue);		//shows 255

    string::release(myString);

    return 0;
}

Der Datentyp int ist 64 Bit breit. Hier ein Beispiel mit Zahlen, deren Darstellung mehr als 32 Bit benötigt. 

int main ()
{
    int a = 6917529027641081856;
    String str = string::alloc();
    string::from_int(str, a);

    //the messages below show the same value
    showmessage("Int value of a is %d", a);
    showmessage("Int value of str is %d", string::to_int(str));

    string::release(str);

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::from_int(int value)

Umwandlung einer Zahl in einen String. Aus der Zahl i wird der String 'i' gemacht.

Name Typ Default Beschreibung
Return String   Zahl als String.
Das Ergebnis ist nur direkt nach dem Aufruf gültig. Wenn es weiter verwendet werden soll, muss es in einen anderen String kopiert werden
value int - Zahlwert der in einen String umgewandelt werden soll 
int main ()
{
    int a = 1234;
    showmessage(string::from_int(a));

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static float string::to_float(String input)

Umwandlung eines float-Zahlenstrings in eine float-Zahl

Name Typ Default Beschreibung
Return float   Float-Zahlenwert des Strings
input String - Float-Zahlenstring.
Die Zahl kann mit Komma oder Punkt geschrieben sein, zwischen den Tausendern sind keine Trenner erlaubt. 
//Different formats for representing the same number
int main ()
{
    String myString = string::alloc();

    string::set(myString, "12.3");
    showmessage("%f", string::to_float(myString));		//shows 12.3000

    string::set(myString, "12,3");
    showmessage("%f", string::to_float(myString));		//shows 12.3000

    string::set(myString, "1.23e+1");
    showmessage("%f", string::to_float(myString));		//shows 12.3000

    string::set(myString, "123.e-1");
    showmessage("%f", string::to_float(myString));		//shows 12.3000

    string::release(myString);

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::from_float(float value, String format)

Umwandlung einer float-Zahl in einen String.

Name Typ Default Beschreibung
Return String   Float-Zahl als String.
Das Ergebnis ist nur direkt nach dem Aufruf gültig. Wenn es weiter verwendet werden soll, muss es in einen anderen String kopiert werden
value float - Float-Zahlwert der in einen String umgewandelt werden soll
format String oder char* "%f" Formatierungsangabe, i. A. "%f".
Weitere Formatierungen finden Sie in jeder Dokumentation über die C-Funktion sprintf. 
int main ()
{
    float f = 12.34567;
    showmessage(string::from_float(f, "%.2f"));	//shows 12.35

    return 0;
}

v4.1 R16516

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::get_netweight(
  String source,
  int convertUniTags = 0,
  int replaceTypos = 0,
  int replaceHTMLEntities = 0)

Ermittle den Nettowert eines Strings. Die Netto-Werte der Strings werden wie folgt berechnet :

Name Typ Default Beschreibung
Return String   String mit dem wie oben beschrieben gekürzten Eingabetext.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
source String oder char* - String, dessen Nettowert berechnet werden soll
convertUniTags int 0 Sollen Unicode-Tags der Form <0x200B> automatisch ersetzt werden?

0 : Nein
sonst : Ja
replaceTypos int 0 Sollen Anführungs-, Leer- und Trennzeichen vereinheitlich werden?

0 : Nein
sonst : Ja
replaceHTMLEntities int 0 [Ab v5.0 R37000] Sollen HTML-Entities durch ihre UTF-8 Zeichen ersetzt werden?

0 : Nein
sonst : Ja. Alle HTML-Entities der Formen &auml;, &#228; und &#xE4; werden durch ihr Unicode-Zeichen (in diesem Fall ä) ersetzt. 
int main ()
{
    String source = string::alloc("ÄÖü");
    String netWeight = string::alloc();

    string::set(netWeight, string::get_netweight(source));
    showmessage(netWeight);		//Shows "<0x00C4><0x00D6><0x00DC>"

    string::release(source);
    string::release(netWeight);

    return 0;
}

Hier einige Ergebenisse von get_netweight_str mit der Eingabe "--Hallo <0x275D>Hällo<0x275E>--". Die gleichen Ergebnisse erhalten Sie auch mit der unkodierten Eingabe "--Hallo ❝Hällo❞--". 

0, 0 --Hallo <0x275D>H<0x00E4>llo<0x275E>--
0, 1 --Hallo "H<0x00E4>llo&"--
1, 0 --Hallo ❝Hällo❞--
1, 1 --Hallo "Hällo"--

v4.1 R16536
Parameter replaceHTMLEntities seit v5.0 R37000

priint:comet InDesign® Plug-Ins, comet_pdf

comet.strutils.getNetWeight

static String string::md5(String input, int upperCase = 0)

Berechne den md5hash eines Textes.

Name Typ Default Beschreibung
Return String   32-stelliger md5hash des Textes.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
text String oder char* - Beliebiger String
upperCase int 0 Groß- oder Kleinbuchstaben für die Hex-Zahlen verwenden?

0 : Kleinbuchstaben
1 : Großbuchstaben

Berechne den md5hash eines Strings. 

int main () {
    String str = string::alloc("Hallo Welt");
    String md5;
    md5 = string::md5(str);

    if (md5 != 0) {
        showmessage(md5);
    }

    string::release(str);

    return 0;
}

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

static String string::encode_base64(String source)

Base64-Codierung eines Strings erzeugen.

Name Typ Default Beschreibung
Return String   Base64-codierter Eingabetext.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input String oder char* - Beliebiger String

Kodierung eines Textes und Rückcodierung dieses Ergebnisses sollten den gleichen String liefern. 

int main () {
    String str = string::alloc("Hallo Welt");
    String reconverted;
    String base64;

    base64 = string::encode_base64(str);

    if (base64 != 0) {
        showmessage(base64);
        reconverted = string::decode_base64(base64);
        if (reconverted != 0) {
            showmessage(reconverted);	//Shows "Hallo Welt"
        }
    }

    string::release(str);
    //Do NOT release base64 and reconverted!"
    //This strings are r/o return values of built-in functions."

    return 0;
}

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

string::decode_base64

static String string::decode_base64(String source)

Decodieren eines base64-codierten Strings.

Name Typ Default Beschreibung
Return String   Neu erzeugter String mit dem decodierten Eingabetext.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input String oder char* - Beliebiger base64 codierter String

Kodierung eines Textes und Rückcodierung dieses Ergebnisses sollten den gleichen String liefern. 

int main () {
    String str = string::alloc("Hallo Welt");
    String reconverted;
    String base64;

    base64 = string::encode_base64(str);

    if (base64 != 0) {
        showmessage(base64);
        reconverted = string::decode_base64(base64);
        if (reconverted != 0) {
            showmessage(reconverted);	//Shows "Hallo Welt"
        }
    }

    string::release(str);
    //Do NOT release base64 and reconverted!"
    //This strings are r/o return values of built-in functions."


    return 0;
}

v4.1 R16536

priint:comet InDesign® Plug-Ins, comet_pdf, Illustrator

string::encode_base64

static char* string::to_cp1252(String source)

Konvertierung eines Strings in den 'Code Page 1252'

Name Typ Default Beschreibung
Return char*   Neu erzeugter char* mit geänderter Codierung

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input String - Beliebiger String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_cp1252

static char* string::to_systemcharset(String source)

Konvertierung eines Strings in den Systemzeichensatz

Name Typ Default Beschreibung
Return char*   Neu erzeugter char* mit geänderter Codierung

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input String - Beliebiger String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_systemcharset

static char* string::to_macroman(String source)

Konvertierung eines Strings in Mac Roman

Name Typ Default Beschreibung
Return char*   Neu erzeugter char* mit geänderter Codierung

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input String - Beliebiger String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_macroman

static int* string::to_wchar(String input, int* destination)

Konvertierung eines Strings in Unicode

Name Typ Default Beschreibung
Return int*   Konvertierter String, entspricht Parameter destination
input String - Beliebiger String
destination int* - Reservierter Speicher für das Ergebnis

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::from_wchar

static String string::from_cp1252(char* input)

Konvertierung eines 'Code Page 1252' char*'s in einen String

Name Typ Default Beschreibung
Return String   Neu erzeugter String.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input char* - CP1252 codierter String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_cp1252

static String string::from_systemcharset(char* input)

Konvertierung eines mit dem Systemzeichensatz codierten char*'s in einen String

Name Typ Default Beschreibung
Return String   Neu erzeugter String.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input char* - Systemzeichensatz codierter String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_systemcharset

static String string::from_macroman(char* input)

Konvertierung eines mit Mac Roman codierten char*'s in einen String

Name Typ Default Beschreibung
Return String   Neu erzeugter String.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input char* - Mac Roman codierter String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_macroman

static String string::from_wchar(String source)

Konvertierung eines Unicode int*'s in einen String

Name Typ Default Beschreibung
Return String   Neu erzeugter String.

Der Rückgabewert darf nicht verändert werden und wird bei folgenden Aufrufen der Funktion überschrieben. Hier finden Sie Informationen zu readonly-Rückgaben von Funktionen.
input int* - Unicode codierter String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::to_wchar

static String string::escape_tagged(String source)

Ersetze alle nicht-ASCII Zeichen durch TaggedText Markierungen.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter input
input String - Beliebiger String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::unescape_tagged
comet.strutils.escapeTagged

static String string::unescape_tagged(String source)

Ersetze TaggedText Markierungen durch die entsprechenden UTF8 Zeichen.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter input
input String - Beliebiger String

v4.1 R18355

priint:comet InDesign® Plug-Ins, comet_pdf

string::escape_tagged
comet.strutils.unescapeTagged

static String string::prepare_aem_url(
  String url,
  char* user = 0,
  char* pwd = 0,
  int pwd_encrypted = 0)

Vorbereiten einer Asset-URL des AEM® zum Download eines Assets.

Beim Platzieren von Assets aus AEM® mit Drag&Drop sendet AEM® eine URL ohne Benutzername und Passwort. Zum Laden des Assets werden diese Angaben aber benötigt. Die Anweisung fügt den Benutzernamen und das Passwort der atuellen AEM®-Verbindung in die übergebene URL ein. Besteht keine AEM®-Verbindung, können Defaults für Benutzer und Passwort übergeben werden.

Zusätzlich zum Einfügen der credentials wird die URL so korrigiert, dass AEM® den Inhalt des Assets liefern kann:

Weitere Ersetzungen in der URL können nach dem Aufruf mit allen verfügbaren String-Funktionen gemacht werden.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter url
url String - URL eines AEM®-Assets
user String oder char* 0 Benutzername. Der Parameter wird nur ausgewertet, wenn keine aktuelle Datenverbindung zu einem AEM® besteht.

0 oder leer : "admin"
pwd String oder char* 0 Passwort. Der Parameter wird nur ausgewertet, wenn keine aktuelle Datenverbindung zu einem AEM® besteht.

0 oder leer : "admin"
pwd_encrypted int 0 Ist das Passwort verschlüsselt oder nicht? Der Parameter wird nur ausgewertet, wenn keine aktuelle Datenverbindung zu einem AEM® besteht.

0 : Nein, Passwort im Klartext
1 : Ja, das Passwort ist crypt verschlüsselt

v4.1 R23457, 19. Jul 2018
Parameter pwd_encrypted seit v4.1.6 R25346, 25. Juni 2019

priint:comet InDesign® Plug-Ins, comet_pdf

file::aem_get_asset
crypt

static String string::crypt_url_credentials(String url)

Verschlüsselt Authentifizierungsdaten in einem URL wie z.B. http://user:password@pubserver.priint.com/...
Der URL kann mit string::decrypt_url_credentials wieder entschlüsselt werden.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter url
url String - URL

v4.1.5 R24777, 18. Feb 2019
priint:comet InDesign® Plug-Ins, comet_pdf

static String (String url)

Entschlüsselt Authentifizierungsdaten in einem URL wie z.B. http://user:password@pubserver.priint.com/...
Der URL kann mit string::crypt_url_credentials wieder verschlüsselt werden.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter url
url String - URL

v4.1.5 R24777, 18. Feb 2019
priint:comet InDesign® Plug-Ins, comet_pdf
Sicherheitslücke

static String string::crypt(String str)

Verschlüsselt einen String. Das Ergebnis ist ein verschlüsselter und Base64-kodierter String. Die Verschlüsselung kann mit string::decrypt wieder rückgängig gemacht werden.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter str
str String - Zu verschlüsselnder String

v4.1.6 R25346, 25. Juni 2019
priint:comet InDesign® Plug-Ins, comet_pdf

static String (String url)

Entschüsselt eine mit string::crypt verschlüsselten String.

Name Typ Default Beschreibung
Return String   Geänderter String, entspricht Parameter str
str String - Zu entschüsselnder String

v4.1.6 R25346, 25. Juni 2019
priint:comet InDesign® Plug-Ins, comet_pdf
Sicherheitslücke

Preconditions
#include "internal/text.h"

Seit
Version 1.1.5

Alphabetic index HTML hierarchy of classes or Java