Escaping characters
When you manage your AGS Strings, you might want to pay special attention to these characters:
- " (double quote)
- \ (backslash)
- [ (opening square bracket, also known as left brace)
- % (percent symbol)
For easy solutions, simply read String_formatting#Displaying_special_characters. For thourough explanations, read below.
| How to read this walkthrough
There are 3 stages in managing your strings :
|
1) In the AGS script editor :
(all the statements below tested in AGS 3.2.1)
Let's say you want to declare a string containing a backslash (\) and or a double quote ("), in the following fashion :
| String s = "this is a string, and soon it will contain a backslash or a double quote"; |
In the script editor, the backslash acts as an escape character, which means it has no value in itself, but depends on what comes immediately behind.
| Situation | What you type into the script editor | What you get in memory | Explanations |
|---|---|---|---|
| One backslash followed by a double quote: \" | String s = "aaa\"bbb"; | 97 97 97 34 98 98 98 | As you can see the backslash acts as an escape character and gets swallowed up so that the double quote doesn't get confused with the ending double quote.
By the way, this is not correct syntaxically, as there is no ending double quote: String s = "aaa\"; |
| One backslash followed by another backslash: \\ | String s = "aaa\\bbb"; | 97 97 97 92 98 98 98 | As you can see the backslash acts as an escape character and gets swallowed up so that the second backslash actually makes it to the String in memory. |
| One backslash followed by an opening brace: \[ | String s = "aaa\[bbb"; | 97 97 97 92 91 98 98 98 | As you can see the backslash acts as an escape character but DOES NOT get swallowed up. Both backslash and opening brace make it to memory.
This becomes useful at rendering time, to display a [ in a Label or a Display. |
| One backslash followed by anything else: \a, \b, etc. | String s = "aaa\bbb"; | 97 97 97 98 98 98 | The backslash gets deleted.
It does not act as an escape character (the "a" immediately after it still makes it to memory) BUT still gets swallowed up, and doesn't appear in the in-memory string. |
| Any number of backslashes followed by something else | String s = "aaa\\\[\bbb"; | 97 97 97 92 92 91 98 98 98 | All the above applies. Count your number of backslashes carefully!
The first two backslashes become just "\", "\[" stays "\[", "\b" becomes just "b". Tricky, isn't it? |
| Any number of percent symbols | String s = "aaa%bbb"; or String s="aaa%%bbb"; | 97 97 97 37 98 98 98 or 97 97 97 37 37 98 98 98 | The string will be stored in memory exactly as you typed it in. Trouble may arise only if you decide to use that particular String as the first parameter of the String.Format or Display function (read further). |
Pro-tip : To avoid human mistakes, manipulate escape characters separately, using only their keyCode.
Example :
| What you type in the script editor | What you get in memory at run-time |
|---|---|
| String s=String.Format("%s%c%c%s", "aaa", eKeyBackSlash, eKeyOpenBracket, "bbb"); | 97 97 97 92 91 98 98 98 (aaa\[bbb) |
2) In the GUI Editor
- What you type in the "Text" property of the Label control is exactly what will be in memory. No escape characters apply.
- What will appear in the Label preview (in the GUI Editor, on the left) is rendered following the rules described in this page for Labels (read further).
| What you type in the Text property | What appears in the Label preview | Explanation |
|---|---|---|
| aaa[bbb | aaa bbb |
See Label rendering rules. |
| aaa\[bbb | aaa[bbb | See Label rendering rules. |
| aaa\\\\[bbb | aaa[bbb | See Label rendering rules. BEFORE AGS 3.4patch3: All the backslashes get swallowed up at once! FROM AGS3.4 patch3 : Same behaviour as everywhere else. Every backslash counts. |
| aaa\bbb | aaa\bbb | (identical) See Label rendering rules. |
| aaa\\\\bbb | aaa\\\\bbb | (identical) See Label rendering rules. |
| aaa%bbb | aaa%bbb | The percent symbol is rendered identically when displayed in a Label.Text. Remember, though, that it has a special effect only when used as the first parameter of the String.Format or Display function (read the next section). |
IMPORTANT NOTE: There was a bug in some versions of AGS older than 3.2 : typing aaa\[bbb in the Text property of a Label would render it as follows in the Label:
| aaa\ bbb |
2) At runtime, in a Label or a Display()
| The string as stored in memory | How it will be rendered in a Label or Display | Explanation |
|---|---|---|
| aaa[bbb | aaa bbb |
The opening brace is a special character that creates a new line. |
| aaa\[bbb | aaa[bbb | The brace's special behaviour is disabled if it's preceded by one or more backslashes. The backslashes are not rendered. |
| aaa\\\\[bbb | aaa[bbb | BEFORE AGS 3.4 patch 3: Please note that all the backslashes before a '[' don't get rendered. Not only do they not get rendered, but they get deleted from the String (in-memory) if you make use of any of the following functions: Append, AppendChar, Replace, etc. Also when you do a string -> String conversion (Reminder: string is the old-style AGS string, while String is the new-style AGS string since 3.x). It doesn't seem to happen when you use String.Chars[i] STARTING FROM AGS 3.4 patch 3 : Every backslash counts. \[ gives [, \\ gives \, etc. |
| aaa\bbb | aaa\bbb | The string gets rendered exactly as in memory, as the backslashes are not followed by [. |
| aaa\\\\bbb | aaa\\\\bbb | The string gets rendered exactly as in memory, as the backslashes are not followed by [. |
| aaa%ddd | In Label.Text: aaa%ddd In Display: aaa%?dd (where ? could be any character) |
% is a special character meant for formatting Strings, as in String s = String.Format("The value of i is %d", i);. In Labels, it will have no effect. However the Display function works the same way as String.Format, so you must avoid having a single percent symbol. Use double percents instead. |
| aaa%%ddd | In Label.Text: aaa%%ddd In Display: aaa%ddd |
% is a special character meant for formatting Strings, as in String s = String.Format("The value of i is %d", i);. In Labels, it will have no effect. However the Display function works the same way as String.Format, so if you want to display one percent symbol, you must have two in your string. |
3) At runtime, in a Listbox
The string is rendered exactly as it is stored in memory. the Listbox doesn't handle line breaks, so a [ or a \[ in memory will appear as-is in the Listbox.
But remember this :
- If your string contains one percent symbol, it can cause issues if at some stage before rendering it's used in a String.Format function (see previous section for recommendations about the double-percents)
- If your string contains several \ followed by one [, then all the \ will be deleted from memory if your string gets manipulated by any String-manipulation function (Append, AppendChar, etc.). See previous section to know more.