Using Strings

Strings are probably the most used variable types in programs. A string in Emergence BASIC is an array of characters terminated by a single NULL character (0).  Strings can be defined as variables with the DEF statement, defined as literals by enclosing text in quotes, or returned from functions.

The STRING variable type is dimensioned automatically to 255 bytes which is enough room for 254 characters and the terminating NULL. The ISTRING variable type is unique to the Emergence BASIC language and can be dimensioned to create a string from 1 to the amount of available memory.
 

DEF mystring as STRING
DEF bigstring[25000] as ISTRING

Strings can be loaded, or initialized by assigning with the = operator.

mystring = "This is a string"
bigstring = STRING$("A",24999)

The WSTRING variable type is dimensioned automatically to 255 Unicode characters which is enough room for 254 characters and the terminating double NULL.  The IWSTRING variable type can create a Unicode string of any size, up to the amounf of available memory.
 

DEF mystring as WSTRING
DEF bigstring[25000] as IWSTRING

Unicode strings can also be loaded, or initialized by assigning with the = operator.
 

mystring = L"This is a string"
bigstring = WSTRING$(L"A",24999)

NOTE: The compiler can not check for overwriting the ends of dimensioned strings so make sure you check your lengths with the LEN function, or otherwise limit the amount of text assigned to a string.

Common string functions

Included with the standard command set are a number of string functions for creating, manipulating and working with strings.

APPEND$ function

Concatenates all the strings in the argument list and returns the total string. This is similar to using the ‘+’ operator on strings.

Result$ = APPEND$ (string1, string2 {,stringn …} )

See also: Operators , concatenation with the + operator

ASC function

The ASC function returns the ASCII value of the character argument. A string may be specified as the argument which case the first character of the string is used.

Value = ASC("A")

CHR$/WCHR$ function

Returns the character represented by the ASCII parameter. This is the opposite of the ASC function. This function is useful for creating characters that can not be normally typed on a keyboard.  The syntax of the CHR$ function is:

Character = CHR$(value)

Example print a <RETURN> to the console:
 

PRINT CHR$(13)

The WCHR$ function accepts a word value and returns a character as a Unicode string.

DATE$ function

Returns the current date as a string in the format DD-MM-YYYY. The syntax of the DATE$ function is:
 

Result$ = DATE$

DATE$(format) function

Returns the current date as a string formatted by a specifier string. The specifier string is comprised of:

For example, to get the date string

"Wed, Aug 31 94"

use the following input string:

"ddd',' MMM dd yy"

Example:
 

PRINT DATE$("ddd',' MMM dd yy")

Note the single quotes used to insert text into the output string.

HEX$/WHEX$ function

Converts the numeric parameter to a string representing the hexadecimal notation of that number. The syntax of HEX$ is:

Result$ = HEX$(value )
 

PRINT HEX$(255)

Would print FF to the console window.  HEX$ uses a UINT64 parameter and can display hex numbers up to 64 bits in length. The WHEX$ function is the Unicode version.

INSTR/WINSTR function

The INSTR function is used to search for text in a string.

Position = INSTR( string1, string2 {,start} )

Returns the position of the sub string string2 in string1. Or returns 0 if string2 is not in string1. Optional start variable specifies a starting point in string1 to begin searching. position and start are ones based. The WINSTR function works with Unicode strings.

INSTR performs a case sensitive search. To perform a case insensitive search use either LCASE$ or UCASE$ on the with the parameters.
 

IF INSTR(UCASE$(mystr), "FOX") > 0
    PRINT "Fox was found in mystr"
ENDIF

LCASE$/WLCASE$ function

Returns the string parameter converted to all lowercase letters.
 

lwr$ = LCASE$("CONVERT THIS TO LOWER CASE")
PRINT lwr$

LEFT$/WLEFT$ function

Extracts count number of characters from the string starting from the leftmost character. Returns the resulting string. The syntax of LEFT$ is:
 

str = "The red fox"
Result$ = LEFT$ (str, 3)
PRINT Result$

LEN function

The LEN function works with any variable type in EBASIC. For strings it returns the number of characters in the string not including the NULL terminator.
 

MyString = "What's my length?"
PRINT LEN(mystring)

LTRIM$/WLTRIM$ function

Removes all leading white-space characters from a string. White-space characters include spaces and tabs. LTRIM$ returns the result as a string leaving the parameter unchanged. The syntax of LTRIM$ is:

Result$ = LTRIM$( string )

MID$/WMID$ function

Extracts count number of characters staring at position from a string. If count is omitted all of the characters from position to the end of the string are returned.

Result$ = MID$ (str, position {,count})

If count is omitted all of the characters from position to the end of the string are returned. position is ones based.
 

MyString = "Extract some characters from me"
PRINT MID$(MyString, 8, 4) 

RIGHT$/WRIGHT$ function

Extracts characters from the end of a string. The syntax of the RIGHT$ function is:

Result$ = RIGHT$ (string, count )

Count is the number of characters to extract from the end of the string.
 

MyString = "Extract some characters from me"
PRINT RIGHT$(MyString,2)

RTRIM$/WRTRIM$ function

Removes any trailing white-space characters from a string. White-space characters include spaces and tabs. RTRIM$ returns the result as a string leaving the parameter unchanged. The syntax of RTRIM$ is:

Result$ = RTRIM$ (string)

SPACE$/WSPACE$ function

Returns a string filled with n spaces. The syntax of the SPACE$ function is:

Result$ = SPACE$( n )

STR$/WSTR$ function

The STR$ function returns the string representation of a number. The syntax of STR$ is:

Result$ = STR$( number )

number is a double precision number and the conversion will contain as many decimal places as specified by the SETPRECISION command.
 

num$ =  STR$(1.23456)
PRINT num$

STRING$/WSTRING$ function

The STRING$ function returns a string filled with count number of the character specified. The syntax of the STRING$ function is:

Result$ = STRING$ (count, character )

TIME$ function

Returns the current system time in the format HH:MM:SS as a string. The syntax of TIME$ is:

Result$ = TIME$

UCASE$/WUCASE$ function

Returns the string parameter converted to all uppercase letters. The syntax of the UCASE$ function is:

Result$ = UCASE$( string)

VAL/WVAL function

Returns the value of a string representation of a number. This function is the opposite of the STR$ function. The syntax of the VAL function is:

Result = VAL( string)

The return type is a double precision number.
 

DEF d as DOUBLE
d = VAL("1.234567")

VAL will stop converting digits on the first non numeric character. Use LTRIM$ on your variable to remove any leading whitespace before conversion.

REPLACE$ statement

The REPLACE$ statement replaces characters in one string with one or more characters from another. The syntax of the REPLACE$ statement is:

REPLACE$ dest, start, count, source

Dest is the string being modifies and source is the string where the characters are extracted from. Start and count must be greater than 0.

Example:
 

DEF s:string
s = "All good DOGs go to heaven"
REPLACE$ s,10,3,"dog"
PRINT s

Would print "All good dogs go to heaven"

Converting between Unicode and ANSI

Converting between a wide character (Unicode) and ANSI strings is accomplished by using the W2S and S2W functions. W2S accepts a Unicode string as input and returns an ANSI string as output.  S2W accepts an ANSI string as input and returns a Unicode string as output.
 

DEF s:STRING
DEF w:WSTRING
s = W2S(L"This is a Unicode string")
PRINT s
w = WLEFT$(L"All good pets deserve love",8)
PRINT W2S(w)