"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.
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.
find(str) – finds the substring str within this string. If the substring is contained within this string, the method returns the character index where the substring starts; the first character is at index 1. If the substring isn't contained within this string, the method returns nil.
Examples:
'abcdef'.substr('cd') yields 3
'abcdef'.substr('g') yields nil
length() – returns the number of characters in the string.
substr(start, length?) – returns a new string consisting of a substring of this string. The substring starts at character index start (the first character in the string is at index 1). If length is specified, the result string is at most length characters long; if length is not specified, the result runs to the end of the source string.
Examples:
'abcdef'.substr(3) yields 'cdef'
'abcdef'.substr(3, 2) yields 'cd'
toLower() – returns a new string consisting of the characters of the original string converted to lower-case. Only alphabetic characters are affected; other characters are copied to the new string unchanged. The conversion uses the case conversions specified in the Unicode character database, so accented and non-Roman alphabetic characters are properly converted.
toUnicode(idx?) – converts one or all of the characters of this string to Unicode character codes. If idx is given, it specifies the character index within the string of the single character to convert (the first character is at index 1), and the method returns an integer containing the Unicode code point for the character at that index. If idx is not specified, the function returns a list; each element in the list is an integer giving the Unicode code point value for the corresponding character in the source string. The list will have one element per character in the source string.
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() – returns a new string consisting of the characters of the original string converted to upper-case. Only alphabetic characters are affected; other characters are copied to the new string unchanged. The conversion uses the case conversions specified in the Unicode character database, so accented and non-Roman alphabetic characters are properly converted.