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.

   A simpler and safer method for dynamic allocation /deallocation is to 
   use the advanced New / Delete keyword (which itself also calls the 
   constructor / destructor of the string object).

   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 (numeric constant, or expression 
   that can be evaluated at compile time) 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.
   Note: It is not recommended to use explicit NULL character (Chr(0)) in a 
   string expression involving a fixed length string variable because this 
   can lead to different unexpected results depending on usage context 
   (initialization, assignment, concatenation, ...).

   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.

Example

   '' Variable length
   Dim a As String

   a = "Hello"
   Print a

   a += ", world!"
   Print a

   Dim As String 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)
   Dim As String 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

   Dim As String status = "OK"

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

Differences from QB
   * In QB the strings were limited to 32767 characters.
   * In QB, the unused characters of a fixed-length string were 
     initialized with 32 (space, or " ", in ASCII).
   * In QB static or fixed-size strings were often used in records to 
     represent a number of bytes of data;  for example, a string of 1 
     length to represent 1 byte in a UDT read from a file.  This is not 
     possible in FreeBASIC since strings always have an NULL character 
     following.  When converting QBasic code that reads UDTs from files, 
     make sure all instances of "As String * n" are replaced with "As uByte 
     (0 to n - 1)" or your files will be incompatible.

See also
   * String (Function)
   * Space
   * ZString
   * WString
   * Str
   * StrPtr
   * VarPtr
   * Standard Data Type Limits
   * Operator [] (String Index)
   * String Operators

