Blitz:String Handling

From AmigaBlitzWiki
Jump to: navigation, search

String variables, or strings, are variables that hold a string of characters instead of simply a numeric value like other variables. Strings in Blitz are handled similarly to strings in most other BASIC dialects.

Declaring and Assigning Strings

String variables for the most part can be treated as just another variable type, with declarations and assignments carried out the very same way. Traditionally, string names in BASIC have always been appended with the $ character to distinguish them from numerical variables. Blitz uses this format too, but can also use the .s extension instead, just like a .l for long or a .f for float.

To declare a string, you can use the DefType statement:

DefType .s MyString1, MyString2

Strings can also be declared at the time of first use:

MyAnswer.s = Edit$(10)
MyName$ = "Joe Bloggs"

These two examples show the alternative string designations, .s and $, and how to assign the results of a function or a literal string to the variable. Only one should be used for a variable. The $ character must be appended to the name every time it is used (as with other BASICS), whereas the .s extension is only necessary for the first use or declaration.

String Size

Blitz does not require the string length to be declared; it will resize the variable dynamically as it is used, up to a maximum of the string buffer size set in the Compiler Settings. However, some situations require the size to be pre-allocated (as it is in C and some other languages), generally OS calls that write a results string directly into a variable since they expect to write to pre-allocated memory. This can bypass Blitz's mechanism for string resizing which can cause serious problems if you're unlucky.

To pre-allocate the space for a string, use the Maxlen statement:

Maxlen MyString$ = 512

This will allocate 512 bytes of space for the string MyString$, which can then be written to directly without having to resize it.

String Functions

Blitz supports the common BASIC string operations, in addition to more advanced operations borrowed from other languages. Copying strings is simply an assignment like a numerical variable, and concatenating strings is performed using the + operator:

a$ = result$ ; Copy the contents of result$ into the variable a$

a$ = "Result: " + result$ ; Create a string containing "Result: " followed by the contents of result$ and store the whole string in a$

Some other useful string handling functions:

Left$(string$, chars)
This function returns chars number of characters from the left of the string string$. For example:
result$ = Left$("Test String", 3)

Will store the string "Tes" in result$.

Right$(string$, chars)
Similar to Left$() only it returns the rightmost chars characters instead.
Mid$(string$, pos, [chars])
Returns chars number of characters of string string$, starting at character pos. If the chars argument is left out, Mid$ will return all the characters from pos to the end of the string.
Instr(string$, findstring$ [,pos])
Searches for findstring$ within string$, starting at character pos. If pos is left out, searching starts at the first character. This function returns the character where the found string starts inside string$, or 0 if it wasn't found.
Chr$(char)
Returns the single character string representation of the ASCII code char.
UnLeft$(string$, chars)
Removes the rightmost chars characters from the string string$ and returns the result
UnRight$(string$, chars)
Removes the leftmost chars characters from the string string$ and returns the result
LCase$(string$)
Returns the lower case equivalent of string$
UCase$(string$)
Returns the upper case equivalent of string$

More useful string functions are available, see the Blitz manual string functions section for more details.

Escape Sequences

AmiBlitz adds the ability to include escape sequences in strings. This allows special characters to be easily inserted into strings, where Blitz Basic requires the string to be assembled from Chr$() functions and so on. An escape sequence consists of two backslashes (\\)followed by the escape code, or an ASCII code in hex for a character. Useful escape sequences include:

\\n
Newline character. Causes a line break to be inserted into the string at that point. Equivalent to inserting ASCII character 10.
\\22
Double quote mark. Inserts a double quote in the string. 22 is the hexadecimal value for the standard quote mark.
\\__DATE_GER__
Compilation date in European format, suitable for Amiga embedded version strings (dd.mm.yyyy).
\\__DATE__
Compilation date in American format. Not suitable for standard Amiga embedded version strings (mm/dd/yyyy).

For example:

NPrint "\\22Quoted Text\\22 on the first line\\nThis is the second line\\nCompiled on \\__DATE_GER__"

Will produce the following output:

"Quoted Text" on the first line
This is the second line
Compiled on 31.08.2015