====== ugBASIC User Manual ======

===== STRING HANDLING =====

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

==== 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 )
    PRINTb: 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