SCI Kernel Documentation/String Functions

From SCI Wiki
Jump to: navigation, search

Official SCI Documentation

Chapter: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | Index

String Functions

Author: Jeff Stephenson

Revision by: David Slayback


String Functions

Strings in Script are kept in arrays, with two characters per array element. Thus, when allocating space for a string of 40 characters, you only need to allocate an array of 20 elements.

(ReadNumber string)

Returns the integer value represented by string.

(Format stringPtr formatStr arg1 arg2 ...)

Formats a string in the storage space pointed to by stringPtr based on the format string formatStr and the arguments arg1, arg2, etc. Formatting commands embedded in formatStr consist of:


[justification]: if a minus sign is present, then the the string representing the argument is to be right justified (rather than the default of left justified) in its field.

[field_width]: number indicating the width of the field (in characters) in which the argument is to be printed.


d Print the corresponding argument as a signed decimal integer. u Print the corresponding argument as an unsigned decimal integer. x Print the corresponding argument as a hexadecimal number. c The corresponding argument is taken to be the ASCII representation of a character, which is printed. s The corresponding argument is assumed to be a pointer to a null terminated string, which is printed.

--- Examples:
If we have declared str somewhere as [str 40] (an 80 character string), then

(Format @str "x:%4d y:%-4d" 23 45) -> "x:23 y: 45"

(Format @str "This is a %s." "test") -> "This is a test."

(GetFarText module entryNumber buffer)

Gets text from a script text file and copies it into buffer. module points to the script #, and entryNumber points to the text number within that file to use.

(StrCmp str1 str2)

Compares the null-terminated strings pointed to by str1 and str2. Returns 0 if the strings are the same, 1 if str1 is greater than str2 (i.e. if the first character of str1 which does not match the corresponding character of str2 is greater than the character in str2), and -1 if str1 is less than str2.

(StrLen str)

Returns the number of characters in the null terminated string pointed to by str.

(StrCpy str1 str2)

Copies the string pointed to by str2 to the storage pointed to by str1. There had better be enough room in str1's storage to hold str2 -- there is no checking.

(StrCat str1 str2)

Concatenates str2 to the end of str1. Str1 had better have enough storage.

(StrEnd str)

Returns a pointer to the NULL which terminates str. This is useful for Formatting a string on the end of another, rather than Formatting to a temporary string and then using StrCat.

(StrAt string position [char])

StrAt returns the character at 'position' in 'string'. If the optional 'char' is specified, it replaces the character with 'char', returning the old contents. Use this rather than the mask-and-shift method since byte order in a word will vary between machines.




Table of Contents


< Previous: System Functions Next: Picture Functions >