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

