ZString
Standard data type: 8 bit character string
Syntax
`
Dim variable As ZString * size
Dim variable As ZString Ptr
`
Description
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]`').
Example
`
Dim As ZString * 13 str1 => "hello, world"
Print str1
Print Len(str1) 'returns 12, the size of the string it contains
Print SizeOf(str1) 'returns 13, the size of the variable
`
`
Dim As ZString Ptr str2
str2 = Allocate( 13 )
*str2 = "hello, world"
Print *str2
Print Len(*str2) 'returns 12, the size of the string it contains
`
Dialect Differences

- Not available in the -lang qb dialect unless referenced with the alias `__Zstring`.

Differences from QB

- New to FreeBASIC

See also

- `String`
- `WString`
- `Standard Data Type Limits`
- `Extends Zstring`