STRING


Standard data type: 8 bit character string

Syntax:
dim variable as String [ * size]

Description:
A String is an array of characters.

A String declared without the size parameter is dynamically resized depending on the length of the string. The length can range from 0 bytes to 2 gigabytes. A descriptor contains a pointer to the actual string, the length of the string, and the amount of space allocated for it. Varptr will return a pointer to the descriptor, while Strptr will point to the actual string.

Because of the hidden descriptor with a String, manual allocation of space, for example using the memory allocation function Callocate (preferentially), for a String is not encouraged. The common way to ensure a certain amount of space is reserved for a String, to prevent unnecessary allocations inside a loop for instance, is to use the Space or String functions.

Nevertheless if necessary, dynamic allocation may be carefully used by means of the memory allocation functions Allocate, Callocate, Reallocate (see precautions for use) and string pointer (which is a pointer to a string descriptor, not string data). When memory is allocated to hold string descriptors, the string must always be destroyed (setting to "") before deallocate each string descriptor (allowing to deallocate the memory taken up by the string data), otherwise, it is not possible to deallocate it later, and it may induce memory leak in the program continuation.

Despite the use of the descriptor, an implicit NULL character (chr(0)) is added to the end of the string, to allow passing them to functions in external libraries without making slow copies. FreeBASIC's internal functions will ignore this character, and not treat it as part of the string.

A String declared with a fixed size is a QB-style fixed length string, with the exception that unused characters are set to 0, regardless of what "-lang" compiler option is used. It has no descriptor and it is not resized to fit its contents. As in QB, if data overflows the size of the string, it is truncated on the right side.
Fixed length strings are also terminated with a NULL character, and so they use size + 1 bytes of space. This NULL terminator may be removed in future, to prevent the redundant character complicating data layout in user-defined Types.

String variable names need not end in a dollar sign $ as in other dialects of BASIC. In lang fb variable suffixes, including the dollar sign, are disallowed entirely.

Examples:

'' Variable length
Dim a As String

a = "Hello"
Print a

a += ", world!"
Print a

Var b = "Welcome to FreeBASIC"
Print b + "! " + a


'' QB-like $ suffixes
#lang "qb"

'' DIM based on $ suffix
Dim a$
a$ = "Hello"

'' Implicit declaration based on $ suffix
b$ = ", world!"

Print a$ + b$


'' Variable-length strings as buffers

'' Reserving space for a string,
'' using Space() to produce lots of space characters (ASCII 32)
Var mybigstring = Space(1024)
Print "buffer address: &h" & Hex( StrPtr( mybigstring ), 8 ) & ", length: " & Len( mybigstring )

'' Explicitly destroying a string
mybigstring = ""
Print "buffer address: &h" & Hex( StrPtr( mybigstring ), 8 ) & ", length: " & Len( mybigstring )


'' Variable-length string as Const parameter

'' Const qualifier preventing string from being modified
Sub silly_print( ByRef printme As Const String )
    Print ".o0( " & printme & " )0o."
    'next line will cause error if uncommented
    'printme = "silly printed"
End Sub

Var status = "OK"

silly_print( "Hello FreeBASIC!" )
silly_print( "Status: " + status )


Differences from QB:
See also:
Back to Standard Data Types
Back to String Functions
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki



sf.net phatcode