UTF8 string class/de: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: UTF8 string class/de

New		Line
1	+	## Was ist TbUtf8?
2	+
3	+	Mit der Bibliothek TbUtf8 kann man auf einfache Weise Utf8 Strings verändern.
4	+
5	+	### Problem
6	+
7	+	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ß.
8	+
9	+	### Lösung
10	+
11	+	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).
12	+
13	+	### Vorteile
14	+
15	+	- TIbUtf8 ist eine Klasse vom Typ TInterfacedObject und muss nicht aufgeräumt werden.
16	+	- Alle Indexe sind Zeichen basiert.
17	+	- Alle Zeichen Rückgabewerte sind vom Typ String.
18	+	- Liefert Anzahl der Zeichen im String.
19	+	- Liefert Anzahl der Bytes im String.
20	+	- Löschen von Zeichen oder Zeichengruppen.
21	+	- Einfügen von Zeichen und Zeichengruppen.
22	+	- Anhängen von Zeichen und Zeichengruppen.
23	+	- Lesen / Schreiben von Zeichen und Zeichengruppen.
24	+	- Lesen / Schreiben in eine Datei.
25	+	- Lesen / Schreiben in einen Stream.
26	+
27	+	### Nachteil
28	+
29	+	- 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)
30	+	- Es wird etwas mehr Speicher benötigt.
31	+
32	+	## Download
33	+
34	+	- GitLab FpTuxe/TbUtf8 repository
35	+
36	+	[`FpTuxe/TbUtf8`](https://gitlab.com/FpTuxe/tbutf8)
37	+
38	+	- Git clone
39	+
40	+	``` bash
41	+	git clone https://gitlab.com/FpTuxe/tbutf8.git
42	+	```
43	+
44	+	## Installation
45	+
46	+	Varinate 1
47	+	Lazarus-\>Datei-\>öffnen
48	+
49	+	dein Pfad /tbutf8/src/tb_utf8.pas -\> Öffnen
50	+
51	+	Lazarus-\>Projekte-\>Datei im Editor ins Projekt aufnehmen.
52	+
53	+	Varinate 2
54	+	Lazarus-\>Package-\>Package-Datei (.lpk) öffen
55	+
56	+	dein Pfad /tbutf8/src/tbutf8.lpk -\> Öffnen
57	+
58	+	Verwenden-\>Zum Projekt hinzufügen.
59	+
60	+	Package Fenster schliessen.
61	+
62	+	## Funktionsbeschreibung
63	+
64	+	### Allgemein
65	+
66	+	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.
67	+
68	+	### Instanz erzeugen
69	+
70	+	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:
71	+
72	+	``` pascal
73	+	procedure Demo01;
74	+	var Name: IbUtf8;
75	+	begin
76	+	Name:= TIbUtf8.Create('Boris');
77	+	end;
78	+	```
79	+
80	+	oder
81	+
82	+	``` pascal
83	+	procedure Demo02;
84	+	var Name: IbUtf8;
85	+	begin
86	+	Name:= TIbUtf8.Create;
87	+	Name.Text:= 'Boris';
88	+	end;
89	+	```
90	+
91	+	Beim Verlassen der Procedure wird die Instanz automatisch aufgelöst.
92	+
93	+	### Options
94	+
95	+	- ut8Combining: Ist dieser Wert gesetzt, werden Zeichen mit kombinierten Zeichen als ein Zeichen interpretiert.
96	+	- 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.
97	+
98	+	Beispiel:
99	+
100	+	``` pascal
101	+	procedure Demo03;
102	+	var
103	+	Name: IbUtf8;
104	+	begin
105	+	Name:= TIbUtf8.Create('Hello');
106	+	Name.CurrentIndex:= 1;
107	+	Name.Options:= Name.Options + [Ut8InclusiveCurrentChar];
108	+	while (not Name.IsStringEnd) and (Name.NextChar <> 'l') do;
109	+	if Name.CurrentChar = 'l' then begin
110	+	WriteLn('Richtig'):
111	+	end;
112	+	end;
113	+	```
114	+
115	+	### NumberOfChars
116	+
117	+	Liefert die Anzahl der Zeichen. Dieser Wert ist abhängig von der Option Ut8Combining. Siehe auch Options.
118	+
119	+	### Length
120	+
121	+	Liefert Anzahl der Bytes die der Text im Buffer belegt.
122	+
123	+	### IsEmpty
124	+
125	+	Ist der String leer, so ist der Rückgabewert True.
126	+
127	+	### IsEqual(aText)
128	+
129	+	Ist der Text (aText) gleich dem Text in der Instanz, dann ist der Rückgabewert True.
130	+
131	+	### IsStringEnd
132	+
133	+	Ist CurrentIndex am Stringende (CurrentIndex \>= NumberOfChars), oder ist der String leer, dann ist der Rückgabewert True.
134	+
135	+	### IsStringFront
136	+
137	+	Ist CurrentIndex = 1 oder der String ist leer, dann ist der Rückgabewert True.
138	+
139	+	### FirstChar
140	+
141	+	Liefert das erste Zeichen des Strings. Ist der String leer, gibt es eine Exception.
142	+
143	+	### LastChar
144	+
145	+	Liefert das Letzte Zeichen in dem String. Ist der String leer, gibt es eine Exception.
146	+
147	+	### NextChar
148	+
149	+	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.
150	+
151	+	### BackChar
152	+
153	+	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.
154	+
155	+	### Text
156	+
157	+	Lesend: Liefert den String. Schreibend: Speichert den Text in der Instanz. Ist es kein Leerstring wird CurrentIndex auf 1 gesetzt, ansonsten auf 0.
158	+
159	+	### CurrentIndex
160	+
161	+	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.
162	+
163	+	### CurrentChar
164	+
165	+	Liefert das Zeichen, wo CurrentIndex drauf verweist. Ist der Text leer, wird ein Leerstring zurückgegeben.
166	+
167	+	### Chars\[Index\]
168	+
169	+	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:
170	+
171	+	``` pascal
172	+	procedure Demo04;
173	+	var Name: IbUtf8;
174	+	begin
175	+	Name:= TIbUtf8.Create('Heko');
176	+	Name.Chars[3]:= 'll';
177	+	if Name.Text = 'Hello' then begin
178	+	WriteLn('Richtig');
179	+	end;
180	+	end;
181	+	```
182	+
183	+	### Copy
184	+
185	+	Erzeugt eine neue Instanz mit gleichem Inhalt.
186	+
187	+	### Copy(StartIndex, nChars)
188	+
189	+	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.
190	+
191	+	Beispiel:
192	+
193	+	``` pascal
194	+	procedure Demo05;
195	+	var Name, Nachname: IbUtf8;
196	+	begin
197	+	Name:= TIbUtf8.Creatre('Boris Weber')
198	+	Nachname:= Name.Copy(7, 5);
199	+	if Nachname.Text = 'Weber' then begin
200	+	WriteLn('Richtig');
201	+	end;
202	+	end;
203	+	```
204	+
205	+	### CopyAsString(StartIndex, nChars)
206	+
207	+	Verhält sich wie Copy(StartIndex, nChars), nur wird hier ein String zurückgegeben.
208	+
209	+	### Delete(CharIndex: Cardinal)
210	+
211	+	Löscht ein Zeichen. Ist CharIndex außerhalb des zulässigen Bereiches, gibt es eine Exception.
212	+
213	+	### Delete(StartIndex, nChars)
214	+
215	+	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.
216	+
217	+	Beispiel:
218	+
219	+	``` pascal
220	+	procedure Demo06;
221	+	var Name: IbUtf8;
222	+	begin
223	+	Name:= TIbUtf8.Create('Boris Weber');
224	+	Name.Delete(1, 6);
225	+	if Name.Text = 'Weber' then begin
226	+	WriteLn('Richtig');
227	+	end;
228	+	end;
229	+	```
230	+
231	+	### Insert(StartIndex, aValue)
232	+
233	+	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.
234	+
235	+	Beispiel:
236	+
237	+	``` pascal
238	+	procedure Demo07;
239	+	var Name: IbUtf8;
240	+	begin
241	+	Name:= TIbUtf8.Create('Bor');
242	+	Name.Insert(4, 'is Weber');
243	+	if Name.Text = 'Boris Weber' then begin
244	+	WriteLn('Richtig');
245	+	end;
246	+	end;
247	+	```
248	+
249	+	### Kombinierte Zeichen
250	+
251	+	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.
252	+
253	+	---
254	+	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](/wiki-contact).

Back to history