String
"String" is a native TADS 3 datatype, but it is also an intrinsic class. The String class provides a number of useful methods for manipulating string values.
Value semantics
Strings have "value semantics," which means that a given string object's text is constant; once you've created a string, the text within that string never changes. All of the methods and operators that appear to change the value of a string actually create a new string with the modified value, leaving the original value intact. For example, consider this code:
local x = 'foo'; local y = x; x += 'bar';
Superficially, it appears that the last line changes the string in x. In fact, the original string is not changed - if we displayed the value of y, we'd see that it still contains 'foo'. When the interpreter executes the last line above, it creates a new string to hold the concatenated value, then assigns the result to x.
Value semantics make it very easy to work with strings, because you don't have to worry about whether a function might modify a string you pass to it: this can never happen, because a given string's text is constant.
String methods
endsWith(str)
find(str, index?)
If index is given, it gives the starting index in self for the search; a value of 1 indicates that the search starts at the first character. If the index value is omitted, the default value is 1. The starting index value can be used to search for another occurrence of the same substring following a previous search, for example.
Examples:
'abcdef'.find('cd') yields 3 'abcdef'.find('g') yields nil 'abcdef'.find('c', 3) yields 3 'abcdef'.find('c', 4) yields nil 'abcabcabc'.find('c', 4) yields 6 'abcabcabc'.find('c', 7) yields 9
findReplace(origStr, newStr, flags, index?)
If index is specified, it gives the starting index in self for the search. If index is 1, the search starts at the first character; this is the default if index is not given. No instances of origStr before index will be replaced.
htmlify(flags?)
- HtmlifyTranslateSpaces: converts each space after the first space in a run of multiple spaces to the sequence (the HTML non-breaking space). This ensures that, when the string is rendered in HTML mode, the display shows the same number of spaces that appeared in the original string. Note that the method never converts the first space in a run of whitespace to the sequence, because the first space in a run of whitespace is significant in HTML and thus requires no special handling.
- HtmlifyTranslateTabs: converts each tab character (\t) in the string to the sequence <tab>.
- HtmlifyTranslateNewlines: converts each newline character (\n) in the string to the sequence <br>.
- HtmlifyTranslateWhitespace: this is simply a combination of HtmlifyTranslateSpaces, HtmlifyTranslateTabs, and HtmlifyTranslateNewlines.
This method is useful if you obtain a string from an external source, such as from the user (via the inputLine() function, for example) or from a text file, and you then want to display the string in HTML mode. Without conversions, any markup-significant characters in the string might not be displayed properly, since the HTML parser would attempt to interpret the characters as HTML formatting codes. You can use this method to ensure that a string obtained externally is displayed verbatim in HTML mode.
length()
mapToByteArray(charset)
substr(start, length?)
If the start parameter is negative, it indicates an offset from the end of the string: -1 indicates that the substring is to start at the last character, -2 at the second-to-last, and so on.
Examples:
'abcdef'.substr(3) yields 'cdef' 'abcdef'.substr(3, 2) yields 'cd' 'abcdefghi'.substr(-3) yields 'ghi' 'abcdefghi'.substr(-3, 2) yields 'gh'
toLower()
startsWith(str)
toUnicode(idx?)
This function can be used to decompose a string into its individual characters, which is sometimes an easier or more efficient method of manipulating the string. You can convert a list of Unicode code point values back into a string using the makeString() function in the tads-gen function set.
toUpper()