====== String Functions ======
String functions are provided to assist the user in accessing and modifying
data within a String.

===== DP(value, numberOfDigits, zeroPrint) =====

DP converts a variable into a decimal string representation.

If zeroPrint is set to 1, zeros are printed instead of blank spaces.

<code xbasic>
Dim A as Integer
Debug DP(A,10,0)      ' Convert A into decimal String representation.
                      ' Set display decimalPlaces to 10.
                      ' If A is 1234, " 1234" will be displayed.
                      ' (notice the 6 blank spaces)
Debug DP(A,10,1)      ' If A is 1234, 0000001234 will be displayed.
</code>

{{ :cubloc:type_conversion:dp_function.png?nolink |}}

===== HP(value, numberOfDigits, zeroPrint) =====

HP converts a variable into a hexadecimal string representation. If
ZeroPrint is set to 1, zeroes are substituted for blank spaces.

<code xbasic>
Debug HP(A,4,0)       ' Convert A into HEX String representation
                      ' Set display decimal places to 4.
                      ' If A is ABC, bABC will be displayed.
                      ' (b stand for blank spaces.)
Debug HP(A,4,1)       ' If A is ABC, 0ABC will be displayed.
</code>

{{ :cubloc:type_conversion:hp_function.png?nolink |}}

===== FP (value, wholeNumberDigits,fractionalNumberDigits) =====

FP converts floating point variables into a formatted string with user defined
whole and fractional number of digits.

<code xbasic>
Dim A as Single
A = 3.14
Debug Float A           ' 3.1400000 Prints all digits.
Debug FP(A,3,2)         ' 3.14 Print user defined digits.
</code>

With the FP function, the user can control the number of digits to be used
for string data when using Debug or displaying to an LCD.

{{ :cubloc:type_conversion:fp_function.png?nolink |}}

Cubloc floating-point values are stored in accordance to the IEEE724
format. The output of FP and Float may differ but the value stored in the
variable will be the same.

===== Left(stringValue, numberOfCharacters) =====
Returns a specified number of characters from the left side of a String

<code xbasic>
Dim ST1 As String * 12
ST1 = "CUBLOC"
Debug Left(ST1,4)           ' "CUBL" is printed.
</code>

===== Right(stringValue, numberOfCharacters) =====
Returns a specified number of characters from the right side of a String.

<code xbasic>
Dim ST1 As String * 12
ST1 = "CUBLOC"
Debug Right(ST1,4)           ' "BLOC" is printed.
</code>

===== Mid(stringValue, location, numberOfCharacters) =====

Returns a specified number of characters from a string starting at a specified location.

<code xbasic>
Dim ST1 As String * 12
ST1 = "CUBLOC"
Debug Mid(ST1,2,4)           ' "UBLO" is printed.
</code>

{{ :cubloc:type_conversion:left_mid_right.png?nolink |}}

===== Len(stringValue) =====
Return the length of the given String.

<code xbasic>
Dim ST1 As String * 12
ST1 = "CUBLOC"
Debug Dec Len(ST1)         ' 6 is printed since there are 6 characters in ST1.
</code>

===== String(asciiCode, length) =====
Creates a String of a specified length with the given ASCII code repeated
for the length of the String.

<code xbasic>
Dim ST1 As String * 12
ST1 = String(&H41,5)
Debug ST1              ' AAAAA is printed.
                       ' &H41 is ASCII code for character A.
</code>

===== SPC(numberOfSpaces) =====
Create a specified amount of blank space

<code xbasic>
Dim ST1 As String * 12
ST1 = SPC(5)
Debug "A",ST1,"A"      ' A A is printed.
                       ' Note the 5 blank spaced between each A.
</code>

{{ :cubloc:type_conversion:spc_function.png?nolink |}}                     

===== LTrim(stringValue) =====
Removes all blank spaces from the left side of the given String.

<code xbasic>
Dim ST1 As String * 12
ST1 = " COMFILE"
ST1 = LTrim(ST1)
Debug "AAA",ST1      ' AAACOMFILE is printed.
</code>

===== RTrim(stringValue) =====

Removes all blank spaces from the right side of the given String.

<code xbasic>
Dim ST1 As String * 12
ST1 = "COMFILE "
ST1 = RTrim(ST1)
Debug ST1,"TECH"     ' COMFILETECH is printed.
                     ' Blank spaces on the right are removed.
</code>

{{ :cubloc:string_functions:trim_function.png?nolink |}}

===== Val(stringValue) =====
Parses a given String into its equivalent decimal value.

<code xbasic>
Dim ST1 As String * 12
Dim i As Integer
ST1 = "123"
i = Val(ST1)         ' 123 is stored in variable I as a number.
</code>

===== ValSng(stringValue) =====
Parses a given String into its equivalent floating point value.

<code xbasic>
Dim ST1 As String * 12
Dim F As Single
ST1 = "3.14"
F = ValSng(ST1)      ' 3.14 is stored in variable F as a floating point number.
</code>

{{ :cubloc:string_functions:vansng.png?nolink |}}

===== ValHex(String variable) =====

Parses a given String in hexadecimal format into its numeric equivalent.

<code xbasic>
Dim ST1 AS String * 12
Dim i AS Long
ST1 = "ABCD123"
i = ValHex(ST1) '&HABCD123 is stored in variable I
</code>

===== Chr(asciiCode) =====

Return the character represented by the given ASCII code.

<code xbasic>
Dim ST1 AS String * 12
ST1 = Chr(&H41)
Debug ST1              ' Print A. &H41 is the ASCII code for character A.
</code>

===== ASC(stringValue) =====

Return ASCII code of the first character in the given String.

<code xbasic>
Dim ST1 AS String * 12
Dim i AS Integer
ST1 = "123"
i = Asc(ST1)          ' &H31 is stored in variable I. ASCII code of 1 is &H31 or 0x31.
</code>

Caution:
A variable must be used when using string functions.

<code xbasic>
Debug Left("INTEGER",4)     ' A String constant cannot be used.
ST1 = "INTEGER"
Debug Left(ST1,4)           ' The String must be stored as a variable first.
</code>

{{ :cubloc:string_functions:ascii_function.png?nolink |}}


[[cubloc:index:|Go CUBLOC home]]