Strings And String Operations

MADRIX Script provides several functions to manipulate strings, find substrings, and to perform many more operations.

Compatibility

Strings in MADRIX 5 support the UTF-8 encoding standard. That mainly means that a variety of characters of different languages as well as special characters can be used.

Several special characters can be masked to make sure that they are included in the text. Otherwise, the script language will interpret them as parts of the language with much different functionality and not part of the text.

Operations On Strings

Assigning Data Types

It is possible to assign integer, float, and string values to another string as shown in the following example:

Furthermore, it is possible to assign a single character of a string to a character of another string like shown below:

Furthermore, it is possible to assign a double-quoted string to a character of a string. But the assigned string must have exactly one character. Here is an example:

The following lines are invalid and will result in a compiler error since the given strings contain more or less than one character:

s[0] = "New"; //given string has three characters but not one
s[0] = ""; //given string is empty

Comparing Two Strings

As it is possible to compare two numbers using the comparison operators, it is also possible to compare two strings. The following table provides an overview of the possible operations.

Operator	Description
str1 == str2	Checks if the strings are equal.
str1 != str2	Checks if the strings are not equal.
str1 < str2	Checks if the first string is less than the second string.
str1 <= str2	Checks if the first string is less or equal to the second string.
str1 > str2	Checks if the first string is greater than the second string.
str1 >= str2	Checks if the first string is greater or equal to the second string.

Please note: The sorting order of the strings is case-sensitive and depends on the contained ASCII characters. Therefore, all upper case characters are "less" than the set of lower case characters, e.g. the string array { "and", "Alice", "Bob", "and me" } results in the ascendingly sorted string array { "Alice", "Bob", "and", "and me" }.

Like in the case of assignments, it is also possible to compare a single character of a string with a double-quoted string with exactly one character:

It is also possible to compare a single character of a string with an integer number:

This also works for the switch/case statements. But the "1" as a label of a case means the same as the 1. So the following two case labels mean the same and this would result in a compiler error:

string s = "1";
switch(s[0])
{
case "1": do something; break;
case 1: do something else; break;
case "A": do something; break;
//it is also valid to check for letters and other characters
...
}

Using Strings Within Switch/Case Statements

Another possibility is to use double-quoted strings of one character for the labels of cases. The following theoretical example demonstrates this:

string s = "New";
for(int i = 0; i < s.length; ++i)
{
switch(s[i])
{
case "A": do something; break;
case "B": do something else; break;
case "!": do something; break;
}
}

Functions For Strings

Function	Description
int findstring(int startIndex, string text, string substring)	Searches for the substring within text starting at startIndex. The function returns an index that describes the position at which the substring begins. »Description Example: findstring(0, "Hello World!", "World") returns 6. If the substring is not found within text, -1 is returned.
string substring(string text, int start, int count)	The function extracts count characters from the given text starting with start. If count is -1, all characters of the string starting at start are returned. »Description E.g.: substring("Hello", 0, 2) returns "He".
int rfindstring(int startIndex, string text, string substring)	This functions looks for the substring in the given text from its end to the beginning. The function starts its search at a specified position of the entire text using startIndex and returns an index that describes the position at which the substring begins. If the substring was not found, -1 is returned.
int startswith(string text, string substring)	This function checks if the string text starts with the given substring. If text starts with substring, 1 (TRUE) is returned, otherwise 0 (FALSE).
int endswith(string text, string substring)	This function checks if the string text ends with the given substring. If text ends with substring, 1 (TRUE) is returned, otherwise 0 (FALSE).
int isalnum(string text)	Returns 1 (TRUE) if the given string contains only characters and figures and if its length is greater then 0. Otherwise, 0 (FALSE) is returned.
int isalpha(string text)	Returns 1 (TRUE) if the given string contains only characters and if its length is greater than 0, otherwise 0 (FALSE) is returned.
int isnum(string text)	Returns 1 (TRUE) if the given text represents a number. This may be an integer number or a floating point number (e.g. 1.3). Otherwise, it returns 0 (FALSE).
void tolower(string text)	Converts each character of the given string into a lower-case character.
void toupper(string text)	Converts each character of the given string into an upper-case character.
string hex(int value)	Formats the given value as a hexadecimal number. Letters are lower-cased (a-f).
string Hex(int value)	Formats the given value as a hexadecimal number. Letters are upper-cased (A-F).
void strip(string text)	Removes leading and ending white spaces, like space, tabulator, line feeds, etc. from the given string.
int strcmp(string str1, string str2)	Compares two given strings with each other. If they are equal, 0 is returned. -1 is returned if str1 is less than str2. A value of 1 is returned if str1 is bigger than str2.
void replace(string src, string old, string new)	Replaces any appearances of old within src with new.
void tokenize(string src, string delimiter, string reslist[])	Strips the src string into smaller pieces delimited by characters within delemiter. The result is returned in reslist. »Description

Tokenizing Strings

The function tokenize enables you to split a string into smaller parts separated by specified delimiters. The single tokens will be delimited by the characters within the second parameter. Each character identifies a single delimiter. The following examples show the usage of the function and the results.

string s = "Have a wonderful,nice day";
string res[];
tokenize(s, " ,", res);

string s = "one two,three";
string res[];
tokenize(s, "," , res);

▪The variable res of the first example will be filled with the following five values: {Have; a; wonderful; nice; day}

▪The res variable of the second example will be filled with the following two values: {one two; three}

▪The result of the second example will contain only two entries. "one two" is only one entry since the tokens of the second example are only delimited by comma but not by space.

Splitting Strings With White Spaces

There is a constant called WHITE_SPACES which can be used as delimiter in order to split a text by any white spaces like tabulator, new line, or space.

string s = "Have a wonderful, nice day";
string res[];
tokenize(s, WHITE_SPACES, res);

//or another example which also uses the comma as delimiter
tokenize(s, WHITE_SPACES + ",", res);

Examples

Substring

This example extracts a part from a string. Insert the source code into the function RenderEffect. As the result "World" should be displayed in the output window of the Script Editor.

string txt = "Hello World!";
string subText = substring(txt, 6, 5); //retrieves "World" from txt
WriteText(subText);