Fixed-length strings

As their name implies, fixed-length strings have a pre-defined length, and any attempt to assign a string longer than the defined length will result in truncation.  If you assign a string to a fixed-length string that is shorter than the defined length, the string will be padded on the right with spaces.  The major difference between dynamic strings and fixed-length strings is that once defined, the length of a fixed-length string cannot be changed.  It is "fixed" for the duration of program execution.

You declare fixed-length string variables using STRING * x (for ANSI characters) or WSTRING * x (for WIDE characters).  For example

DIM MyStr1 AS STRING  * 10  ' occupies 10 bytes

DIM MyStr2 AS WSTRING * 10  ' occupies 20 bytes

The declared length refers to the number of characters, not the number of bytes.  Unlike dynamic strings, the length of fixed-length strings is determined at compile-time, not run-time.  In addition, unlike dynamic strings, fixed-length strings do not use handles.  When you pass a fixed-length string to a procedure as a parameter, you are actually passing a pointer to the string data.

In PowerBASIC (and most versions of BASIC), new fixed-length strings (and all variables) are initialized by filling with nuls, CHR$(0). When you assign a value, that text is padded to the right with the fill character, which defaults to a space).

A declaration of a fixed-length string or fixed-length string pointer must explicitly state the length of the variable, because the compiler must know it to allocate memory, and to pad the variable with spaces upon assignment.

The address of the contents of a fixed length string can always be obtained with the VARPTR function.  LOCAL fixed-length string memory is released when the associated Sub, Function, Method, or Property ends.  Subsequent calls to the routine will result in new storage locations for the fixed-length string data; however, the location of a LOCAL fixed-length string does not move until the string memory is released when the routine terminates.

LOCAL fixed-length strings are created on the stack frame, so LOCAL fixed-length strings will be limited to available stack space.  Typically this is less than 1 MB unless a larger stack frame has been allocated with the #STACK metastatement.  If larger fixed-length strings are required, it is advisable to make them INSTANCE, STATIC, or GLOBAL, since those are not created within the stack frame.

The address of the contents of STATIC and GLOBAL fixed-length strings stays constant for the duration of the module.  STATIC and GLOBAL Scalar (non-array) fixed-length strings may be up to 16,777,216 bytes each.


See Also

Nul-Terminated Strings

Dynamic (Variable-length) strings ($)

FIELD strings

String expressions