UTF8 string class/de

Was ist TbUtf8?

Mit der Bibliothek TbUtf8 kann man auf einfache Weise Utf8 Strings verändern.

Problem

Bei Lazarus (Free Pascal) ist der String UTF8 kodiert. Allerdings ist der Type „String“ nichts anderes als ein dynamisches Byte- Array. Length liefert die Anzahl der Bytes im Array aber nicht die Anzahl der Zeichen. Bei UTF8 kann ein Zeichen 4Byte groß sein und mit kombinierten Zeichen sogar 7 Byte. Ein Beispiel soll das veranschaulichen. ‚Thomas‘ 6 Zeichen, 6 Byte groß. ‚Thömäs‘ 6 Zeichen, 8 Byte groß.

Lösung

Mit TbUtf8 kann man jetzt auf einfache Weise UTF8 Strings mit Sonder- und kombinierten Zeichen, wie „üäößẶặǺǻǼǽǞǟǍǎḂḃÞþÇçĆćĊċ…“ verändern und durchsuchen. Im wesentlichen besteht die Bibliothek aus einer UTF8 String Klasse (TIbUtf8).

Vorteile

• TIbUtf8 ist eine Klasse vom Typ TInterfacedObject und muss nicht aufgeräumt werden.
• Alle Indexe sind Zeichen basiert.
• Alle Zeichen Rückgabewerte sind vom Typ String.
• Liefert Anzahl der Zeichen im String.
• Liefert Anzahl der Bytes im String.
• Löschen von Zeichen oder Zeichengruppen.
• Einfügen von Zeichen und Zeichengruppen.
• Anhängen von Zeichen und Zeichengruppen.
• Lesen / Schreiben von Zeichen und Zeichengruppen.
• Lesen / Schreiben in eine Datei.
• Lesen / Schreiben in einen Stream.

Nachteil

• Da UTF8 keinen konstanten Offset von Zeichen zu Zeichen hat, ist das Suchen nach Zeichen deutlich aufwendiger. Das Iterieren über die Zeichen ist ca. 20 x langsamer als beim String. (Komfort hat eben seinen Preis)
• Es wird etwas mehr Speicher benötigt.

Download

• GitLab FpTuxe/TbUtf8 repository

FpTuxe/TbUtf8

• Git clone

git clone https://gitlab.com/FpTuxe/tbutf8.git

Installation

Varinate 1
Lazarus->Datei->öffnen

dein Pfad /tbutf8/src/tb_utf8.pas -> Öffnen

Lazarus->Projekte->Datei im Editor ins Projekt aufnehmen.

Varinate 2
Lazarus->Package->Package-Datei (.lpk) öffen

dein Pfad /tbutf8/src/tbutf8.lpk -> Öffnen

Verwenden->Zum Projekt hinzufügen.

Package Fenster schliessen.

Funktionsbeschreibung

Allgemein

Alle Indexe halten sich an die Pascal- Notation. Erste Zeichen hat den Index 1, letzte Zeichen hat den Index NumberOfChars. Nach dem Erzeugen einer Instanz hat Options den Wert [ut8Combining]. Nach dem Zuweisen von Text hat CurrentIndex den Wert 1.

Instanz erzeugen

Es wird immer eine Variable vom Typ „IbUtf8“ benötigt. NICHT vom Type TIbUtf8!!! Das ‚I‘ in IbUtf8 steht für Interface. Das ‚I‘ in TIbUtf8 steht für InterfacedObject. Beispiel:

procedure Demo01;
var Name:  IbUtf8;
begin
  Name:= TIbUtf8.Create('Boris');
end;

oder

procedure Demo02;
var Name:  IbUtf8;
begin
  Name:= TIbUtf8.Create;
  Name.Text:= 'Boris';
end;

Beim Verlassen der Procedure wird die Instanz automatisch aufgelöst.

Options

• ut8Combining: Ist dieser Wert gesetzt, werden Zeichen mit kombinierten Zeichen als ein Zeichen interpretiert.
• ut8InclusiveCurrentChar: Dieser Wert verändert das Verhalten von NextChar und BackChar. Ist der Wert gesetzt, liefert NextChar und BackChar immer das aktuelle Zeichen (CurrentIndex) und geht dann zum nächsten Zeichen. Ist der Wert nicht gesetzt, bekommt man immer das nächste Zeichen.

Beispiel:

procedure Demo03;
var
  Name: IbUtf8;
begin
  Name:= TIbUtf8.Create('Hello');
  Name.CurrentIndex:= 1;
  Name.Options:=  Name.Options + [Ut8InclusiveCurrentChar];
  while (not Name.IsStringEnd) and (Name.NextChar <> 'l') do;
  if Name.CurrentChar = 'l' then begin
   WriteLn('Richtig'):
  end;
end;

NumberOfChars

Liefert die Anzahl der Zeichen. Dieser Wert ist abhängig von der Option Ut8Combining. Siehe auch Options.

Length

Liefert Anzahl der Bytes die der Text im Buffer belegt.

IsEmpty

Ist der String leer, so ist der Rückgabewert True.

IsEqual(aText)

Ist der Text (aText) gleich dem Text in der Instanz, dann ist der Rückgabewert True.

IsStringEnd

Ist CurrentIndex am Stringende (CurrentIndex >= NumberOfChars), oder ist der String leer, dann ist der Rückgabewert True.

IsStringFront

Ist CurrentIndex = 1 oder der String ist leer, dann ist der Rückgabewert True.

FirstChar

Liefert das erste Zeichen des Strings. Ist der String leer, gibt es eine Exception.

LastChar

Liefert das Letzte Zeichen in dem String. Ist der String leer, gibt es eine Exception.

NextChar

Liefert das nächste Zeichen. Das Verhalten ist abhängig von der Option Ut8InclusiveCurrentChar. Siehe auch Options Ist der String leer, oder CurrentIndex am Ende des Strings, wird ein Leerstring zurückgegeben. CurrentIndex wird um 1 erhöht.

BackChar

Liefert das vorige Zeichen. Das Verhalten ist abhängig von der Option Ut8InclusiveCurrentChar. Siehe auch Options Ist der String leer oder CurrentIndex am Anfang des Strings, wird ein Leerstring zurück gegeben. CurrentIndex wird um 1 erniedrigt.

Text

Lesend: Liefert den String. Schreibend: Speichert den Text in der Instanz. Ist es kein Leerstring wird CurrentIndex auf 1 gesetzt, ansonsten auf 0.

CurrentIndex

Lesend: Gibt die aktuelle Indexposition zurück. Schreibend: Setzt die neue Indexposition. Ist die Indexposition außerhalb des zulässigen Bereiches, gibt es eine Exception.

CurrentChar

Liefert das Zeichen, wo CurrentIndex drauf verweist. Ist der Text leer, wird ein Leerstring zurückgegeben.

Chars[Index]

Lesend: Liefert ein Zeichen, welches durch den Index angegeben ist. Schreibend: Ersetzt das Zeichen, welches durch den Index angegeben wird. Es können auch mehrere Zeichen angegeben werden. Ist die Indexposition außerhalb des zulässigen Bereiches, gibt es eine Exception. Beispiel:

procedure Demo04;
var  Name: IbUtf8;
begin      
  Name:= TIbUtf8.Create('Heko');
  Name.Chars[3]:= 'll';
  if Name.Text = 'Hello' then begin
    WriteLn('Richtig');
  end;
end;

Copy

Erzeugt eine neue Instanz mit gleichem Inhalt.

Copy(StartIndex, nChars)

Erzeugt eine neue Instanz mit dem Text von StartIndex bis nChars. Ist StartIndex außerhalb des zulässigen Bereiches, gibt es eine Exception. Ist nCharts = 0, wird ein Leerstring zurück gegeben. Ist nChars > Stringende werden die Zeichen bis Stringende kopiert.

Beispiel:

procedure Demo05;
var  Name, Nachname: IbUtf8;
begin      
  Name:= TIbUtf8.Creatre('Boris Weber')
  Nachname:= Name.Copy(7, 5);
  if Nachname.Text = 'Weber' then begin
    WriteLn('Richtig');
  end;
end;

CopyAsString(StartIndex, nChars)

Verhält sich wie Copy(StartIndex, nChars), nur wird hier ein String zurückgegeben.

Delete(CharIndex: Cardinal)

Löscht ein Zeichen. Ist CharIndex außerhalb des zulässigen Bereiches, gibt es eine Exception.

Delete(StartIndex, nChars)

Löscht nChars ab dem StartIndex. Bei StartIndex außerhalb des zulässigen Bereiches, gibt es eine Exception. Ist nCharts = 0, wird nichts gelöscht. Ist nChars > Stringende wird bis zum Stringende gelöscht.

Beispiel:

procedure Demo06;
var  Name: IbUtf8;
begin      
  Name:= TIbUtf8.Create('Boris Weber');
  Name.Delete(1, 6);
  if Name.Text = 'Weber' then begin
    WriteLn('Richtig');
  end;
end;

Insert(StartIndex, aValue)

Insert gibt es zweimal. Einmal kann man ein String einfügen, das andere mal eine IbUtf8 Instanz. StartIndex legt fest, ab welcher Position der Text eingefügt wird. Bei StartIndex = 0, gibt es eine Exception. Bei StartIndex > Stringende wird der Text am Ende angehängt.

Beispiel:

procedure Demo07;
var  Name: IbUtf8;
begin      
  Name:= TIbUtf8.Create('Bor');
  Name.Insert(4, 'is Weber');
  if Name.Text = 'Boris Weber' then begin
    WriteLn('Richtig');
  end;
end;

Kombinierte Zeichen

Sollten die kombinierten Zeichen, die in „tb_utf8_combinings.pas“ definiert sind, nicht ausreichen, so kann einfach die Tabelle „C_COMBINIGS“ um die neuen Werte oder Wertebereiche erweitert werden. Zur Zeit sind 4 Blöcke definiert.

From the Free Pascal wiki, page "UTF8 string class/de", as it stood on 2022-01-24 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's Licensing page. If you have concerns about this material, message the admin.