Character and string types: what changed

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

Old	New		Line
1	1		Free Pascal supports several [[Char\|character]] and [[String\|string]] types. They range from single ANSI characters to unicode strings and also include pointer types. Differences also apply to encodings and reference counting.
2	2
3	3		## Character types
4	4
5	5		### AnsiChar
6	6
7	7		A variable of type AnsiChar, also referred to as [[Char\|char]], is exactly 1 byte in size, and contains one "ANSI" (local code page) character.
8	8
9	9		\| \|
10	10		\|-----\|
11	11		\| a \|
12	12
13	13		#### Reference
14	14
15	15		- [FPC AnsiChar documentation](http://www.freepascal.org/docs-html/ref/refsu6.html)
16	16		- [[Char\|Usage Char]]
17	17		- [Wikipedia:Windows code page#ANSI code page](https://en.wikipedia.org/wiki/Windows_code_page#ANSI_code_page)
18	18
19	19		### WideChar
20	20
21	21		A variable of type WideChar, also referred to as UnicodeChar, is exactly 2 bytes in size, and usually contains one [[LCL Unicode Support\|Unicode]] code point (normally a character) in UTF-16 encoding. Note: it is impossible to encode all Unicode code points in 2 bytes. Therefore, 2 WideChars may be needed to encode a single code point.
22	22
23	23		\| \| \|
24	24		\|-----\|-----\|
25	25		\| \| a \|
26	26
27	27		#### References
28	28
29	29		- [FPC WideChar documentation](http://www.freepascal.org/docs-html/ref/refsu7.html)
30	30		- [UTF-16 information on Wikipedia](https://en.wikipedia.org/wiki/UTF-16)
31	31		- [[doc:rtl/system/unicodechar.html\|RTL UnicodeChar documentation]]
32	32
33	33		## Character-derived types
34	34
35	35		### Array of Char
36	36
37	37		Early Pascal implementations that were in use before 1978 did not support a string type (with the exception of string constants). The only possibility to store strings in variables was the use of arrays of char. This approach has many disadvantages and is no longer recommended. It is, however, still supported to ensure backward-compatibility with ancient code.
38	38
39	39		#### Static Array of Char
40	40
41	41		``` pascal
42	42		type
43	43		TOldString4 = array[0..3] of char;
44	44		var
45	45		aOldString4: TOldString4;
46	46		begin
47	47		aOldString4[0] := 'a';
48	48		aOldString4[1] := 'b';
49	49		aOldString4[2] := 'c';
50	50		aOldString4[3] := 'd';
51	51		end;
52	52		```
53	53
54	54		The static array of char has now the content:
55	55
56	56		\| \| \| \| \|
57	57		\|-----\|-----\|-----\|-----\|
58	58		\| a \| b \| c \| d \|
59	59
60	60		> Note: Unassigned chars can have any content, depending on what was just in memory when the memory for the array was made available.
61	61
62	62		#### Dynamic Array of Char
63	63
64	64		``` pascal
65	65		var
66	66		aOldString: Array of Char;
67	67		begin
68	68		SetLength(aOldString, 5);
69	69		aOldString[0] := 'a';
70	70		aOldString[1] := 'b';
71	71		aOldString[2] := 'c';
72	72		aOldString[3] := 'd';
73	73		end;
74	74		```
75	75
76	76		The dynamic array of char has now the content:
77	77
78	78		\| \| \| \| \| \|
79	79		\|-----\|-----\|-----\|-----\|-----\|
80	80		\| a \| b \| c \| d \| \#0 \|
81	81
82	82		> Note: Unassigned chars in dynamic arrays have a content \#0, cause empty positions of all dynamic arrays are initially initialised with 0 (or \#0, or nil, or ...)
83	83
84	84		### PChar
85	85
86	86		A variable of type [[PChar]] is basically a pointer to a Char type, but allows additional operations. PChars can be used to access C-style [null-terminated strings](http://en.wikipedia.org/wiki/Null-terminated_string), e.g. in interaction with certain OS libraries or third-party software.
87	87
88	88		\| \| \| \| \|
89	89		\|-----\|-----\|-----\|-----\|
90	90		\| a \| b \| c \| \#0 \|
91	91		\| ^ \| \| \| \|
92	92
93	93		#### Reference
94	94
95	95		- [FPC PChar documentation](http://www.freepascal.org/docs-html/ref/refsu12.html)
96	96		- [[doc:rtl/sysutils/pcharfunctions.html\|PChar related functions]]
97	97
98	98		### PWideChar
99	99
100	100		A variable of type PWideChar is a pointer to a WideChar variable.
101	101
102	102		\| \| \| \| \| \| \| \| \|
103	103		\|-----\|-----\|-----\|-----\|-----\|-----\|-----\|-----\|
104	104		\| \| a \| \| b \| \| c \| \#0 \| \#0 \|
105	105		\| ^ \| \| \| \| \| \| \| \|
106	106
107	107		#### Reference
108	108
109	109		- [[doc:rtl/system/pwidechar.html\|RTL PWideChar documentation]]
110	110
111	111		## String types
112	112
113	113		### String
114	114
115	115		The type String may refer to ShortString or AnsiString, depending from the [{\$H} switch](http://www.freepascal.org/docs-html/prog/progsu25.html#x32-310001.2.25). If the switch is off ({\$H-}) then any string declaration will define a ShortString. It size will be 255 chars, if not otherwise specified. If it is on ({\$H+}) string without length specifier will define an AnsiString, otherwise a ShortString with specified length. In mode delphiunicode String'' isUnicodeString'''.
116	116
117	117		#### Reference
118	118
119	119		- [[String\|Usage String]].
120	120		- [[doc:rtl/sysutils/stringfunctions.html\|String functions]]
121	121		- [[doc:rtl/strutils/index-5.html\|Reference for unit 'strutils': Procedures and functions]]
122	122
123	123		### ShortString
124	124
125	125		Short strings have a maximum length of 255 characters with the implicit [[FPC Unicode support\|codepage]] CP_ACP. The length is stored in the character at index 0. A short string of 255 characters uses 256 bytes of memory (one byte for the length specification and 255 bytes for characters).
126	126
127	127		\| \| \| \| \|
128	128		\|-----\|-----\|-----\|-----\|
129	129		\| \#3 \| a \| b \| c \|
130	130
131	131		#### Reference
132	132
133	133		- [FPC Single-byte String types documentation](https://www.freepascal.org/docs-html/ref/refsu9.html)
134	134
135	135		### AnsiString
136	136
137	137		Ansistrings are strings that have no length limit. They are [reference counted](http://en.wikipedia.org/wiki/Reference_counting) and are guaranteed to be [null terminated](http://en.wikipedia.org/wiki/Null-terminated_string). Internally, a variable of type AnsiString is treated as a pointer: the actual content of the string is stored on the heap, as much memory as needed to store the string content is allocated.
138	138
139		-	~~<tbody>~~
140		-
141		-	~~</tbody>~~
	139	+	\| \| \| \| \| \| \| \| \| a \| b \| c \| #0 \|
	140	+	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	141	+	\| RefCount \| \| \| \| Length \| \| \| \| \| \| \| \|
142	142
143	143		On 64-bit targets, fields RefCount/Length consume 8 bytes each, not 4.
144	144
145	145		An AnsiString type may also have a compile-time code page since FPC 2.7.1; a missing value defaults to `DefaultSystemCodePage`. A value of `CP_NONE` results in `RawBytestring` and a value of `CP_UTF8` results in `UTF8String`.
146	146
147	147		#### Reference
148	148
149	149		- [FPC Single-byte String types documentation](https://www.freepascal.org/docs-html/ref/refsu9.html)
150	150
151	151		### UnicodeString
152	152
153	153		Like AnsiStrings, UnicodeStrings are reference counted, null-terminated arrays, but they are implemented as arrays of WideChars instead of regular Chars.
154	154
155	155		> Note: The UnicodeString naming is a bit ambiguous but probably due to its use in Delphi on Windows, where the OS uses UTF16 encoding; it's not the only string type that can hold Unicode string data (see also UTF8String)...
156	156
157		-	~~<tbody>~~
158		-
159		-	~~</tbody>~~
	157	+	\| \| \| \| \| \| \| \| \| \| a \| \| b \| \| c \| #0 \| #0 \|
	158	+	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	159	+	\| RefCount \| \| \| \| Length \| \| \| \| \| \| \| \| \| \| \| \|
160	160
161	161		On 64-bit targets, fields RefCount/Length consume 8 bytes each, not 4.
162	162
163	163		#### Reference
164	164
165	165		- [FPC Multi-byte String types documentation](http://www.freepascal.org/docs-html/ref/refsu10.html)
166	166
167	167		### UTF8String
168	168
169	169		In FPC 2.6.5 and below the type UTF8String was an alias to the type AnsiString. In FPC 2.7.1 and above it is defined as `UTF8String = type AnsiString(CP_UTF8);`
170	170
171	171		It is meant to contain UTF-8 encoded strings (i.e. unicode data) ranging from 1..4 bytes per character. Note that String can also contain UTF-8 encoded characters.
172	172
173	173		#### Reference
174	174
175	175		- [FPC UTF8String documentation](https://www.freepascal.org/docs-html/ref/refsu9.html#x32-400003.2.4)
176	176
177	177		### UTF16String
178	178
179	179		The type UTF16String is an alias to the type WideString. In the LCL unit lclproc it is an alias to UnicodeString.
180	180
181	181		#### Reference
182	182
183	183		- [[doc:lcl/lclproc/utf16string.html\|LCL UTF16String documentation]]
184	184
185	185		### WideString
186	186
187	187		Variables of type [[Widestrings\|WideString]] (used to represent unicode character strings in COM applications) resemble those of type UnicodeString, but unlike them they are not reference-counted. On Windows they are allocated with a special windows function which allows them to be used for OLE automation.
188	188
189	189		WideStrings consist of COM compatible UTF16 encoded bytes on Windows machines (UCS2 on Windows 2000), and they are encoded as plain UTF16 on Linux, Mac OS X and iOS.
190	190
191		-	~~<tbody>~~
192		-
193		-	~~</tbody>~~
	191	+	\| \| \| \| \| \| a \| \| b \| \| c \| #0 \| #0 \|
	192	+	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	193	+	\| Length \| \| \| \| \| \| \| \| \| \| \| \|
194	194
195	195		#### Reference
196	196
197	197		- [FPC Multi-byte String types documentation](http://www.freepascal.org/docs-html/ref/refsu10.html)
198	198
199	199		## String-derived types
200	200
201	201		### PShortString
202	202
203	203		A variable of type PShortString is a pointer that points to the first byte of a ShortString-type variable (which defines the length of the ShortString).
204	204
205	205		\| \| \| \| \|
206	206		\|-----\|-----\|-----\|-----\|
207	207		\| \#3 \| a \| b \| c \|
208	208		\| ^ \| \| \| \|
209	209
210	210		#### Reference
211	211
212	212		- [[doc:rtl/system/pshortstring.html\|RTL PShortString documentation]]
213	213
214	214		### PAnsiString
215	215
216	216		Variables of type PAnsiString are pointers to AnsiString-type variables. However, unlike PShortString-type variables they don't point to the first byte of the header, but to the first char of the AnsiString.
217	217
218		-	~~<tbody>~~
219		-
220		-	~~</tbody>~~
	218	+	\| \| \| \| \| \| \| \| \| a \| b \| c \| #0 \|
	219	+	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	220	+	\| RefCount \| \| \| \| Length \| \| \| \| ^ \| \| \| \|
221	221
222	222		#### Reference
223	223
224	224		- [[doc:rtl/system/pansistring.html\|RTL PAnsiString documentation]]
225	225
226	226		### PUnicodeString
227	227
228	228		Variables of type PUnicodeString are pointers to variables of type UnicodeString.
229	229
230		-	~~<tbody>~~
231		-
232		-	~~</tbody>~~
	230	+	\| \| \| \| \| \| \| \| \| \| a \| \| b \| \| c \| #0 \| #0 \|
	231	+	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	232	+	\| RefCount \| \| \| \| Length \| \| \| \| ^ \| \| \| \| \| \| \| \|
233	233
234	234		#### Reference
235	235
236	236		- [[doc:rtl/system/punicodestring.html\|RTL PUnicodeString documentation]]
237	237
238	238		### PWideString
239	239
240	240		Variables of type PWideString are pointers. They point to the first char of a WideString-typed variable.
241	241
242		-	~~<tbody>~~
243		-
244		-	~~</tbody>~~
	242	+	\| \| \| \| \| \| a \| \| b \| \| c \| #0 \| #0 \|
	243	+	\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|---\|
	244	+	\| Length \| \| \| \| ^ \| \| \| \| \| \| \| \|
245	245
246	246		#### Reference
247	247
248	248		- [[doc:rtl/system/pwidestring.html\|RTL PWideString documentation]]
249	249
250	250		## String constants
251	251
252	252		If you use only English (ASCII) constants your strings work the same with all types, on all platforms and all compiler versions. Non English strings can be loaded via resourcestrings or from files. If you want to use non English strings in code then you should read further.
253	253
254	254		There are various encodings for non English strings. By default Lazarus saves Pascal files as UTF-8 without BOM. UTF-8 supports the full Unicode range. That means all string constants are stored in UTF-8. Lazarus also supports to change the encoding of a file to other encoding, for example under Windows your local codepage. The Windows codepage is limited to your current language group.
255	255
256	256		\| String Type, UTF-8 Source \| With `{$codepage utf8}`? \| FPC ≤ 2.6.5 \| FPC ≥ 2.7.1 \| FPC ≤ 2.7.1, [[Unicode Support in Lazarus\|UTF8 as default CodePage]] \|
257	257		\|----\|----\|----\|----\|----\|
258	258		\| AnAnsiString:='ãü'; \| No \| Needs UTF8ToAnsi in RTL/WinAPI. Ok in LCL \| Needs UTF8ToAnsi in RTL/WinAPI. Ok in LCL \| Ok in RTL/W-WinAPI/LCL. Needs UTF8ToWinCP in A-WinAPI. \|
259	259		\| AnAnsiString:='ãü'; \| Yes \| System cp ok in RTL/WinAPI. Needs SysToUTF8 in LCL \| Ok in RTL/WinAPI/LCL. Mixing causes conversion. \| Ok in RTL/W-WinAPI/LCL. Needs UTF8ToWinCP in A-WinAPI \|
260	260		\| AnUnicodeString:='ãü'; \| No \| Wrong everywhere \| Wrong everywhere \| Wrong everywhere \|
261	261		\| AnUnicodeString:='ãü'; \| Yes \| System cp ok in RTL/WinAPI. Needs UTF8Encode in LCL \| Ok in RTL/WinAPI/LCL.Mixing causes conversion. \| Ok in RTL/W-WinAPI/LCL. Needs UTF8ToWinCP in A-WinAPI \|
262	262		\| AnUTF8String:='ãü'; \| No \| Same as AnsiString \| Wrong everywhere \| Wrong everywhere \|
263	263		\| AnUTF8String:='ãü'; \| Yes \| Same as AnsiString \| Ok in RTL/WinAPI/LCL. Mixing causes conversion. \| Ok in RTL/W-WinAPI/LCL. Needs UTF8ToWinCP in A-WinAPI. \|
264	264
265	265		- W-WinAPI = Windows API "W" functions, UTF-16
266	266		- A-WinAPI = Windows API non "W" functions, 8bit system ("ANSI") code page
267	267		- System CP = The 8bit system code page of the OS. For example code page [1252](http://en.wikipedia.org/wiki/Windows-1252).
268	268
269	269		``` pascal
270	270		const
271	271		c='ãü';
272	272		cstring: string = 'ãü'; // see AnAnsiString:='ãü';
273	273		var
274	274		s: string;
275	275		u: UnicodeString;
276	276		begin
277	277		s:=c; // same as s:='ãü';
278	278		s:=cstring; // does not change encoding
279	279		u:=c; // same as u:='ãü';
280	280		u:=cstring; // fpc 2.6.1: converts from system cp to UTF-16, fpc 2.7.1+: depends on encoding of cstring
281	281		end;
282	282		```
283	283
284	284		The rules for conversion are laid out in a ["Code page conversions"](https://freepascal.org/docs-html/ref/refsu9.html#x32-380003.2.4) section in the FPC manual. The basic point is that assigning an AnsiString (including the `CP_UTF8` specialization) to another AnsiString converts what is in the source to match the code page of the target string. A quirk for compatibility with presumably fpc ≤ 2.6.5 is that no such conversion will be done if one matches the source code CP and the other matches the system CP. In this case, forced (likely incorrect) interpretation as the target code page will occur.
285	285
286	286		## See also
287	287
288	288		- [[FPC Unicode support]]
289	289		- [[LCL Unicode Support]]
290	290		- [[TStringList-TStrings Tutorial]]
291	291		- [A Brief History of Strings](http://web.archive.org/web/20151125114234/http://www.codexterity.com/delphistrings.htm)
292	292
293	293		---
294	294		From the Free Pascal wiki, page "Character and string types", as it stood on 2023-12-14 after a change by Coz, 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