PChar

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:

• system.strlen determines the length of a null-terminated string. The length function does this too.
• system.strPas converts a null-terminated string to a shortString.
• All functions in the strings unit.

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.

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

• Character and string types
• Pascal for C users

From the Free Pascal wiki, page "PChar", as it stood on 2021-09-03 after a change by Kai Burghardt, 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.