tads-gen Function Set
The tads-gen function set provides general utility and data manipulation functions. These functions have no user interface component.
To use the tads-gen function set in a program, you should #include either <tadsgen.h> or <tads.h> (the latter includes both <tadsio.h> and <tadsgen.h>, for the full set of TADS intrinsics). If you're using the adv3 library, you can simply #include <adv3.h>, since that automatically incluedes the basic system headers.
tads-gen functions
dataType(val)
firstObj(cls?, flags?)
If the flags argument is specified, it can a combination (with the | operator) of the following bit flags:
- ObjInstances - the function returns only instances, not "class" objects. This is the default.
- ObjClasses - the function returns only objects originally defined as "class" objects.
- ObjAll - this is defined for convenience as (ObjInstances | ObjClasses).
If the flags argument is omitted, only instances are enumerated, as though ObjInstances had been specified.
getArg(idx)
getFuncParams(funcptr)
- returnValue[1] is the minimum number of arguments taken by the function;
- returnValue[2] is the number of additional optional arguments taken by the function;
- returnValue[3] is true if the function accepts any number of additional arguments (i.e., it's a "varargs" function), nil if not.
The second element gives the number of optional arguments; this element is always zero, because there's no way for an ordinary function (non-intrinsic) to specify optional arguments. This element is included in the list specifically so that the list uses the same format as the Object.getPropParams() method.
If the third element is true, it indicates that the function was defined with the ... varying argument list notation.
getMethodDefiner()
getTime(timeType?)
- GetTimeDateAndTime - returns the current system date and time
as a list with the following elements:
[year, month, monthDay, weekDay, yearDay, hour, minute, second, timer].
- year is the AD year number (the full four-digit number)
- month is the month number (January = 1, February = 2, etc.)
- monthDay is the day of the month (on March 13, this returns 13)
- weekDay is the day of the week (Sunday = 1, Monday = 2, etc.)
- yearDay is the day of the year (January 1 = 1, January 2 = 2, etc.)
- hour is the hour of the day on a 24-hour clock (2:00 PM returns 14)
- minute is the minute of the hour (2:35 PM returns 35)
- second is the second of the minute (2:35:12 PM returns 12)
- timer is the number of seconds since January 1, 1970.
- GetTimeTicks - returns the number of milliseconds since some arbitrary zero point. The precision of the timer varies by system, so the fact that the return value is represented with millisecond precision doesn't necessarily mean that the system is actually capable of measuring time differences that precisely. The zero point is chosen as the time of the first call during a VM session, which reduces the likelihood that the program will ever encounter a timer rollover (i.e., the point at which the timer exceeds the 31-bit precision of the integer return value and thus resets back to zero), which occurs after about 23 days of continuous execution.
makeString(val, repeatCount?)
- If val is a string, the return value is the given number of copies of the string appended one after the other. For example, makeString('abc', 3) yields 'abcabcabc'.
- If val is a list, the list must contain integers. Each integer in the list gives a Unicode character value. The function constructs a string with the same number of characters as the list has elements, and with each character of the string having the Unicode code point of the corresponding integer in the list. This string is then repeated the given number of times. For example, makeString([65,66,67]) yields 'ABC'.
- If val is an integer, the function returns a string consisting of the single Unicode character whose code point is given by the integer, repeated the specified number of times. For example, makeString(65, 5) yields 'AAAAA'.
- Other types are invalid.
If repeatCount is not specified, the default is 1.
max(val1, ...)
min(val1, ...)
nextObj(obj, cls?, flags?)
rand(x, ...)
- With a single integer argument, rand() generates a random integer from 0 to one less than the given value, inclusive, and returns the integer value; for example, rand(10) returns a value from 0 to 9.
- With a single list argument, rand() randomly selects one of the list elements and returns it.
- With two or more arguments, rand() randomly selects one of the argument values and returns it; note, however, that all of the arguments are evaluated (and hence any side effects of those evaluations will occur).
In all cases, rand() chooses numbers based on a "uniform distribution" over the range, which means that each value in the desired range has equal probability.
randomize()
restartGame()
If an error occurs, the function throws a run-time error. The errno_ property of the RuntimeError exception object gives a VM error code describing the problem; the possible errors are:
- 1201 - the file does not contain a saved state (it has some other type of data)
- 1202 - the state was saved by a different program, or by a different version of the same program
- 1207 - the file is corrupted
rexGroup(groupNum)
Returns nil if there is no such group, or if there's no match for the group. If there's a match for the group, returns a three-element list: the character index of the group match within the original source string; the length in characters of the group match; and the matching string.
If the leading substring of str matches the regular expression, the function returns the number of characters of the matching substring; if there is no match, the function returns nil. This does not search for a match, but merely determines if str matches the expression in its leading substring. Note that a regular expression can successfully match zero characters, so a return value of zero is distinct from a return value of nil: zero indicates a successful match that's zero characters long, and nil indicates no match.
If index is given, it indicates the starting index for the match; index 1 indicates the first character in the string, and is the default if index is omitted. This can be used to match a substring of str to the pattern without actually creating a separate substring value.
Refer to the regular expressions section for details on how to construct a pattern string.
rexReplace(pat, str, replacement, flags, index?)
The return value is the resulting string with the substitutions applied.
The pattern pat can be given as a string using regular expression syntax, or as a RexPattern object.
The flags value specifies whether to replace multiple occurrences or not: ReplaceOnce specifies that only the first match is to be replaced, and ReplaceAll specifies that all matches are to be replaced.
If index is given, replacements start with the first instance of the pattern at or after the character index position. The first character is at index 1. If index is omitted, the search starts at the first character.
The replacement string is substituted for the original matching text of each match (or of the first match if ReplaceOnce is specified). The original substring that matches the regular expression pat is removed from the string, and replacement is inserted in its palce. The replacement text can include the special sequences %1 through %9 to indicate that the text that matches the corresponding parenthesized group in the regular expression should be substituted at that point. %1 is replaced by the original matching text of the first parenthesized group expression, %2 by the second group's matching text, and so on. In addition, %* is replaced by the match for the entire regular expression. Because of the special meaning of the percent sign, you have to use the special code %% if you want to include a literal percent sign in the replacement text.
Refer to the regular expressions section for details on how to construct a pattern string.
rexSearch(pat, str, index?)
If index is given, it gives the starting character position in str for the search. The first character is at index 1. If index is omitted, the search starts with the first character. The index value can be used to search for repeated instances of the pattern, by telling the function to ignore matches before the given point in the string.
If the function finds a match, it returns a list with three elements: the character index within str of the first character of the matching substring (the first character in the string is at index 1); the length in characters of the matching substring; and a string giving the matching substring. If there is no match, the function returns nil.
Refer to the regular expressions section for details on how to construct a pattern string.
saveGame(filename)
savepoint()
toInteger(val, radix?)
- If val is an integer, the return value is simply val. radix is ignored in this case.
- If val is a BigNumber, the value is converted to an integer by rounding to the nearest whole number. If the number is too large for the integer type to hold (that is, outside the valid integer range, -2147483648 to +2147483647), a run-time error occurs ("numeric overflow").
- If val is the 'nil' or the string 'true', the return value is nil or true, respectively.
- If val is any other string value, the function skips any leading spaces in the string, then tries to parse the text as an integer in the given radix. If the radix is 10, and the string (after leading spaces) starts with a dash, the function skips the dash and treats the number as negative; if the radix is 10, and the string starts with a plus sign, the function skips the plus sign. The function then scans all following consecutive numerals in the given radix and returns the resulting integer value.
- If val is of any other type, an error is generated ("invalid type for built-in").
toString(val, radix?)
- If val is an integer, the value is converted to a textual representation. If radix is specified, the conversion is performed in that numeric base; radix can any integer value from 2 to 36, but the most common radix values are 2 (binary), 8 (octal), 10 (decimal), and 16 (hexadecimal). A decimal conversion is done using a signed interpretation of the number, so a negative value will be preceded by a dash in the result string; the number is treated as unsigned for any other radix.
- If val is a BigNumber, the value is converted to a string using the default BigNumber formatting. radix is ignored.
- If val is true or nil, the result is the string 'true' or the string 'nil', respectively.
- If val is a string, the return value is simply val.
- For any other type, an error occurs ("no string conversion").
undo()
When the function returns nil, it will have made no changes to the system state. The function never makes any changes unless it has a complete set of undo information back to a savepoint, so the function will never leave the system in an inconsistent state. The VM has an internal limit on the total amount of undo information retained in memory at any given time, to keep memory consumption under control during a long-running session; as new undo information is added, the VM discards the oldest undo information as needed to keep within the memory limits. This maintains a rolling window of the most recent undo information.