# systype.h | documentation

    #charset "us-ascii"
    #pragma once

    /*
     *   Copyright 2000, 2006 Michael J. Roberts.
     *
     *   This file is part of TADS 3.
     *
     *   This module defines the fundamental intrinsic classes, including Object,
     *   String, Collection, List, and Iterator.
     */

    /* ------------------------------------------------------------------------ */
    /*
     *   TADS datatype codes.  These values are returned by propType(), etc.
     */
    #define TypeNil         1
    #define TypeTrue        2
    #define TypeObject      5
    #define TypeProp        6
    #define TypeInt         7
    #define TypeSString     8
    #define TypeDString     9
    #define TypeList        10
    #define TypeCode        11
    #define TypeFuncPtr     12
    #define TypeNativeCode  14
    #define TypeEnum        15
    #define TypeBifPtr      16

    /* ------------------------------------------------------------------------ */
    /*
     *   The root object class.  All objects descend from this class.
     */
    intrinsic class Object 'root-object/030004'
    {
        /*
         *   Determine if I'm an instance or subclass of the given class 'cls'.
         *   Note that x.ofKind(x) returns true - an object is of its own kind.
         */
        ofKind(cls);

        /* get the list of direct superclasses of this object */
        getSuperclassList();

        /* determine if a property is defined or inherited by this object */
        propDefined(prop, flags?);

        /* get the type of a property defined for this object */
        propType(prop);

        /*
         *   Get a list of my directly-defined properties.  When called on
         *   intrinsic class objects, this returns a list of properties defined
         *   for instances of the class, as well as static properties of the
         *   class.
         */
        getPropList();

        /*
         *   get parameter list information for the given method - returns a
         *   list: [minimumArgc, optionalArgc, varargs], where minimumArgc is
         *   the minimum number of arguments, optionalArgc is the number of
         *   additional optional arguments, and varargs is true if the function
         *   takes a varying number of arguments greater than or equal to the
         *   minimum, nil if not.
         */
        getPropParams(prop);

        /*
         *   determine if I'm a "class" object - returns true if the object was
         *   defined with the "class" keyword, nil otherwise
         */
        isClass();

        /*
         *   Determine if a property is inherited further from the given object.
         *   definingObj is usually the value of the 'definingobj'
         *   pseudo-variable, and origTargetObj is usually the value of the
         *   'targetobj' pseudo-variable.
         */
        propInherited(prop, origTargetObj, definingObj, flags?);

        /* determine if this instance is transient */
        isTransient();
    }

    /*
     *   propDefined() flags
     */
    #define PropDefAny           1
    #define PropDefDirectly      2
    #define PropDefInherits      3
    #define PropDefGetClass      4

    /* export the objToString method */
    property objToString;
    export objToString 'objToString';

    /* ------------------------------------------------------------------------ */
    /*
     *   The IntrinsicClass intrinsic class.  Objects of this type represent the
     *   intrinsic classes themselves.
     */
    intrinsic class IntrinsicClass 'intrinsic-class/030001': Object
    {
        /*
         *   Class method: is the given value an IntrinsicClass object?  This
         *   returns true if so, nil if not.
         *
         *   It's not possible to determine if an object is an IntrinsicClass
         *   object using x.ofKind(IntrinsicClass) or via x.getSuperclassList().
         *   This is because those methods traverse the nominal class tree:
         *   [1,2,3] is a List, and List is an Object.  However, List and Object
         *   themselves are represented by IntrinsicClass instances, and it's
         *   occasionally useful to know if you're dealing with such an object.
         *   That's where this method comes in.
         *
         *   This method returns nil for instances of an intrinsic class.  For
         *   example, isIntrinsicClass([1,2,3]) returns nil, because [1,2,3] is a
         *   List instance.  If you get the superclass list for [1,2,3], though,
         *   that will be [List], and isIntrinsicClass(List) returns true.
         */
        isIntrinsicClass(obj);
    }

    /*
     *   Intrinsic class modifier object (for internal compiler use only)
     */
    intrinsic class IntrinsicClassModifier 'int-class-mod/030000'
    {
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   The native collection type - this is the base class for lists, vectors,
     *   and other objects that represent collections of values.
     */
    intrinsic class Collection 'collection/030000': Object
    {
        /*
         *   Create an iterator for the collection.  This returns a new Iterator
         *   object that can be used to iterate over the values in the
         *   collection.  The Iterator will use a snapshot of the collection that
         *   will never change, even if the collection is changed after the
         *   iterator is created.
         */
        createIterator();

        /*
         *   Create a "live iterator" for the collection.  This returns a new
         *   Iterator object that refers directly to the original collection; if
         *   the original collection changes, the iterator will reflect the
         *   changes in its iteration.  As a result, the iterator is not
         *   guaranteed to visit all of the elements in the collection if the
         *   collection changes during the course of the iteration.  If
         *   consistent results are required, use createIterator() instead.
         */
        createLiveIterator();
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   The native iterator type - this is the base class for all iterators.
     *   This class is abstract and is thus never directly instantiated.
     *
     *   Note that iterators can never be created directly with the 'new'
     *   operator.  Instead, iterators must be obtained from a collection via the
     *   collection's createIterator() method.
     */
    intrinsic class Iterator 'iterator/030001': Object
    {
        /*
         *   Get the next item in the collection.  This returns the next item's
         *   value, and advances the internal state in the iterator so that a
         *   subsequent call to getNext() returns the next item after this one.
         *   When the iterator is first created, or after calling
         *   resetIterator(), this returns the first item in the collection.
         */
        getNext();

        /*
         *   Determine if the collection is out of items.  Returns true if
         *   getNext() will return a valid item, nil if no more items are
         *   available.
         */
        isNextAvailable();

        /*
         *   Reset to the first item.  After calling this routine, the next call
         *   to getNext() will return the first item in the collection.
         */
        resetIterator();

        /*
         *   Get the current key.  This returns the value of the key for the
         *   current item in the collection.  For an indexed collection, this
         *   returns the index value; for a keyed collection, this returns the
         *   current key value.
         */
        getCurKey();

        /*
         *   Get the current value.  This returns the value of the current item
         *   in the collection.
         */
        getCurVal();
    }

    /*
     *   Indexed object iterator - this type of iterator is used for lists,
     *   vectors, and other indexed collection objects.
     */
    intrinsic class IndexedIterator 'indexed-iterator/030000': Iterator
    {
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   AnonFuncPtr depends on Vector
     */
    #include "vector.h"

    /*
     *   Anonymous function pointer intrinsic class
     */
    intrinsic class AnonFuncPtr 'anon-func-ptr': Vector
    {
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   The "TADS Object" intrinsic class.  All objects that the program
     *   defines with the "class" or "object" statements descend from this
     *   class.
     */
    intrinsic class TadsObject 'tads-object/030005': Object
    {
        /*
         *   Create an instance of this object: in other words, create a new
         *   object whose superclass is this object.  The arguments provided are
         *   passed to the new object's constructor.  This method returns a
         *   reference to the new object.
         */
        createInstance(...);

        /*
         *   Create a clone of this object.  This creates an exact copy, with
         *   the same property values, as the original.  This does not call any
         *   constructors; it merely instantiates an exact copy of the original.
         *
         *   Note that the clone is a "shallow" copy, which means that any
         *   objects it references are not themselves cloned.
         */
        createClone();

        /*
         *   Create a transient instance of this object.  This works just like
         *   createInstance(), but creates a transient instance instead of an
         *   ordinary (persistent) instance.
         */
        createTransientInstance(...);

        /*
         *   Create an instance of an object based on multiple superclasses.
         *   Each argument gives a superclass, and optionally arguments for
         *   invoking the superclass constructor.  If an argument is given as
         *   simply a class, then we don't invoke that superclass's constructor;
         *   if the argument is given as a list, the first element of the list is
         *   the class, and the remaining elements of the list are arguments for
         *   that superclass's constructor.  The arguments are specified in the
         *   same order they would be to define the object, so the first argument
         *   is the dominant superclass.
         *
         *   For example, suppose we created a class definition like this:
         *
         *   class D: A, B, C
         *.    construct(x, y)
         *.    {
         *.      inherited A(x);
         *.      inherited C(y);
         *.    }
         *.  ;
         *
         *   We could obtain the same effect dynamically like so:
         *
         *   local d = TadsObject.createInstanceOf([A, x], B, [C, y]);
         *
         *   Note that only *actual* lists are interpreted as constructor
         *   invokers here.  A list-like object (with operator[] and length()
         *   methods) will be treated as a simple superclass, since otherwise it
         *   wouldn't be possible to specify the no-constructor format for such a
         *   superclass.
         */
        static createInstanceOf(...);

        /*
         *   Create a transient instance based on multiple superclasses.  This
         *   works just like createInstanceOf(), but creates a transient
         *   instance.
         */
        static createTransientInstanceOf(...);

        /*
         *   Set the superclass list.  scList is a list giving the new
         *   superclasses.  The superclasses must all be TadsObject objects, with
         *   one exception: the list [TadsObject] may be passed to create an
         *   object based directly on TadsObject.  No other intrinsic classes can
         *   be used in the list, and objects of other types cannot be used in
         *   the list.
         */
        setSuperclassList(scList);

        /*
         *   Get a method value.  If the property is a method, this returns a
         *   function pointer to the method; this does NOT evaluate the method.
         *   If the property is not a method, this returns nil.
         *
         *   The returned function pointer can be called like an ordinary
         *   function, but such a call will have no 'self' value, so the
         *   disembodied method won't be able to refer to properties or methods
         *   of 'self'.  The main use of this method is to get a method of one
         *   object to assign as a method of another object using setMethod().
         */
        getMethod(prop);

        /*
         *   Set a method value.  Assigns the given function (which must be a
         *   function pointer value) to the given property of 'self'.  This
         *   effectively adds a new method to the object.
         *
         *   The function can be an ordinary named function, or a method pointer
         *   retrieved from this object or from another object with getMethod().
         *   Anonymous functions are NOT allowed here.
         */
        setMethod(prop, func);
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   We need CharacterSet and ByteArray (for String.mapToByteArray).  (But
     *   wait to include these until after we've defined Object, since everything
     *   depends on Object.)
     */
    #include "charset.h"
    #include "bytearr.h"

    /* ------------------------------------------------------------------------ */
    /*
     *   The native string type.
     */
    intrinsic class String 'string/030008': Object
    {
        /* get the length of the string */
        length();

        /* extract a substring */
        substr(start, len?);

        /* convert to upper case */
        toUpper();

        /* convert to lower case */
        toLower();

        /*
         *   Find a substring or pattern within the subject string (self),
         *   searching the string from left to right returning the index of the
         *   first match found.  If 'str' is a string, this searches for an exact
         *   match to the substring.  If 'str' is a RexPattern object, this
         *   searches for a match to the pattern.  Returns the character index of
         *   the start of the match if found (the first character is at index 1),
         *   or nil if no match is found.
         *
         *   'index' is the optional starting index for the search.  the first
         *   character is at index 1; a negative index specifies an offset from
         *   the end of the string, with -1 indicating the last character, -2 the
         *   second to last, and so on.  If 'index' is omitted, the search starts
         *   at the first character.  Note that the search proceeds from left to
         *   right even if 'index' is negative - a negative starting index is
         *   just a convenience to specify an offset from the end of the string,
         *   but the search still proceeds in the same direction.
         *
         *   (Note: "left to right" in this context simply means from lower to
         *   higher character index in the string.  We're using the term loosely,
         *   in particular ignoring anything related to the reading order or
         *   display direction for different languages or scripts.)
         */
        find(str, index?);

        /*
         *   convert to a list of Unicode character codes, or get the Unicode
         *   character code for the single character at the given index
         */
        toUnicode(idx?);

        /* htmlify a string */
        htmlify(flags?);

        /* determine if we start with the given string */
        startsWith(str);

        /* determine if we end with the given string */
        endsWith(str);

        /*
         *   Map to a byte array, converting to the given character set.  If
         *   'charset' is provided, it must be an object of intrinsic class
         *   CharacterSet, or a string giving the name of a character set.  The
         *   characters in the string are mapped from the internal Unicode
         *   representation to the appropriate byte representation in the given
         *   character set.  Any unmappable characters are replaced with the
         *   usual default/missing character for the set, as defined by the
         *   mapping.
         *
         *   If 'charset' is omitted or nil, the byte array is created simply by
         *   treating the Unicode character code of each character in the string
         *   as a byte value.  A byte can only hold values from 0 to 255, so a
         *   numeric overflow error is thrown if any character code in the source
         *   string is outside this range.
         *
         */
        mapToByteArray(charset?);

        /*
         *   Replace one occurrence or all occurrences of the given substring
         *   with the given new string.
         *
         *   'self' is the subject string, which we search for instances of the
         *   replacement.
         *
         *   'origStr' is the string to search for within 'self'.  This is
         *   treated as a literal text substring to find within 'self'.
         *   'origStr' can alternatively be a RexPattern object, in which case
         *   the regular expression is matched.
         *
         *   'newStr' is the replacement text, as a string.  'newStr' can
         *   alternatively be a function (regular or anonymous) instead of a
         *   string.  In this case, it's invoked as 'newStr(match, index, orig)'
         *   for each match where 'match' is the matching text, 'index' is the
         *   index within the original subject string of the match, and 'orig' is
         *   the full original subject string.  This function must return a
         *   string value, which is used as the replacement text.  Using a
         *   function allows greater flexibility in specifying the replacement,
         *   since it can vary the replacement according to the actual text
         *   matched and its position in the subject string.
         *
         *   'flags' is a combination of ReplaceXxx flags specifying the search
         *   options.  It's optional; if omitted, the default is ReplaceAll.
         *
         *   ReplaceOnce and ReplaceAll are mutually exclusive; they mean,
         *   respectively, that only the first occurrence of the match should be
         *   replaced, or that every occurrence should be replaced.  ReplaceOnce
         *   and ReplaceAll are ignored if a 'limit' value is specified (this is
         *   true even if 'limit' is nil, which means that all occurrences are
         *   replaced).
         *
         *   'index' is the starting index within 'self' for the search.  If this
         *   is given, we'll ignore any matches that start before the starting
         *   index.  If 'index' is omitted, we start the search at the beginning
         *   of the string.  If 'index' is negative, it's an index from the end
         *   of the string: -1 is the last character, -2 the second to last, etc.
         *
         *   'origStr' can be given as a list of search strings, rather than a
         *   single string.  In this case, we'll search for each of the strings
         *   in the list, and replace each one with 'newStr'.  If 'newStr' is
         *   also a list, each match to an element of the 'origStr' list is
         *   replaced with the corresponding element (at the same index) of the
         *   'newStr' list.  If there are more 'origStr' elements than 'newStr'
         *   elements, each match to an excess 'origStr' element is replaced with
         *   an empty string.  This allows you to perform several replacements
         *   with a single call.
         *
         *   'limit', if specified, is an integer indicating the maximum number
         *   of matches to replace, or nil to replace all matches.  If the limit
         *   is reached before all matches have been replaced, no further
         *   replacements are performed.  If this parameter is specified, it
         *   overrides any ReplaceOnce or ReplaceAll flag.
         *
         *   There are two search modes when 'origStr' is a list.  The default is
         *   "parallel" mode.  In this mode, we search for all of the 'origStr'
         *   elements, and replace the leftmost match.  We then search the
         *   remainder of the string, after this first match, again searching for
         *   all of the 'origStr' elements.  Again we replace the leftmost match.
         *   We repeat this until we run out of matches.
         *
         *   The other option is "serial" mode, which you select by including
         *   ReplaceSerial in the flags argument.  In serial mode, we start by
         *   searching only for the first 'origStr' element.  We replace each
         *   occurrence throughout the string (unless we're in ReplaceOnce mode,
         *   in which case we stop after the first replacement).  If we're in
         *   ReplaceOnce mode and we did a replacement, we're done.  Otherwise,
         *   we start over with the updated string, containing the replacements
         *   so far, and search it for the second 'origStr' element, replacing
         *   each occurrence (or just the first, in ReplaceOnce mode).  We repeat
         *   this for each 'origStr' element.
         *
         *   The key difference between the serial and parallel modes is that the
         *   serial mode re-scans the updated string after replacing each
         *   'origStr' element, so replacement text could itself be further
         *   modified.  Parallel mode, in contrast, never re-scans replacement
         *   text.
         */
        findReplace(origStr, newStr, flags?, index?, limit?);

        /*
         *   Splice: delete 'del' characters starting at 'idx', and insert the
         *   string 'ins' in their place.  'ins' is optional; if omitted, this
         *   simply does the deletion without inserting anything.
         */
        splice(idx, del, ins?);

        /*
         *   Split the string into substrings at the given delimiter, or of a
         *   given fixed length.
         *
         *   'delim' is the delimiter.  It can be one of the following:
         *
         *   - A string or RexPattern, giving the delimiter where we split the
         *   string.  We search 'self' for matches to this string or pattern, and
         *   split it at each instance we find, returning a list of the resulting
         *   substrings.  For example, 'one,two,three'.split(',') returns the
         *   list ['one', 'two', 'three'].  The delimiter separates parts, so
         *   it's not part of the returned substrings.
         *
         *   - An integer, giving a substring length.  We split the string into
         *   substrings of this exact length (except that the last element will
         *   have whatever's left over).  For example, 'abcdefg'.split(2) returns
         *   ['ab', 'cd', 'ef', 'g'].
         *
         *   If 'delim' is omitted or nil, the default is 1, so we'll split the
         *   string into one-character substrings.
         *
         *   If 'limit' is included, it's an integer giving the maximum number of
         *   elements to return in the result list.  If we reach the limit, we'll
         *   stop the search and return the entire rest of the string as the last
         *   element of the result list.  If 'limit' is 1, we simply return a
         *   list consisting of the source string, since a limit of one element
         *   means that we can't make any splits at all.
         */
        split(delim?, limit?);

        /*
         *   Convert special characters and TADS markups to standard HTML
         *   markups.  Returns a new string with the contents of the 'self'
         *   string processed as described below.
         *
         *   'stateobj' is an object containing the state of the output stream.
         *   This allows an output stream to process its contents a bit at a
         *   time, by maintaining the state of the stream from one call to the
         *   next.  This object gives the prior state of the stream on entry, and
         *   is updated on return to contain the new state after processing this
         *   string.  If this is omitted or nil, a default initial starting state
         *   is used.  The function uses the following properties of the object:
         *
         *   stateobj.flags_ is an integer with a collection of flag bits giving
         *   the current line state
         *
         *   stateobj.tag_ is a string containing the text of the tag currently
         *   in progress.  If the string ends in the middle of a tag, this will
         *   be set on return to the text of the tag up to the end of the string,
         *   so that the next call can resume processing the tag where the last
         *   call left off.
         *
         *
         *   The function makes the following conversions:
         *
         *   \n -> <BR>, or nothing at the start of a line
         *
         *   \b -> <BR> at the start of a line, or <BR><BR> within a line
         *
         *   \ (quoted space) -> &nbsp; if followed by a space or another quoted
         *   space, or an ordinary space if followed by a non-space character
         *
         *   \t -> a sequence of &nbsp; characters followed by a space, padding
         *   to the next 8-character tab stop.  This can't take into account the
         *   font metrics, since that's determined by the browser, so it should
         *   only be used with a monospaced font.
         *
         *   \^ -> sets an internal flag to capitalize the next character
         *
         *   \v -> sets an internal flag to lower-case the next character
         *
         *   <Q> ... </Q> -> &ldquo; ... &rdquo; or &lsquo; ... &rsquo;,
         *   depending on the nesting level
         *
         *   <BR HEIGHT=N> -> N <BR> tags if at the start of a line, N+1 <BR>
         *   tags if within a line
         *
         *
         *   Note that this isn't a general-purpose HTML corrector: it doesn't
         *   correct ill-formed markups or standardize deprecated syntax or
         *   browser-specific syntax.  This function is specifically for
         *   standardizing TADS-specific syntax, so that games can use the
         *   traditional TADS syntax with the Web UI.
         */
        specialsToHtml(stateobj?);

        /*
         *   Convert special characters and HTML markups to plain text, as it
         *   would appear if written out through the regular console output
         *   writer and displayed on a plain text terminal.  Returns a new string
         *   with the contents of the 'self' string processed as described below.
         *   This works very much like specialsToHtml(), but rather than
         *   generating standard HTML output, we generate plain text output.
         *
         *   'stateobj' has the same meaning asin specialsToHtml().
         *
         *   The function makes the following conversions:
         *
         *   \n -> \n, or nothing at the start of a line
         *
         *   \b -> \n at the start of a line, or \n\n within a line
         *
         *   \ (quoted space) -> regular space
         *
         *   \^ -> sets an internal flag to capitalize the next character
         *
         *   \v -> sets an internal flag to lower-case the next character
         *
         *   <Q> ... </Q> -> "..." or '...' depending on the quote nesting level
         *
         *   <BR HEIGHT=n> -> N \n characters at the start of a line, N+1 \n
         *   characters within a line
         *
         *   <P> -> \n at the start of a line, \n\n within a line
         *
         *   <TAG> -> nothing for all other tags
         *
         *   &amp; -> &
         *
         *   &lt; -> <
         *
         *   &gt; -> >
         *
         *   &quot; -> "
         *
         *   &ldquo; and &rdquo; -> "
         *
         *   &lsquo; and &rsquo; -> '
         *
         *   &#dddd; -> Unicode character dddd
         */
        specialsToText(stateobj?);

        /*
         *   Encode a URL parameter string.  Spaces are encoded as "+", and all
         *   other non-alphanumeric characters except - and _ are encoded as
         *   "%xx" sequences.
         */
        urlEncode();

        /*
         *   Decode a URL parameter string.  This reverses the effect of
         *   urlEncode(), returning a string with the encodings translated back
         *   into ordinary characters.  Any sequences that do not form valid
         *   UTF-8 characters are converted to '?'.
         */
        urlDecode();

        /*
         *   Get the SHA-256 hash of the string.  This calculates the 256-bit
         *   Secure Hash Algorithm 2 hash value, returning the hash as a
         *   64-character string of hex digits.  The hash value is computed on
         *   the UTF-8 representation of the string.
         */
        sha256();

        /*
         *   Get the MD5 digest of the string.  This calculates the 128-bit RSA
         *   MD5 digest value, returning the digest as a 32-character string of
         *   hex digits.  The hash value is computed on the UTF-8 representation
         *   of the string.
         */
        digestMD5();

        /*
         *   Pack the arguments into bytes, and create a new string from the byte
         *   values.  The characters of the new string correspond to the packed
         *   byte values, so each character will have a Unicode character number
         *   from 0 to 255.
         *
         *   'format' is a format string describing the packed formats for the
         *   values, and the rest of the arguments are the values to pack into
         *   the string.  Returns a string containing the packed bytes.
         *
         *   See Byte Packing in the System Manual for more details.
         */
        static packBytes(format, ...);

        /*
         *   Unpack this string, interpreting the characters in the string as
         *   byte values, and unpacking the bytes according to the format string.
         *   Each character in the string must have a Unicode character number
         *   from 0 to 255; if any characters are outside this range, an error is
         *   thrown.
         *
         *   This method can be used to unpack a string created with
         *   String.packBytes().  In most cases, using the same format string
         *   that was used to pack the bytes will re-create the original values.
         *   This method can also be convenient for parsing plain text that's
         *   arranged into fixed-width fields.
         *
         *   'format' is the format string describing the packed byte format.
         *   Returns a list consisting of the unpacked values.
         *
         *   See Byte Packing in the System Manual for more details.
         */
        unpackBytes(format);

        /*
         *   Convert each character in the string to title case, according to the
         *   Unicode character database definitions.  Returns a new string with
         *   the title-case version of this string.
         *
         *   For most characters, title case is the same as upper case.  It
         *   differs from upper case when a single Unicode character represents
         *   more than one printed letter, such as the German sharp S U+00DF, or
         *   the various "ff" and "fi" ligatures.  In these cases, the title-case
         *   conversion consists of the upper-case version of the first letter of
         *   the ligature followed by the lower-case versions of the remaining
         *   characters.  Unicode doesn't define single-character title-case
         *   equivalents of most of the ligatures, so the result is usually a
         *   sequence of the individual characters making up the ligature.  For
         *   example, title-casing the 'ffi' ligature character (U+FB03) produces
         *   the three-character sequence 'F', 'f', 'i'.
         *
         *   Note that this routine converts every character in the string to
         *   title case, so it's not by itself a full title formatter - it's
         *   simply a character case converter.
         */
        toTitleCase();

        /*
         *   Convert the string to "folded" case.  Returns a new string with the
         *   case-folded version of this string.
         *
         *   Folded case is used for eliminating case distinctions in sets of
         *   strings, to allow for case-insensitive comparisons, sorting, etc.
         *   This routine produces the case folding defined in the Unicode
         *   character database; in most cases, the result is the same as
         *   converting each original character to upper case and then converting
         *   the result to lower case.  This process not only removes case
         *   differences but also normalizes some variations in the ways certain
         *   character sequences are rendered, such as converting the German
         *   ess-zed U+00DF to "ss", and converting lower-case accented letters
         *   that don't have single character upper-case equivalents to the
         *   corresponding series of composition characters (e.g., U+01F0, a
         *   small 'j' with a caron, turns into U+006A + U+030C, a regular small
         *   'j' followed by a combining caron character).  Without this
         *   normalization, the upper- and lower-case renderings of such
         *   characters wouldn't match.
         */
        toFoldedCase();

        /*
         *   Compare this string to another string, using Unicode character code
         *   points as the collation order.  Returns an integer less than zero if
         *   this string sorts before the other string, zero if they're
         *   identical, or greater than zero if this string sorts after the
         *   other.  This makes the result suitable for use in a sort() callback,
         *   for example.
         *
         *   Note that if you use the result for sorting text that includes
         *   accented Roman letters, the result order probably won't match the
         *   dictionary order for your language.  Different languages (and even
         *   different countries/cultures sharing a language) have different
         *   rules for dictionary ordering, so collation is inherently language-
         *   specific.  This routine doesn't take language differences into
         *   account; it simply uses the fixed Unicode code point ordering.  The
         *   Unicode ordering for accented characters is somewhat arbitrary,
         *   because the accented Roman characters are arranged into multiple
         *   disjoint blocks that are all separate from the unaccented
         *   characters.  For example, A-caron sorts after Z-caron, which sorts
         *   after A-breve, which sorts after Y-acute, which sorts after A-acute,
         *   which sorts after plain Z.
         */
        compareTo(str);

        /*
         *   Compare this string to another string, ignoring case.  The two
         *   strings are compared on the basis of the "case folded" versions of
         *   their characters, using the case folding rules from the Unicode
         *   standard (the case folded version of a string is the value returned
         *   by toFoldedCase()).  The return alue is an integer less than zero if
         *   this string sorts before the other string, zero if they're
         *   identical, or greater than zero if this string sorts after the
         *   other.
         *
         *   As with compareTo(), this only produces alphabetically correct
         *   sorting order when comparing ASCII strings.
         */
        compareIgnoreCase(str);

        /*
         *   Find the last instance of a substring or pattern within the string,
         *   searching the subject string (self) from right to left (that is,
         *   from the end of the string towards the beginning).  This works like
         *   find(), but searches in the reverse direction.  Returns the index of
         *   the match, or nil if no match is found.
         *
         *   'str' can be a string or a RexPattern.  If it's a string, we look
         *   for an exact match to the substring.  If it's a RexPattern, we
         *   search for a match to the pattern.
         *
         *   The optional 'index' specifies the starting index for the search.
         *   This is the index of the character AFTER the last character that's
         *   allowed to be included in the match.  The first character of the
         *   string is at index 1; a negative index indicates an offset from the
         *   end of the string, so -1 is the last character.  0 has the special
         *   meaning of the end of the string, just past the last character in
         *   the string, so you can use 0 (or, equivalently, self.length()+1) to
         *   search the entire string from the end.  For a repeated search, pass
         *   the index of the previous match, since this will find the next
         *   earlier matching substring that doesn't overlap with the previous
         *   match.
         *
         *   (Note: "right to left" in this context simply means that the search
         *   runs from higher to lower character index in the string.  We're
         *   using the term loosely, in particular ignoring anything related to
         *   the reading order or display direction for different languages or
         *   scripts.)
         */
        findLast(str, index?);

        /*
         *   Find all occurrences of substring or pattern within a string,
         *   returning a list of the results.
         *
         *   'str' can be a string or RexPattern object.  If it's a string, we
         *   look for exact matches to the substring.  If it's a RexPattern, we
         *   search for matches to the pattern.
         *
         *   'func' is an optional function used to process the results.  If this
         *   is provided, the function is called once for each match found in the
         *   string.  The function's return value is then placed into the result
         *   list for the overall findAll() result.  The function is called for
         *   each match found as follows: func(match, idx, g1, g2, ...), where
         *   'match' is a string giving the text of the match, 'idx' is an
         *   integer giving the index in the string (self) of the first character
         *   of the match, and the 'gN' arguments are strings giving the text of
         *   the correspondingly numbered capture groups (the parenthesized
         *   groups in a regular expression match).  All of the 'func' arguments
         *   except 'match' are optional: the function can omit them, in which
         *   case the caller doesn't pass them.  If 'func' specifies more 'gN'
         *   capture group parameters than were actually found in the match, nil
         *   is passed for each extra parameter.
         *
         *   The return value is a list of the results.  If no occurrences of
         *   'str' are found, the result is an empty list.  If 'func' is
         *   specified, each element in the return list is the return value from
         *   calling 'func' for the corresponding match; if 'func' is omitted,
         *   each element in the return list is a string with the text of that
         *   match.
         */
        findAll(str, func?);

        /*
         *   Match the given string or RexPattern object to this string value,
         *   starting at the start of the string or at the given index, if
         *   specified.  If 'str' is a string, we check for a match to the
         *   literal text of the string; if 'str' is a RexPattern, we try to
         *   match the regular expression.  'idx' is the optional starting
         *   position (1 is the first character; negative values are from the end
         *   of the string, with -1 as the last character, -2 as the second to
         *   last, etc).  If 'idx' is omitted, the default is the start of the
         *   string.
         *
         *   Returns an integer giving the length of the match found if the
         *   string matches 'str', or nil if there's no match.
         *
         *   The difference between this method and find() is that this method
         *   only checks for a match at the given starting position, without
         *   searching any further in the string, whereas find() searches for a
         *   match at each subsequent character of the string until a match is
         *   found or the string is exhausted.
         */
        match(str, idx?);
    }

    /*
     *   Flags for String.htmlify
     */

    /*
     *   translate spaces - each space in a run of multiple spaces is converted
     *   to an &nbsp; sequence
     */
    #define HtmlifyTranslateSpaces    0x0001

    /* translate newlines - converts each \n character to a <br> tag */
    #define HtmlifyTranslateNewlines  0x0002

    /* translate tabs - converts each \t character to a <tab> tag */
    #define HtmlifyTranslateTabs      0x0004

    /*
     *   Translate all whitespace characters - translate all spaces, tabs, and
     *   newlines into their HTML equivalents: each space character becomes an
     *   '&nbsp sequence;', each '\n' character becomes a <br> tag; and each
     *   '\t' character becomes a <tab> tag.
     */
    #define HtmlifyTranslateWhitespace \
        (HtmlifyTranslateSpaces | HtmlifyTranslateNewlines | HtmlifyTranslateTabs)

    /*
     *   Flags for String.findReplace
     */
    #define ReplaceAll         0x0001
    #define ReplaceIgnoreCase  0x0002
    #define ReplaceFollowCase  0x0004
    #define ReplaceSerial      0x0008
    #define ReplaceOnce        0x0010

    /* property exports for specialsToHtml's state object */
    property flags_, tag_;
    export flags_ 'String.specialsToHtml.flags';
    export tag_ 'String.specialsToHtml.tag';

    /* ------------------------------------------------------------------------ */
    /*
     *   The native list type
     */
    intrinsic class List 'list/030008': Collection
    {
        /*
         *   Select a subset of the list: returns a new list consisting only
         *   of the elements for which the callback function 'func' returns
         *   true.
         */
        subset(func);

        /*
         *   Apply the callback function to each element of this list, and
         *   return a new list consisting of the results.  Effectively maps
         *   the list to a new list using the given function.  Suppose the
         *   original list is
         *
         *   [x, y, z]
         *
         *   Then the result list is
         *
         *   [func(x), func(y), func(z)]
         */
        mapAll(func);

        /* get the number of elements in the list */
        length();

        /* extract a sublist */
        sublist(start, len?);

        /* intersect with another list */
        intersect(other);

        /* get the index of the first match for the given value */
        indexOf(val);

        /* car/cdr - head/tail of list */
        car();
        cdr();

        /*
         *   Find the first element for which the given condition is true, and
         *   return the index of the element.  Applies the callback function
         *   (which encodes the condition to evaluate) to each element in
         *   turn, starting with the first.  For each element, if the callback
         *   returns nil, proceeds to the next element; otherwise, stops and
         *   returns the index of the element.  If the callback never returns
         *   true for any element, we'll return nil.
         */
        indexWhich(cond);

        /*
         *   Invoke the callback func(val) on each element, in order from first
         *   to last.  No return value.
         */
        forEach(func);

        /*
         *   Find the first element for which the given condition is true, and
         *   return the value of the element.  Returns nil if no item
         *   satisfies the condition.
         */
        valWhich(cond);

        /* find the last element with the given value, and return its index */
        lastIndexOf(val);

        /*
         *   Find the last element for which the condition is true, and return
         *   the index of the element.  Applies the callback to each element
         *   in turn, starting with the last element and working backwards.
         *   For each element, if the callback returns nil, proceeds to the
         *   previous element; otherwise, stops and returns the index of the
         *   element.  If the callback never returns true for any element,
         *   we'll return nil.
         */
        lastIndexWhich(cond);

        /*
         *   Find the last element for which the condition is true, and return
         *   the value of the element
         */
        lastValWhich(cond);

        /* count the number of elements with the given value */
        countOf(val);

        /* count the number of elements for which the callback returns true */
        countWhich(cond);

        /* get a new list consisting of the unique elements of this list */
        getUnique();

        /*
         *   append the elements of the list 'lst' to the elements of this
         *   list, then remove repeated elements in the result; returns a new
         *   list with the unique elements of the combination of the two lists
         */
        appendUnique(lst);

        /*
         *   append an element - this works almost exactly like the
         *   concatation operator ('+'), but if the argument is a list, this
         *   simply adds the list as a new element, rather than adding each
         *   element of the list as a separate element
         */
        append(val);

        /*
         *   Sort the list, returning a new list.  If the 'descending' flag is
         *   provided and is not nil, we'll sort the list in descending order
         *   rather than ascending order.
         *
         *   If the 'comparisonFunction' argument is provided, it must be a
         *   callback function; the callback takes two arguments, and returns
         *   an integer less than zero if the first argument value is less
         *   than the second, zero if they're equal, and an integer greater
         *   than zero if the first is greater than the second.  If no
         *   'comparisonFunction' argument is provided, or it's provided and
         *   its value is nil, we'll simply compare the list elements as
         *   ordinary values.  The comparison function can be provided for
         *   caller-defined orderings, such as ordering a set of objects.
         */
        sort(descending?, comparisonFunction?);

        /*
         *   Prepend an element - this inserts the value before the first
         *   existing element.
         */
        prepend(val);

        /*
         *   Insert one or more elements at the given index.  If the starting
         *   index is 1, the elements will be inserted before the first existing
         *   element.  If the index is one higher than the number of elements,
         *   the elements will be inserted after all existing elements.  If the
         *   index is negative, it counts backwards from the end of the list: -1
         *   inserts before the last element, -2 inserts before the second to
         *   last, and so on.  If the index is zero, the new elements are
         *   inserted after the last element.
         *
         *   Note that a list value argument will simply be inserted as a single
         *   element.
         *
         *   Returns a new list with the value(s) inserted.
         */
        insertAt(startingIndex, val, ...);

        /*
         *   Delete the element at the given index, reducing the length of the
         *   list by one element.  If the index is negative, it counts from the
         *   end of the list: -1 is the last element, -2 is the second to last,
         *   etc.  Returns a new list with the given element removed.
         */
        removeElementAt(index);

        /*
         *   Delete the range of elements starting at startingIndex and ending at
         *   endingIndex.  The elements at the ends of the range are included in
         *   the deletion.  If startingIndex == endingIndex, only one element is
         *   removed.  If either index is negative, it counts from the end of the
         *   list: -1 is the last element, -2 is the second to last, etc.
         *   Returns a new list with the given element range removed.
         */
        removeRange(startingIndex, endingIndex);

        /*
         *   Invoke the callback func(index, val) on each element, in order from
         *   first to last.  No return value.
         */
        forEachAssoc(func);

        /*
         *   Class method: Generate a new list.  'func' is a callback function,
         *   which can take zero or one argument.  'n' is the number of elements
         *   for the new list.  For each element, 'func' is invoked as func() if
         *   it takes no arguments, or func(idx) if it takes one argument, where
         *   'idx' is the index of the element being generated.  The return value
         *   of the call to 'func' is stored as the list element.  The method
         *   returns the resulting list.  For example, a list of the first ten
         *   even positive integers: List.generate({i: i*2}, 10).
         */
        static generate(func, n);

        /*
         *   Splice new values into the list.  Deletes the 'del' list items
         *   starting at 'idx', then inserts the extra arguments in their place.
         *   Returns a new list reflecting the spliced values.  To insert items
         *   without deleting anything, pass 0 for 'del'.  To delete items
         *   without inserting anything, omit any additional arguments.
         */
        splice(idx, del, ...);

        /*
         *   Combine the list elements into a string.  This converts each element
         *   into a string value using the usual default conversions (or throws
         *   an error if string conversion isn't possible), then concatenates the
         *   values together and returns the result.  If 'separator' is provided,
         *   it's a string that's interposed between elements; if this is
         *   omitted, the elements are concatenated together with no extra
         *   characters in between.
         */
        join(sep?);

        /*
         *   Get the index of the list item with the minimum value.  If 'func' is
         *   missing, this simply returns the index of the list element with the
         *   smallest value, comparing the element values as though using the '>'
         *   and '<' operators.  If 'func' is specified, it must be a function;
         *   it's called as func(x) for each value in the list, and the result of
         *   the overall call is the index of the element for which func(x)
         *   returns the smallest value.  For example, if you have a list of
         *   strings l, l.indexOfMin({x: x.length()}) returns the index of the
         *   shortest string in the list.
         */
        indexOfMin(func?);

        /*
         *   Get the minimum value in the list.  If 'func' is missing, this
         *   returns the minimum element value.  If 'func' is specified, it must
         *   be a function; it's called as func(x) for each value in the list,
         *   and the result of the overall method call is the element value x
         *   that minimizes func(x).  For example, if l is a list of strings,
         *   l.minVal({x: x.length()}) returns the shortest string.
         */
        minVal(func?);

        /*
         *   Get the index of the list item with the maximum value.  If 'func' is
         *   missing, this simply returns the index of the list element with the
         *   largest value, comparing the element values as though using the '>'
         *   and '<' operators.  If 'func' is specified, it must be a function;
         *   it's called as func(x) for each value in the list, and the result of
         *   the overall call is the index of the element for which func(x)
         *   returns the greatest value.  For example, if you have a list of
         *   strings l, l.indexOfMax({x: x.length()}) returns the index of the
         *   longest string in the list.
         */
        indexOfMax(func?);

        /*
         *   Get the maximum value in the list.  If 'func' is missing, this
         *   returns the largest element value.  If 'func' is specified, it must
         *   be a function; it's called as func(x) for each value in the list,
         *   and the result of the overall method call is the element value x
         *   that maximizes func(x).  For example, if l is a list of strings,
         *   l.maxVal({x: x.length()}) returns the longest string.
         */
        maxVal(func?);
    }

    /*
     *   Sorting order flags.  These can be passed in as the first argument to
     *   List.sort() (and Vector.sort() as well) to make the meaning of the
     *   argument clearer.
     */
    #define SortAsc    nil
    #define SortDesc   true

    /*
     *   Export length() as the element counter method for list-like objects in
     *   general.
     */
    export length 'length';

    /* ------------------------------------------------------------------------ */
    /*
     *   'RexPattern' intrinsic class.  This class encapsulates a compiled
     *   regular expression pattern.
     *
     *   A RexPattern object can be passed to the regular expression functions
     *   (rexMatch, rexSearch, rexReplace) in place of a string pattern.  Since
     *   compiling a regular expression takes a non-trivial amount of time, it's
     *   more efficient to compile a pattern to a RexPattern object if the same
     *   pattern will be used in multiple searches.
     */
    intrinsic class RexPattern 'regex-pattern/030000': Object
    {
        /*
         *   Constructor:
         *
         *   new RexPattern(patternString) - returns a RexPattern representing
         *   the compiled pattern string.
         */

        /* retrieve the original pattern string used to construct the object */
        getPatternString();
    }

    /* ------------------------------------------------------------------------ */
    /*
     *   StackFrameDesc intrinsic class.  This class provides access to a stack
     *   frame.  It lets us retrieve the values of local variables and method
     *   context variables (self, definingobj, targetobj, targetprop).  It also
     *   allows us to assign new values to local variables.
     *
     *   To get the value of a local variable in the frame, simply use
     *   frame[name], where 'frame' is the StackFrameDesc object for the frame,
     *   and 'name' is a string giving the name of the local variable to
     *   retrieve.  If the frame is active, this retrieves the live value of the
     *   variable from the frame; otherwise it retrieves the value from a
     *   snapshot containing the last value before the routine returned to its
     *   caller.
     *
     *   To assign a new value to a local in the frame, assign a value to
     *   frame[name] for the desired variable name.  If the frame is active, this
     *   updates the live variable in the stack frame, so when execution returns
     *   to the caller the variable will have the new value.  If the frame is
     *   inactive, it updates the snapshot we made when the routine returned to
     *   its caller.
     *
     *   This object can't be created with 'new'.  Instead, you obtain these
     *   objects via the t3GetStackTrace() function.  That function retrieves
     *   information on an active stack frame in the current call stack,
     *   including the frame object.
     */
    intrinsic class StackFrameDesc 'stack-frame-desc/030000'
    {
        /*
         *   Is the stack frame active?  A stack frame is active until the
         *   function or method it represents returns to its caller.  When the
         *   routine returns, the frame becomes inactive.
         *
         *   When the routine is about to return (so the frame is about to become
         *   inacive), the StackFrameDesc object makes a private snapshot of the
         *   variables in the frame.  Subsequent access to the locals will
         *   automatically use the snapshot copy, so you can continue to access
         *   the locals as normal without worrying about whether or not the
         *   actual stack frame still exists.  This allows you to continue to
         *   access and modify the values of the variables after the routine has
         *   exited.
         */
        isActive();

        /*
         *   Get a LookupTable consisting of all of the variables (local
         *   variables and parameters) in the frame.  Each element in the table
         *   is keyed by the name of a variable, and contains the current value
         *   of the variable.
         *
         *   The returned lookup table is a snapshot copy of the current values
         *   of the variables.  If the underlying variable values in the frame
         *   change, the lookup table won't be affected, since it's just a
         *   separate copy made at the moment this routine is called.  Similarly,
         *   changing the value of an entry in the returned lookup table won't
         *   affect the actual variable in the stack frame.
         *
         *   To retrieve the current live value of a variable in the actual stack
         *   frame, use frame[name], where 'frame' is the StackFrameDesc object
         *   for the frame, and 'name' is a string giving the variable name.
         */
        getVars();

        /*
         *   Get the value of 'self' in this frame.
         */
        getSelf();

        /*
         *   Get the value of 'definingobj' in this frame.
         */
        getDefiningObj();

        /*
         *   Get the value of 'targetobj' in this frame.
         */
        getTargetObj();

        /*
         *   Get the value of 'targetprop' in this frame.
         */
        getTargetProp();

        /*
         *   Get the value of 'invokee' in this frame.
         */
        getInvokee();
    }

    /*
     *   A StackFrameRef is an internal object used with StackFrameDesc.  This
     *   type is used internally by the VM; user code can't create an instance of
     *   this class directly with 'new', and the class has no public methods.
     */
    intrinsic class StackFrameRef 'stack-frame-ref/030000'
    {
    }

TADS 3 Library Manual
Generated on 5/16/2013 from TADS version 3.1.3