Difference between revisions of "PChar"

From Lazarus wiki
Jump to navigationJump to search
m
(consider changes suggested in discussion)
 
(7 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Pchar}}
+
{{PChar}}
  
A '''PChar''' is [[Data type]] and a [[Pointer]] to a null-terminated string. The most important application of a PChar is interaction with system libraries like dll's.
+
The data type {{Doc|package=RTL|unit=system|identifier=pchar|text=<syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight>}} is a [[Pointer|pointer]] to a single [[Char|<syntaxhighlight lang="pascal" inline>char</syntaxhighlight>]].
 +
{{Doc|package=RTL|unit=system|identifier=pansichar|text=<syntaxhighlight lang="pascal" inline>PAnsiChar</syntaxhighlight>}} is an alias for <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight>.
 +
<syntaxhighlight lang="pascal">type
 +
PChar = ^char;
 +
PAnsiChar = PChar;</syntaxhighlight>
  
Messagebox:
+
== special support ==
<syntaxhighlight>
+
A <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> ''could'' be interpreted as a pointer to NULL-terminated string data type value on the heap.
var  
+
This means this string value ends with <syntaxhighlight lang="pascal" inline>chr(0)</syntaxhighlight>.
  s: String;
+
This kind of storing data is rather unsafe and Pascal’s own string data types always indicate an explicit (maximum) length.
 +
However, many libraries written in other programming languages make use of this dangerous data type and in order to facilitate interaction with them the [[FPC]] provides special support (only available in ''non''-ISO modes).
 +
 
 +
=== direct assignments ===
 +
A string literal can be assigned directly to a <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight>:
 +
<syntaxhighlight lang="delphi">
 +
program PCharDemo(output);
 +
var
 +
p: PChar;
 
begin
 
begin
  s := 'Test';
+
p := 'Foobar';
  Application.MessageBox( PChar(s)),'Title', MB_OK );
+
writeLn(p);
end;
+
end.</syntaxhighlight>
</syntaxhighlight>
+
This assigns <syntaxhighlight lang="pascal" inline>p</syntaxhighlight> the address of an invisible ''constant'' value.
 +
That means you are not allowed to alter any component of this value.
 +
Something like <syntaxhighlight lang="pascal" inline style="white-space: nowrap;">p[0] := 'f'</syntaxhighlight> will crash.
 +
(Enforced since [[User Changes 3.0#Literal storage memory has been made read-only|FPC 3.0.0]])
 +
 
 +
=== routines ===
 +
[[Write|<syntaxhighlight lang="pascal" inline>Write</syntaxhighlight>/<syntaxhighlight lang="pascal" inline>writeLn</syntaxhighlight>]] can accept a <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> and take it as a null-terminated string (provided the destination is a [[Text|<syntaxhighlight lang="pascal" inline>text</syntaxhighlight> file]]).
 +
Conversely [[WriteStr|<syntaxhighlight lang="pascal" inline>writeStr</syntaxhighlight>]] does not support <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight>.
 +
 
 +
The standard [[RTL|run-time library]] provides many handy functions:
 +
* {{Doc|package=RTL|unit=system|identifier=strlen|text=<syntaxhighlight lang="pascal" inline>system.strlen</syntaxhighlight>}} determines the length of a null-terminated string. The <syntaxhighlight lang="pascal" inline>length</syntaxhighlight> function does this too.
 +
* {{Doc|package=RTL|unit=system|identifier=strpas|text=<syntaxhighlight lang="pascal" inline>system.strPas</syntaxhighlight>}} converts a null-terminated string to a [[Shortstring|<syntaxhighlight lang="pascal" inline>shortString</syntaxhighlight>]].
 +
* All functions in the {{Doc|package=RTL|unit=strings|text=<syntaxhighlight lang="pascal" inline>strings</syntaxhighlight> unit}}.
  
Declaration:
+
There is also <syntaxhighlight lang="pascal" inline>{$modeSwitch PCharToString}</syntaxhighlight>/<syntaxhighlight lang="bash" inline>‑MPCharToString</syntaxhighlight> ''automatically'' interpreting <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> values as null-terminated strings and ''automatically'' converting them ''to'' the destination’s <syntaxhighlight lang="pascal" inline>string</syntaxhighlight> data type.
<syntaxhighlight>
 
var
 
  p: PChar;
 
</syntaxhighlight>
 
  
Valid assignments:
+
=== data types ===
<syntaxhighlight>
+
The [[Ansistring#implementation|<syntaxhighlight lang="pascal" inline>ANSIString</syntaxhighlight> data type]] is a pointer to a <syntaxhighlight lang="pascal" inline>char</syntaxhighlight> and always ends with a ''complimentary'' null-Byte which allows direct [[Typecast|typecasting]] to <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight>:
  p := 'This is a null-terminated string.';
+
<syntaxhighlight lang="delphi" highlight="7">program ansiStringAsPCharDemo(output);
  p := IntToStr(45);
+
var
</syntaxhighlight>
+
s: ANSIString;
 +
p: PChar;
 +
begin
 +
s := 'foobar';
 +
p := PChar(s);
 +
writeLn(p);
 +
end.</syntaxhighlight>
 +
Beware that this works well only as long as you are merely ''reading from'' the typecasted value.
 +
Also note that an <syntaxhighlight lang="pascal" inline>ANSIString</syntaxhighlight> ''is allowed'' to contain <syntaxhighlight lang="pascal" inline>chr(0)</syntaxhighlight> ''as'' payload.
  
Invalid assignments:
+
{{Note|If you intend to ''alter'' data ''via'' the pointer, you possibly want to call {{Doc|package=RTL|unit=system|identifier=uniquestring|text=<syntaxhighlight lang="pascal" inline>uniqueString</syntaxhighlight>}} before you do the typecast.}}
<syntaxhighlight>
 
  p := 45;
 
</syntaxhighlight>
 
The integer value is not casted to a PChar as might be expected.
 
  
== See also ==
+
== caveats ==
 +
The <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> data type used as a null-terminated string data type is rather an anomaly in the Pascal world.
 +
It has many caveats:
 +
* The definition of <syntaxhighlight lang="pascal" inline>char</syntaxhighlight> depends on <syntaxhighlight lang="pascal" inline>{$modeSwitch unicodeStrings}</syntaxhighlight>, that means in FPC 3.2.0 it could either refer to a 1‑Byte or 2‑Byte quantity. Most noticeably, this affects the offset if you are using pointer arithmetic, e.&#8239;g. [[Inc and DecSpecial behaviors|<syntaxhighlight lang="pascal" inline>inc(PCharVariable)</syntaxhighlight>]]. See [[FPC Unicode support]] for more details.
 +
* ''In Pascal'' a <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> is just that: a ''pointer'' to a single <syntaxhighlight lang="pascal" inline>char</syntaxhighlight> value.
 +
** That means the ''string concatenation'' [[Plus|operator&nbsp;<syntaxhighlight lang="pascal" inline>+</syntaxhighlight>]] does ''not'' work. If <syntaxhighlight lang="pascal" inline>{$pointerMath on}</syntaxhighlight> it will rather refer to arithmetic addition. You will need to use, for instance, {{Doc|package=RTL|unit=strings|identifier=strcat|text=<syntaxhighlight lang="pascal" inline>strings.strCat</syntaxhighlight>}} instead.
 +
** Also the comparison operator&nbsp;<syntaxhighlight lang="pascal" inline>=</syntaxhighlight> will in fact compare ''addresses''. Use, for instance, {{Doc|package=RTL|unit=strings|identifier=strcomp|text=<syntaxhighlight lang="pascal" inline>strings.strComp</syntaxhighlight>}} to compare the referenced null-terminated string values, unless you really want to ensure two null-terminated strings are ''identical'' (=&nbsp;share the same memory).
 +
* Debugging is more difficult, confer [[FpDebug#Strings (vs PChar and Array of Char)|FPDebug]].
 +
Using a <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> ''just'' as a ''regular'' pointer to a ''single'' <syntaxhighlight lang="pascal" inline>char</syntaxhighlight>, however, does not have any special caveats.
 +
 
 +
== comparative remarks ==
 +
* Delphi supports <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> as a null-terminated string.
 +
* The [[GNU Pascal|GPC]] has a special data type <syntaxhighlight lang="pascal" inline>CString</syntaxhighlight> which behaves like a null-terminated string. In GPC <syntaxhighlight lang="pascal" inline>PChar</syntaxhighlight> is otherwise just a pointer.
 +
 
 +
== see also ==
 
* [[Character and string types]]
 
* [[Character and string types]]
 
+
* [[Pascal for C users]]
[[Category:Data types]]
 

Latest revision as of 13:14, 3 September 2021

Deutsch (de) English (en) español (es) français (fr) русский (ru)

The data type PChar is a pointer to a single char. PAnsiChar is an alias for PChar.

type
	PChar = ^char;
	PAnsiChar = PChar;

special support

A PChar could be interpreted as a pointer to NULL-terminated string data type value on the heap. This means this string value ends with chr(0). This kind of storing data is rather unsafe and Pascal’s own string data types always indicate an explicit (maximum) length. However, many libraries written in other programming languages make use of this dangerous data type and in order to facilitate interaction with them the FPC provides special support (only available in non-ISO modes).

direct assignments

A string literal can be assigned directly to a PChar:

program PCharDemo(output);
var
	p: PChar;
begin
	p := 'Foobar';
	writeLn(p);
end.

This assigns p the address of an invisible constant value. That means you are not allowed to alter any component of this value. Something like p[0] := 'f' will crash. (Enforced since FPC 3.0.0)

routines

Write/writeLn can accept a PChar and take it as a null-terminated string (provided the destination is a text file). Conversely writeStr does not support PChar.

The standard run-time library provides many handy functions:

There is also {$modeSwitch PCharToString}/‑MPCharToString automatically interpreting PChar values as null-terminated strings and automatically converting them to the destination’s string data type.

data types

The ANSIString data type is a pointer to a char and always ends with a complimentary null-Byte which allows direct typecasting to PChar:

program ansiStringAsPCharDemo(output);
var
	s: ANSIString;
	p: PChar;
begin
	s := 'foobar';
	p := PChar(s);
	writeLn(p);
end.

Beware that this works well only as long as you are merely reading from the typecasted value. Also note that an ANSIString is allowed to contain chr(0) as payload.

Light bulb  Note: If you intend to alter data via the pointer, you possibly want to call uniqueString before you do the typecast.

caveats

The PChar data type used as a null-terminated string data type is rather an anomaly in the Pascal world. It has many caveats:

  • The definition of char depends on {$modeSwitch unicodeStrings}, that means in FPC 3.2.0 it could either refer to a 1‑Byte or 2‑Byte quantity. Most noticeably, this affects the offset if you are using pointer arithmetic, e. g. inc(PCharVariable). See FPC Unicode support for more details.
  • In Pascal a PChar is just that: a pointer to a single char value.
    • That means the string concatenation operator + does not work. If {$pointerMath on} it will rather refer to arithmetic addition. You will need to use, for instance, strings.strCat instead.
    • Also the comparison operator = will in fact compare addresses. Use, for instance, strings.strComp to compare the referenced null-terminated string values, unless you really want to ensure two null-terminated strings are identical (= share the same memory).
  • Debugging is more difficult, confer FPDebug.

Using a PChar just as a regular pointer to a single char, however, does not have any special caveats.

comparative remarks

  • Delphi supports PChar as a null-terminated string.
  • The GPC has a special data type CString which behaves like a null-terminated string. In GPC PChar is otherwise just a pointer.

see also