ZString

Standard data type: 8 bit character string

Syntax
	KeyPgDimDim variable KeyPgAsAs ZString * size
	KeyPgDimDim variable KeyPgAsAs ZString KeyPgPtr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 KeyPgPtrPtr can point to a standard ZString, also can be used to 
	implement an "user-managed" ZString, in this case KeyPgAllocateAllocate/KeyPgReallocateReallocate/
	KeyPgDeallocate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. KeyPgChrChr(0)) may never be contained in the text of a 
	ZString or the rest of the string will be truncated.

	In a ZString, KeyPgLenLen returns the size of the contained string and KeyPgSizeofSizeOf 
	returns the space allocated to the ZString.  KeyPgSizeof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 KeyPgByrefByRef function 
	argument.

	Any intrinsic string functions like KeyPgLeft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 KeyPgPtrPtr. The compiler performs itself an 
	automatic conversion (without warning message) between any string type 
	argument and the ZString KeyPgPtrPtr type parameter.

	When allocating dynamic memory for a ZString, the safest is to use 
	KeyPgCallocateCAllocate (or at worst, to use KeyPgAllocate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 CompilerOptlang-lang qb dialect unless referenced with the 
	  alias __Zstring.

Differences from QB
	* New to FreeBASIC

See also
	* KeyPgStringString
	* KeyPgWstringWString
	* TblVarTypesStandard Data Type Limits
	* KeyPgExtendsZstringExtends Zstring

