{\rtf1\ansi{\fonttbl\f0\fnil Times-Roman;\f1\fswiss Helvetica;\f2\fmodern Courier;}\paperw12000\paperh8000\margl40\margr40
\pard\f0\fs24\cf0 Portable Object Compiler (c) 1997,98,99,2003.  All Rights Reserved.\fs16\
\
\
\
\
\
\
\f1\b\fs56\li2200 String\f0\b0\fs16\
\
\
\
\
\
\f0\fs28\li2200 {\b {\f1 Inherits from:}} Array\fs16\
\
\fs16\
\
\f1\b\fs36\li1400 Class Description\b0\f0\fs16\
\
\f0\fs28\li2200 Strings are used to hold conventional, NULL-terminated C strings of characters.  String objects can, unlike ordinary C strings, easily be added to collections or sets.  They are also very useful as keys in a dictionary object.\fs16\
\
\f0\fs28\li2200 New instances are usually created via {\f2 str:}, which initializes the object to a copy of the argument (a C string).  Another factory method is the {\f2 sprintf:} method which supports the options of the C library function, {\i sprintf()}.\fs16\
\
\f0\fs28\li2200 It's possible to compare {\b String} instances using the methods {\f2 compare:} and {\f2 dictCompare:}.  These methods return an integer which is less than, equal to, or greater than zero, if the receiver is less than, equal to, or greater than the argument object.\fs16\
\
\f0\fs28\li2200 You can randomly access the characters in a string object using the {\f2 charAt:} and {\f2 charAt:put:} methods.  The latter method replaces the character at the indicated offset by a new character, and returns the old value.\fs16\
\
\f0\fs28\li2200 Finally, using such methods as {\f2 toLower}, {\f2 toUpper} etc., instances can do various conversions on their contents.\fs16\
\
\fs16\
\
\f1\b\fs36\li1400 Method types\b0\f0\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Creation}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- new\
	- new:\
	- str:\
	- chars:count:\
	- sprintf:\
	- copy\
	- deepCopy\
	- free\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Comparison}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- compare:\
	- compareSTR:\
	- hash\
	- dictCompare:\
	- isEqual:\
	- isEqualSTR:\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Interrogation}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- size\
	- charAt:\
	- charAt:put:\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Concatenation}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- strcat:\
	- concat:\
	- concatSTR:\
	- concatenateSTR:\
	- at:insert:count:\
	- at:insert:\
	- deleteFrom:to:\
	- assignSTR:\
	- assignSTR:length:\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Format Conversions}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- asDouble\
	- asInt\
	- asLong\
	- asSTR:maxSize:\
	- str\
	- strCopy\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Conversions}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- toLower\
	- toUpper\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Printing}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- printOn:\
\pard\fs16\
\
\pard\tx2600\fs28\li2600\cf0
{\b Archiving}
\pard\tx6000\fs28\fi-3800\li6000\cf0
	- fileOutOn:\
	- fileInFrom:\
\pard\fs16\
\
\fs16\
\
\f1\b\fs36\li1400 Methods\b0\f0\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 new\f0\b0\
\f0\fs28\li2500 +{\b new}\fs16\
\
\f0\fs28\li2200 Creates an instance whose value is set to the empty string.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 new:\f0\b0\
\f0\fs28\li2500 +{\b new}:(unsigned){\i nChars}\fs16\
\
\f0\fs28\li2200 Creates an instance whose value is set to the empty string, can hold at least {\i nChars} without having to expand.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 str:\f0\b0\
\f0\fs28\li2500 +{\b str}:(STR){\i aString}\fs16\
\
\f0\fs28\li2200 Creates an instance whose value is set to a copy of {\i aString}.  If {\i aString} is NULL, creates an instance whose value is set to the empty string. \fs16\
\
\fs16\
\
\f1\b\fs28\li2200 chars:count:\f0\b0\
\f0\fs28\li2500 +{\b chars}:(STR){\i aString}{\b count}:(int){\i n}\fs16\
\
\f0\fs28\li2200 Creates an instance whose value is set to a copy of the {\i n} first characters of {\i aString}, and NULL-terminates the copy of characters.  The array of characters {\i aString} doesn't have to be NULL-terminated itself.  If {\i aString} is NULL, the method creates an instance whose value is set to the empty string. \fs16\
\
\fs16\
\
\f1\b\fs28\li2200 sprintf:\f0\b0\
\f0\fs28\li2500 +{\b sprintf}:(STR){\i format,...}\fs16\
\
\f0\fs28\li2200 Returns a new instace initialized just as the standard C library {\i sprintf()}.  See the documentation on {\i sprintf()} for the formats and variable declarations.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 copy\f0\b0\
\f0\fs28\li2500 -{\b copy}\fs16\
\
\f0\fs28\li2200 Returns a copy of the receiver with its internal C string copied as well.\fs16\
\
\f0\fs28\li2200 {\b {\f1 See also:}} - strCopy\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 deepCopy\f0\b0\
\f0\fs28\li2500 -{\b deepCopy}\fs16\
\
\f0\fs28\li2200 For this class, this method acts as {\f2 copy}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 free\f0\b0\
\f0\fs28\li2500 -{\b free}\fs16\
\
\f0\fs28\li2200 Frees the receiver and its internal C string as well.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 compare:\f0\b0\
\f0\fs28\li2500 - (int){\b compare}:{\i aStr}\fs16\
\
\f0\fs28\li2200 Compares the receiver's string to another instance of this class (or its subclasses).  Comparison works by sending {\i aStr} a {\f2 str} message, and comparing the null terminated C strings.  Returns the comparison value (0 if the strings are equal).\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 compareSTR:\f0\b0\
\f0\fs28\li2500 - (int){\b compareSTR}:(STR){\i aString}\fs16\
\
\f0\fs28\li2200 Compares the receiver's string to {\i aString}.  Returns the comparison value.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 hash\f0\b0\
\f0\fs28\li2500 - (unsigned){\b hash}\fs16\
\
\f0\fs28\li2200 Returns a hash value based upon the contents of the string held in the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 dictCompare:\f0\b0\
\f0\fs28\li2500 - (int){\b dictCompare}:{\i aStr}\fs16\
\
\f0\fs28\li2200 Compares the receiver's string to another instance of this class, or its subclasses, according to {\i dictionary ordering}, i.e., all characters other than letters and numbers are ignored and case is ignored.  Returns the comparison value.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 isEqual:\f0\b0\
\f0\fs28\li2500 - (BOOL){\b isEqual}:{\i aStr}\fs16\
\
\f0\fs28\li2200 Returns YES if the value contained by {\i aStr} is equal to the contents of the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 isEqualSTR:\f0\b0\
\f0\fs28\li2500 - (BOOL){\b isEqualSTR}:(STR){\i aString}\fs16\
\
\f0\fs28\li2200 Returns YES if the ordinary C string {\i aString} is equal to the contents of the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 size\f0\b0\
\f0\fs28\li2500 - (unsigned){\b size}\fs16\
\
\f0\fs28\li2200 Returns the number of actual characters in the string, excluding the NULL terminator.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 charAt:\f0\b0\
\f0\fs28\li2500 - (char){\b charAt}:(unsigned){\i anOffset}\fs16\
\
\f0\fs28\li2200 Returns the character at {\i anOffset} or {\b zero} if {\i anOffset} is greater than the length of the C string.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 charAt:put:\f0\b0\
\f0\fs28\li2500 - (char){\b charAt}:(unsigned){\i anOffset}{\b put}:(char){\i aChar}\fs16\
\
\f0\fs28\li2200 Replaces the character at {\i anOffset} with {\i aChar} and returns the old character which was in that location.  Returns {\b zero} if {\i anOffset} is greater than the length of the C string.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 strcat:\f0\b0\
\f0\fs28\li2500 - (STR){\b strcat}:(STR){\i aBuffer}\fs16\
\
\f0\fs28\li2200 Concatenates the receiver's C string to {\i aBuffer}.  No length checking is possible to ensure that {\i aBuffer} is large enough.  Returns {\i aBuffer}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 concat:\f0\b0\
\f0\fs28\li2500 -{\b concat}:{\i aString}\fs16\
\
\f0\fs28\li2200 Concatenates {\i aString} (any instance that responds to {\f2 str}) to the end of the receiver.  Returns {\b self}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 concatSTR:\f0\b0\
\f0\fs28\li2500 -{\b concatSTR}:(STR){\i aString}\fs16\
\
\f0\fs28\li2200 Concatenates {\i aString}, an ordinary C string, to the end of the receiver.  Returns {\b self}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 concatenateSTR:\f0\b0\
\f0\fs28\li2500 -{\b concatenateSTR}:(STR){\i aString}\fs16\
\
\f0\fs28\li2200 Same as concatSTR.  For Stepstone compatibility.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 at:insert:count:\f0\b0\
\f0\fs28\li2500 -{\b at}:(unsigned){\i anOffset}{\b insert}:(char*){\i aString}{\b count}:(int){\i n}\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 at:insert:\f0\b0\
\f0\fs28\li2500 -{\b at}:(unsigned){\i anOffset}{\b insert}:{\i aString}\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 deleteFrom:to:\f0\b0\
\f0\fs28\li2500 -{\b deleteFrom}:(unsigned){\i p}{\b to}:(unsigned){\i q}\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 assignSTR:\f0\b0\
\f0\fs28\li2500 -{\b assignSTR}:(STR){\i aString}\fs16\
\
\f0\fs28\li2200 Copies the C string {\i aString} into the receiver's string.  Returns the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 assignSTR:length:\f0\b0\
\f0\fs28\li2500 -{\b assignSTR}:(STR){\i aString}{\b length}:(unsigned){\i nChars}\fs16\
\
\f0\fs28\li2200 Copies the C string {\i aString} into the receiver's string, truncating at {\i nChars}.  Returns the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 asDouble\f0\b0\
\f0\fs28\li2500 - (double){\b asDouble}\fs16\
\
\f0\fs28\li2200 Returns the double value of the C string, using the standard C function {\b atof()}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 asInt\f0\b0\
\f0\fs28\li2500 - (int){\b asInt}\fs16\
\
\f0\fs28\li2200 Returns the integer value of the C string, using the standard C function {\b atoi()}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 asLong\f0\b0\
\f0\fs28\li2500 - (long){\b asLong}\fs16\
\
\f0\fs28\li2200 Returns the long value of the C string, using the standard C function {\b atol()}.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 asSTR:maxSize:\f0\b0\
\f0\fs28\li2500 -{\b asSTR}:(STR){\i aBuffer}{\b maxSize}:(int){\i aSize}\fs16\
\
\f0\fs28\li2200 Copies the value of the object into {\i aBuffer}, truncating at {\i aSize}, and returns the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 str\f0\b0\
\f0\fs28\li2500 - (STR){\b str}\fs16\
\
\f0\fs28\li2200 Returns a pointer to the NULL-terminated C string stored in the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 strCopy\f0\b0\
\f0\fs28\li2500 - (STR){\b strCopy}\fs16\
\
\f0\fs28\li2200 Returns a {\b OC_MallocAtomic()}'ed copy of the NULL-terminated C string stored in the receiver.  You are responsible for {\b OC_Free()}'ing the pointer.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 toLower\f0\b0\
\f0\fs28\li2500 -{\b toLower}\fs16\
\
\f0\fs28\li2200 Converts the receiver string to lower case.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 toUpper\f0\b0\
\f0\fs28\li2500 -{\b toUpper}\fs16\
\
\f0\fs28\li2200 Converts the receiver string to upper case.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 printOn:\f0\b0\
\f0\fs28\li2500 -{\b printOn}:(IOD){\i aFile}\fs16\
\
\f0\fs28\li2200 Prints the string to {\i aFile} without appending a newline.  Returns the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 fileOutOn:\f0\b0\
\f0\fs28\li2500 -{\b fileOutOn}:{\i aFiler}\fs16\
\
\f0\fs28\li2200 Writes the string on {\i aFiler}.  Returns the receiver.\fs16\
\
\fs16\
\
\f1\b\fs28\li2200 fileInFrom:\f0\b0\
\f0\fs28\li2500 -{\b fileInFrom}:{\i aFiler}\fs16\
\
\f0\fs28\li2200 Reads a string object from {\i aFiler}.  Returns the receiver.\fs16\
\
\fs16\
\
\
}