String(3)

String

Inherits from:

Array

Class Description

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.

New instances are usually created via str: , which initializes the object to a copy of the argument (a C string). Another factory method is the sprintf: method which supports the options of the C library function, sprintf() .

It's possible to compare String instances using the methods compare: and 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.

You can randomly access the characters in a string object using the charAt: and charAt:put: methods. The latter method replaces the character at the indicated offset by a new character, and returns the old value.

Finally, using such methods as toLower , toUpper etc., instances can do various conversions on their contents.

Method types

Creation

Comparison

Interrogation

Concatenation

Format Conversions

Conversions

Printing

Archiving

Methods

new

Creates an instance whose value is set to the empty string.

new:

Creates an instance whose value is set to the empty string, can hold at least nChars without having to expand.

str:

Creates an instance whose value is set to a copy of aString . If aString is NULL, creates an instance whose value is set to the empty string.

chars:count:

Creates an instance whose value is set to a copy of the n first characters of aString , and NULL-terminates the copy of characters. The array of characters aString doesn't have to be NULL-terminated itself. If aString is NULL, the method creates an instance whose value is set to the empty string.

sprintf:

Returns a new instace initialized just as the standard C library sprintf() . See the documentation on sprintf() for the formats and variable declarations.

copy

Returns a copy of the receiver with its internal C string copied as well.

See also:

- strCopy

deepCopy

For this class, this method acts as copy .

free

Frees the receiver and its internal C string as well.

compare:

Compares the receiver's string to another instance of this class (or its subclasses). Comparison works by sending aStr a str message, and comparing the null terminated C strings. Returns the comparison value (0 if the strings are equal).

compareSTR:

Compares the receiver's string to aString . Returns the comparison value.

hash

Returns a hash value based upon the contents of the string held in the receiver.

dictCompare:

Compares the receiver's string to another instance of this class, or its subclasses, according to dictionary ordering , i.e., all characters other than letters and numbers are ignored and case is ignored. Returns the comparison value.

isEqual:

Returns YES if the value contained by aStr is equal to the contents of the receiver.

isEqualSTR:

Returns YES if the ordinary C string aString is equal to the contents of the receiver.

size

Returns the number of actual characters in the string, excluding the NULL terminator.

charAt:

Returns the character at anOffset or zero if anOffset is greater than the length of the C string.

charAt:put:

Replaces the character at anOffset with aChar and returns the old character which was in that location. Returns zero if anOffset is greater than the length of the C string.

strcat:

Concatenates the receiver's C string to aBuffer . No length checking is possible to ensure that aBuffer is large enough. Returns aBuffer .

concat:

Concatenates aString (any instance that responds to str ) to the end of the receiver. Returns self .

concatSTR:

Concatenates aString , an ordinary C string, to the end of the receiver. Returns self .

concatenateSTR:

Same as concatSTR. For Stepstone compatibility.

at:insert:count:

at:insert:

deleteFrom:to:

assignSTR:

Copies the C string aString into the receiver's string. Returns the receiver.

assignSTR:length:

Copies the C string aString into the receiver's string, truncating at nChars . Returns the receiver.

asDouble

Returns the double value of the C string, using the standard C function atof() .

asInt

Returns the integer value of the C string, using the standard C function atoi() .

asLong

Returns the long value of the C string, using the standard C function atol() .

asSTR:maxSize:

Copies the value of the object into aBuffer , truncating at aSize , and returns the receiver.

str

Returns a pointer to the NULL-terminated C string stored in the receiver.

strCopy

Returns a OC_MallocAtomic() 'ed copy of the NULL-terminated C string stored in the receiver. You are responsible for OC_Free() 'ing the pointer.

toLower

Converts the receiver string to lower case.

toUpper

Converts the receiver string to upper case.

printOn:

Prints the string to aFile without appending a newline. Returns the receiver.

fileOutOn:

Writes the string on aFiler . Returns the receiver.

fileInFrom:

Reads a string object from aFiler . Returns the receiver.