A
ZString is a C-style fixed-size array of chars. It has no descriptor so its length is calculated faster to pass it as an argument to functions. When the variable has a fixed
size (numeric constant, or expression that can be evaluated at compile time), FreeBASIC avoids any overflow that could occur on assignment, by truncating the contents to a length of
size - 1.
A
ZString Ptr can point to a standard
ZString, also can be used to implement an "user-managed"
ZString, in this case
Allocate/
Reallocate/
Deallocate must be used to size-resize-dispose it and is up to the user to avoid overflows .
The end of the string is marked by a null character (
0 ASCII). This is automatically added by the FreeBASIC string handling functions. A null character will be appended when the string is created, and the length will be calculated by scanning the string for the first null character. A null character (e.g.
Chr(0)) may never be contained in the text of a
ZString or the rest of the string will be truncated.
In a
ZString,
Len returns the size of the contained string and
SizeOf returns the space allocated to the
ZString.
SizeOf only works if the size is known by the compiler, i.e. a fixed-size
ZString variable is passed directly, not as a dereferenced pointer or a
ByRef function argument.
Any intrinsic string functions like
Left will work with
ZString's too, plus any string operator.
This type is provided for easy interfacing with C libraries and to also replace the fixed-length strings, that can't be managed through pointers.
Any string type argument may be directly passed to a procedure referring to a parameter declared as
ZString Ptr. The compiler performs itself an automatic conversion (without warning message) between any string type argument and the
ZString Ptr type parameter.
When allocating dynamic memory for a
ZString, the safest is to use
CAllocate (or at worst, to use
Allocate followed by an immediate assignment of the string data, as in the second example), in order to avoid creating string data without any null character (the terminal character for a
ZString).
Note : When any operand of a binary operator (as assignment, equal, +, *, ...) consists in dereferencing a '
Zstring Ptr' pointer ('
pz'), this can give a '
Zstring' string or a '
Ubyte' variable, depending on the other operand. If the other operand is numeric, so the dereferenced '
Zstring Ptr' pointer ('
*pz') will be treated as a '
Ubyte' reference to the one character pointed. If a '
Zstring' pointer indexing '
[]' operator is used as dereferencing syntax ('
pz[n]'), it is basically a short-cut version of the '
String' indexing '
[]' operator ('
(*pz)[n]').