UTF8 string class/de: what changed

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

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