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, 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.

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 intrinsic string functions like Left will work with Zstring's too, plus any string operator.

Note : When any operand of the '=' operator (assignment or equal) consists in dereferencing a 'Zstring Ptr' pointer ('pz'), this can give a 'Zstring' string or a 'Ubyte' character, 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]').

Examples:
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:
Differences from QB:
See also:
Back to Standard Data Types
Back to String Functions
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode