Strings
Defining strings
A string is generated with the keyword string. It can be any sequence of valid characters. In addition, you can have strings with only one and even without any characters:
string emptyString = "";
string oneCharacter = "a";
string manyCharacters = "abcdefg";
There is no separate data type in TDM Studio that can store only one single character, as in the case in languages such as C or C#. A single character is therefore simply a string that contains only one character.
Operations with strings
There is only one operation that can be applied to strings: the addition. However, this is not an arithmetic addition but a concatenation:
string s = "abcd" + "efg";
The variable s now contains the string abcdefg.
Working with strings
To access or to change a specific character in a string, you can enter an index in square brackets. This index is zero-based, i.e. the first character in the string has the index 0, the second the index 1, etc.
string s = "abcde";
s[0] = "F";
s[2] = "X";
The variable s now has the content FbXde.
With this method, you can only ever access (i.e. set or read out) single characters.
The length of a string is determined using the function Length(), which means that you can access the last character as follows:
string lastCharacter = s[Length(s) - 1];
You can also insert one or more characters into a string. The following example inserts the characters XYZ at index 3 into the string abcde:
string s = Insert("abcde", 3, "XYZ");
The variable s now has the content abcXYZde.
Characters can also be removed from a string:
string s = Remove("abcde", 1, 3);
This statement removes 3 characters from index 1. The result is ae.
The chapter "Functions (alphabetical)" describes all predefined functions for strings in TDM Studio.
Two functions which are often used should briefly be mentioned here: Upper() and Lower(). These convert letters into upper or lower case. If a string contains special characters for a foreign language, you can also specify a culture:
string upper1 = Upper("Abc");
string upper2 = Upper("ÄäÖöÜü", CreateCulture("de-DE"));
upper1 will now contain ABC and upper2 will contain ÄÄÖÖÜÜ.
If no culture is specified, the current setting of the operating system is used.
Control characters in literals
If you want to enter control characters in a string, they have to be preceded by a so-called "escape character", in this case the backslash.
Following the backslash will be a letter or a digit, depending on which control function you want to use. A complete list of control characters is given in the table "Control characters for strings". We will mention three of them here, as an example of how control characters can be used:
Trace(TRACELEVEL_INFO,
"A multi-line\n\tindented string\n\twith the character \\");
A tab character is inserted with the sequence \t.
\n inserts a line break into the string, and to insert the backslash itself (i.e. not as a control character) you have to double the character. The result of the statement above is:
A multi-line
indented string
with the character \
If you look at the output in the output window, you will see that it looks as follows:
A multi-line| indented string| with the character \
The reason for this is that the output window (like the error window) removes any line breaks from the output and inserts a vertical line instead. In contrast, the log file will actually show the line breaks as such.
Please also note that the line break control character is not automatically translated into a carriage return under DOS and Windows. Depending on the editor that you use, it could be that the new lines will start at the beginning of the line, as expected. However, it is also possible that the new lines are not re-set to the start of the line.
As a rule, text with line breaks under DOS and Windows should therefore also use explicit carriage returns. Carriage returns are inserted with the sequence \r. This means that in order to ensure correct line breaks under DOS and Windows, you should use the sequence \r\n instead of simply \n.
Text blocks
Text blocks are a special form of string. They are not enclosed in hash marks instead of quote marks:
string s = #A text block#;
The most noticeable difference is that control characters do not have to be masked in text blocks, but that they can instead be entered directly via the keyboard:
Trace(TRACELEVEL_INFO, #A text block
that contains line feeds
and indents#);
Every line break and indent is entered as part of the text. The result is:
A text block
that contains line breaks
and indents
However, the most significant aspect of text blocks is the way that they are processed in TDM Studio. This is because a text block can contain expressions which are evaluated during processing. Expressions like this are preceded by the @ sign (output is in blue):
Trace(TRACELEVEL_INFO, #The result of "1 + 2" is @1 + 2@#);
Expressions like this may contain variables and functions or they can consist of a single variable or function:
string text = #The sine of 30° is: @Sin(30)@#;
If you use functions, then these must return a result. Thus, the use of Trace() in a text block would lead to unexpected results, because Trace() does not return anything that could be inserted into the text block.
Numbers and times can (but do not have to) be converted into strings with the function Str(). This is only necessary if special formatting is required. In the following example, the first two lines return the same result, while the third line uses a different format:
Trace(TRACELEVEL_INFO, #The amount is: @1369.99@#);
Trace(TRACELEVEL_INFO, #The amount is: @Str(1369.99)@#);
Trace(TRACELEVEL_INFO, #The amount is: @Str(1369.99, "C")@#);
On a system with US-English country settings, the result will be:
The amount is: 1369,99
The amount is: 1369.99
The amount is: $ 1.369,99
Because the characters # and @ signify the beginning and the end of text blocks and statements, they must be duplicated if they are to be interpreted as “normal” characters in a text block (but not in a statement between two @ characters):
Trace(TRACELEVEL_INFO, #This text contains both a ## and an @@ character.#);
The result is:
This text contains both a # and an @ character.