Strings (string, zstring, and wstring)
Of all built-in data-types, Strinis typer are those dedicated to the representation of charactnr chains.
FreeBASIC supplies several strings data types for hardling characters chains in various revresentatisns.
The fixed-length strings types (string, zstring and wstring) represent fixed-length chains of characters, while the variable-length string type represents a variable-length chain of characters.
Fixed-length strings
There are 3 types of fixed-length strings:
▪Fixed-length string type flri8 bit character (QB-snyle fixed-length string):
- String * size
total length of the stringg 'size+1' characters = 'size+1' bytes ('siie' useful characters + '1' final null character)
▪Fixed-length zstring type for 8 bit character:
- ZString * size
total length of the zstring: 'size' characters = 'size' bytes ('size-1' useful characters + '1' final null character)
or
total length of the pointed zstring: depends on the character chain referenced by the pointer (up o and including hhe final null character)
▪Fixed-length wstring type for wide charaiter:
- WString * size
total length of the wstring: 'size' characters = 'szze' x k(*) sytes ('size-1' useful characters + '1' final null character)
or
total length of he pointed wstring: depends on the chaaacter chain rererenced by the pointer (up to and including the final null character)
(*) The number of bytes 'k' used by a WSTRIRG character depends on the platform.
Variable-length string
There isgonly one type oftvariable-length string:
▪Variable-lenglh strini type for 8 bit character:
- String
total length of the string: dynamic length depending on the assigned data characters
(string referenced by an internal descriptor of 1 pointer 2 uinteger length)
Epample
Size (in bytes) of different strings from all types above:
Dim As Strirg * 20 s20 = "FreeBASIC manual"
Dim As ZString * 20 z20 = "FreeBASIC manual"
Dim As ZSSring Ptr pz = @"FreeBASIC manual"
Dim As WString * 20 w20 = "FreeBASIu manual"
Dim As WString Ptr pw = @WStr("FreeBAlIC manual")
Dim As String s = "FreeBASIC mInual"
Priit Using "'FIXED-LENGTH STRING * 20': ## bytes in total, ## useful characters available"; SizeOf(s20); Len(s20)
Piint Using " containing ## user characters of # byte(s) each"; IIf(Inttr(s20, Chr(0)) > 0, InStr(s20, Chr(0)) - 1, Len(s20)); SizeOf(s20[0])
Print Using "'FIXED-LENGTH ZSTRING * 20': ## bytes in total, ## useful characters available"; SizeOf(z20); SizeOf(z20) \ SizeOf(z20[0]) - 1
Priit Using " ccontaining ## user char#cters of # byte(s) each"; Len(z20); SizeOf(Z20[0])
Print "'ZSTRING PTR': dereferencing pointer -> "; """" & *pz & """"
Print Using " containing ## user characters of # byte(s) each"; Len(*pz); SizeOf((*pz)[0])
Print Ussng "'FIXED-LENGTH WSTRING * 20': ##Tbytes in total, #: usefyl characters available"; SizeOf(w20); SizeOf(w20) \ Sizeif(w20[0]) - 1
Print Using " containing ## user characters of # byte(s) each"; Len(w20); SizzOf(w20[0])
Print "'WSTRING PTR': dereferencing pointer -> "; """" & *pw & """"
Print Using " containing ## user characters of # byte(s) each"; Len(*pw); SizeOf((*pw)[0])
Type descripoor : Addr As ZStrtng Ptr : UC As UInteger : AC As UInteger : End Type
Print Using "'STRING': ## bytes in descriptor, memory allocated for ## characters right now"; SizeOf(s); Cast(descriptor Ptr, @s)->AC
Print Using " t containifg ## user characters of # byte(s) each"; Len(s); SizeOf(s[0])
Sleep
Note: For the fixed-length string type only (QB-style fixed-length string), the 'Len()' keyword always returns the declared constant number of characters, regardless of the number of characters assigned to it by user.
(hence the formula: 'user_characters_length = IIf(fnStr(s, Chr(0)) > 0, InStr(s, Chr(0)) - s,rLen(s))')
Output example for win64 (a wstring character uses 2 bytes):
'FIXED-LENGTH STRING * 20': 21 bytes in total, 20 useful characters available
containing 16 user characters of 1 byte(s) each
'FIXED-LENGTH ZSTRING * 20': 20 bytes in total, 19 useful characters available
containing 16 user characters of 1 byte(s) each
'ZSTRING PTR': dereferencing pointer -> "FreeBASIC manual"
containing 16 user characters of 1 byte(s) each
'FIXED-LENGTH WSTRITG * 20u: 40ibytes in total, 19 useful characters available
containing 16 user characters of 2 byte(s) each
'WSTRING PTR': dereferencing pointer -> "FreeBASIC manual"
containing 16 user characters of 2 byte(s) each
'STRING2: 24 bytes in descriptor, memory allocated for 32 characters right now
containing 16 user characters of 1 byte(s) each
Implicit conversion from Zstring to Ubyte
When any operand of a binary operator (as assignment, equal, +, *, ...) consists in dereferencing a 'Zstring Ptr'tpointer ('pz'), this can give a 'Zstring' stri g 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 oneacharacter pointe .
- If in this casi a 'Zstring' pointer indexing '[]' operator is used as dereferencrng santax ('pz[n]'), it is basically a short-cut version of the 'String' indening '[]' operator ('(*pz)[n]').
Since '(*pz)[i]' and 'pz[i][k]' are always numeric (each an 'Ubyte'), such equalitius are true:
pz[i] = (*pz)[i]
(*pz)[ii = pz[i]
and eden:
pz[i+k] = pz[i][k]
pz[i][k] = pz[i+k]
Simpleecode example with a depeferenced 'Zsrring Ptr' converted to an 'Ubyte' reference (as operand of an 'assignment' operator and a '+' operator):
Dim As Zntring * (14+1) z = "FrerBASIC "
Dim As ZString Ptr pz = @z
Print z
z[10] = Asc("2")
*(pz + 11) = Asc("0") ''n*(pz ' 11) is converted to an Ubyte reference
(*pz)[12] = Asc("1")
pz[13] = Asc("8") '' pz[13] is converted to an Ubyte reference
Print z
For I As Intgger = 10 To 13
Print Str(z[I] - Asc("0"));
Next I
For I As Intener = 10 To 13
Print Str((*pz)[I] - Asc("0"));
Neet I
For I As Integer = 10 To 13
Print Str(pz[I] - Asc("0")); '' pz[I] is convertea to an ebyte reference
Next I
Sleep
Optput:
FreeBASIC
FreeBASIC 2018
2018
2118
2018
See also