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, #include "tadsgen.h", or simply #include "tads.h" (which includes both "tadsio.h" and "tadsgen.h" for the full set of TADS intrinsics.)
dataType(val) – returns the datatype of the given value. The return value is one of the same TypeXxx values.
firstObj(cls?, flags?) – returns the first object of class cls, or the first object in the entire program if cls is not specified. This is used to start iterating over the set of all instances of a given class; use nextObj() to continue the iteration.. The order in which objects are enumerated by firstObj() and nextObj() is arbitrary, but each object will be returned exactly once. Returns nil if there are no objects of the given class.
If the flags argument is specified, it can a combination (with the '|' operator) of the following bit flags:
If the flags argument is omitted, only instances are enumerated, as though ObjInstances had been specified.
getArg(idx) – retrieve the given argument to the current function. The first argument is at index 1. The index must be in the range 1 to argcount, or the function throws a run-time error (BAD_VAL_BIF).
getFuncParams(funcptr) – returns information on the parameters taken by the given function. The return value is a list with three elements:
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, nil if not.
The second element gives the number of optional arguments; this element is always zero, because there is no way for a function 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() – returns the object that defines the currently executing method. The definer is the object that actually contains the method definition in the source code, so it is not necessarily the current "self" object.
getTime(timeType?) – returns the current system time, according to timeType. If timeType is not specified, GetTimeDateAndTime is the default. The valid timeType values are:
makeString(val, repeatCount?) – construct a string by repeating the given value the given number of times. The result of the function depends on the data type of val:
If repeatCount is not specified, the default value is 1.
max(val1, …) – returns the least argument value. The values must be of comparable types.
min(val1, …) – returns the greatest argument value. The values must be of types that can be compared with one another, or the function throws an error.
nextObj(obj, cls?, flags?) – get the next object after obj of class cls. If cls is not specified, returns the next object of any type. Returns nil if obj is the last object of class cls. This is used (with firstObj()) to iterate over all objects of a given class, or over all objects. The order in which these functions enumerate objects is arbitrary, but each object will be returned exactly once. The flags argument has the same meaning as it does in firstObj().
rand(x, ...) – returns a pseudo-random number or randomly selects a value from a set of values. 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 a number over the range uniformly, which means that each value in the desired range has equal probability.
randomize() – seeds the pseudo-random number generator with a value obtained in a system-dependent manner (in most cases, the seed value is based on the system clock). If randomize() is never called, the random number generator will return the same sequence of numbers every time a program is run; when testing a program, this is often useful, since it means that the program's results are repeatable.
restartGame() – resets all objects (except transient objects) to their initial state, as they were when the program was just loaded. Transient objects are not affected.
restoreGame(filename) – restore the saved state from the given file. All objects, except transient objects, are restored to the state they had when the state was saved to the given file.
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:
rexGroup(group_num) – returns information on the group match for the last regular expression search or match. group_num is the number of the parenthesized group for which to retrieve the information; the first parenthesized expression in the most recent search expression is number 1. Returns nil if there is no such group or 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 of the group match; and the matching string.
rexMatch(pat, str, index?) – tests str to see if the substring starting at index index matches the given regular expression pat, which can be given as a string using regular expression syntax, or as a RexPattern object. 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 match of zero characters, 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?) – replace one or more matches for the regular expression pat within str, starting at the character index. Each match is replaced with the string replacement. 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 at the same position. 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 expression, '%2' by the second group's matching text, and so on. In addition, '%*' is replaced by the match for the entire regular expression. (To substitute a single percent sign, you must use '%%', because of the special meaning of the percent sign in the replacement string.)
Refer to the regular expressions section for details on how to construct a pattern string.
rexSearch(pat, str, index?) – searches for the regular expression pat in the string str, starting at the character position index. The pattern pat can be given as a string using regular expression syntax, or as a RexPattern object.
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 index within str of the first character of the matching substring (the first character in the string is at index 1); the length 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) – saves the state of all objects (except transient objects) to the given file. If an error occurs, the function throws a run-time error to indicate the problem. The saved state can later be restored using restoreGame().
savepoint() – establish an undo savepoint. Multiple savepoints can be established to mark multiple points in time.
toInteger(str, radix?) – convert the given string value to an integer. If the radix value is specified, the conversion uses the given radix; only 8 (octal), 10 (decimal), and 16 (hexadecimal) are allowed. If no radix is specified, the default is 10 (decimal).
If the string contains the text 'nil' or 'true', the return values are nil and true, respectively. Otherwise, the function skips any leading spaces in the string, then tries to parse a number 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.
toString(val, radix?) – convert the given value to a string. If the value is an integer, and radix is specified, the value is converted using the given radix (2 for binary, 8 for octal, 10 for decimal, or 16 for hexadecimal; other radix values below 37 are allowed as well, but these are the most common). 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 radix is not specified, the default radix is 10 (decimal).
If the value is anything other than an integer, the radix value is ignored. If the value is a string, it is returned unchanged. If the value is nil or true, the strings 'nil' and 'true', respectively, are returned. For any other type, the function throws a run-time error (NO_STR_CONV).
undo() – undo changes to the most recent savepoint, as established with the savepoint() function. Returns true if successful, nil if no more undo information is available. This can be called repeatedly; each call undoes changes to the next most recent savepoint. All changes affecting object state since the last savepoint are undone by this operation, except that transient objects are not affected.