ugBASIC User Manual

Strings handling

This section will show you how to handle strings through instructions. Infact, ugBASIC has a full range of string manipulation instructions, and experienced Basic programmers should already be familiar with the standard syntax used.

Extracting Finding Converting Manipulating Informations

Extracting and replacing chars

The first that we show is LEFT$ (also shortened as LEFT). It reads the specified number of characters in a source string, starting from the left-hand side, and copies them into a destination string. The first type of usage of this function creates a new destination string from the chosen number of characters of the source string.

a = "ugBASIC COMPILER"
b = LEFT$( a, 7 )
PRINT b: REM It print out "ugBASIC"

The second usage is to replace the leftmost number of characters:

a$ = "******* COMPILER"
LEFT$( a$, 7 ) = "ugBasic"
PRINT a$: REM It print out "ugBASIC COMPILER"

Exactly the same processes can be performed with the other side of the string by using the RIGHT$ (RIGHT) function:

a$ = "ugBASIC ********"
RIGHT$( a$, 7 ) = "COMPILER"
PRINT a$: REM It print out "ugBASIC COMPILER"
b$ = RIGHT$( a$, 7 )
PRINT b$: REM It print out "COMPILER"

Similarly, the MID$ (also abbreviated as MID) function returns characters from the middle of a string, with the first number specified in brackets setting the offset from the start of the string and the second number setting how many characters are to be fetched. If the number of characters to be fetched is omitted from your instruction, then the characters will be read right up to the end of the string being examined.

Some examples:

PRINT MID("ugBASIC", 6): REM it prints out "C"
a = "ugBASIC"
MID(a, 6, 1) = "X"
PRINT a: REM "ugBASIX"

Finding characters in a string

If you need to search through strings for individual characters or sub-strings, there is a specific instruction, called INSTR. This is very useful if you want to write an adventure game where lines of text must be broken down into individual commands. INSTR allows you to search for all instances of one string inside another.

In the following examples, the first string is searched for the first occurrence of the second strings. If it is found, its location will be reported in the form of the number of characters from the left-hand side of the searched string. If the search is unsuccessful, a result of zero will be given.

PRINT INSTR( "ugBASIC", "ugBASIC"): REM Print 1
PRINT INSTR( "ugBASIC", "O"): REM Print 0
PRINT INSTR( "ugBASIC", "A"): REM Print 4

Normally, the search will begin from the first character at the extreme left-hand side of the host string, but you can specify an (optional) number of characters from the beginning of the searched string. The optional start-of-search position can range from zero to the maximum number of characters in the searched string to be searched.

For example:

PRINT INSTR( "ugBASIC", "ugBASIC", 2): REM Print 0
PRINT INSTR( "ugBASIC", "A", 3): REM Print 4
PRINT INSTR( "ugBASIC", "A", 5): REM Print 0


Converting strings

When you need to convert the characters in a string into upper case (capital) letters, you can use the UPPER$ (shortened as UPPER) functions that generates a new string. The same if you need to convert to lower case a string, by using LOWER$ (LOWER). These sorts of text conversions are particularly useful for interpreting user-input in interactive data programs and adventure games, because input can be converted into a standard format which is understood by your programs.

PRINT UPPER$("ugBasic") : REM it prints out "UGBASIC"
PRINT LOWER$("ugBasic") : REM it prints out "ugbasic"
PRINT UPPER$(LOWER$("ugBasic")) : REM it prints out "UGBASIC"

In ugBASIC numbers can be converted into strings by using the STR$ (shortened as STR) function. This can be used to overcome some limitations posed by functions which does not accept numbers as parameters, but will work happily with parameters in the form of strings. Also, when string adding is performed, all operand must be strings.

It is an example:

PRINT "The answer is " + STR$(42): REM It prints out "The answer is 42"

To perform the reverse task, you can use the VAL function. It converts a list of decimal digits stored in a string, changing them into a number. Note that a result of zero is returned if this process fails for any reason. For example:

x = VAL("42"): PRINT x: REM it prints 42
y = VAL("is42"): PRINT y: REM it prints 0

Finally, the STRING$ function (abbreviated as STRING) can be used to create a new string filled with the required number of copies of the first character from an existing string. The following example produces a new string containing ten copies of the character “u”.

PRINT STRING("ugBASIC is a compiler",10)

Manipulating strings

There are some functions to handle string in a very special way. For example, you can produce a certain number of spaces by using the function SPACE$ (SPACE). Or you could flip your string, reversing the order of letters, by simply calling FLIP$ (or FLIP). For example:

PRINT FLIP$("ugBASIC"): REM print out "CISABgu"
PRINT FLIP$(FLIP$("ugBASIC")): REM print out "ugBASIC"


Getting information about strings

The CHR$ function creates a string that contains a single character, generated by a given ASCII code number. Note that, depending on the hardware, only some characters are printable on the screen. Others are used internally as control codes. For example:

i = 0: FOR i = 32 TO 255: PRINT CHR(i): NEXT

On the opposite side, if you need to get the internal ASCII code of the first character in a string, you can use the ASC function:

PRINT ASC("A"): REM print out 65

Finally, the LEN function returns the number of characters stored in a string.

a = "ugBASIC"
PRINT LEN(a): REM print out 7

Any problem?

If you have found a problem, if you think there is a bug or, more simply, you would like something to be improved, write a topic on the official forum, or open an issue on GitHub.

Thank you!