Stringclasssystype.h[356], reflect.t[283]

The native string type.

Modified in reflect.t[283]:
Modify the String intrinsic class to provide a to-symbol mapping

intrinsic class String :   Object

Superclass Tree   (in declaration order)

String
        Object

Subclass Tree  

(none)

Global Objects  

(none)

Summary of Properties  

(none)

Summary of Methods  

digestMD5  endsWith  find  findReplace  htmlify  length  mapToByteArray  sha256  specialsToHtml  specialsToText  splice  split  startsWith  substr  toLower  toUnicode  toUpper  unpackBytes  urlDecode  urlEncode  valToSymbol 

Inherited from Object :
getPropList  getPropParams  getSuperclassList  isClass  isTransient  ofKind  propDefined  propInherited  propType 

Properties  

(none)

Methods  

digestMD5 ( )systype.h[638]

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.

endsWith (str)systype.h[386]
determine if we end with the given string

find (str, index?)systype.h[371]
find a substring

findReplace (origStr, newStr, flags?, index?)systype.h[467]
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', and 'newStr' is the string to replace it with on each occurrence.

'newStr' can be a function (regular or anonymous) instead of a list. 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.

'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.

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.

htmlify (flags?)systype.h[380]
htmlify a string

length ( )systype.h[359]
get the length of the string

mapToByteArray (charset?)systype.h[404]
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 will be 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.directly to byte value. A byte can only hold values from 0 to 255, so a numeric overflow will occur if any character code is outside this range.

sha256 ( )systype.h[630]
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.

specialsToHtml (stateobj?)systype.h[560]
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.

specialsToText (stateobj?)systype.h[607]
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

splice (idx, del, ins?)systype.h[474]
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.

split (delim?, limit?)systype.h[504]
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.

startsWith (str)systype.h[383]
determine if we start with the given string

substr (start, len?)systype.h[362]
extract a substring

toLower ( )systype.h[368]
convert to lower case

toUnicode (idx?)systype.h[377]
convert to a list of Unicode character codes, or get the Unicode character code for the single character at the given index

toUpper ( )systype.h[365]
convert to upper case

unpackBytes (format)systype.h[672]
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.

urlDecode ( )systype.h[622]
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 '?'.

urlEncode ( )systype.h[614]
Encode a URL parameter string. Spaces are encoded as "+", and all other non-alphanumeric characters except - and _ are encoded as "%xx" sequences.

valToSymbol ( )OVERRIDDENreflect.t[284]
no description available

TADS 3 Library Manual
Generated on 12/22/2011 from TADS version 3.1.0