ocstring Specification Sheet

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

Methods

new

+new

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

new:

+new:(unsigned)nChars

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

str:

+str:(STR)aString

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:

+chars:(STR)aStringcount:(int)n

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:

+sprintf:(STR)format,...

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

copy

-copy

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

See also: - strCopy

deepCopy

-deepCopy

For this class, this method acts as copy.

free

-free

Frees the receiver and its internal C string as well.

compare:

- (int)compare:aStr

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:

- (int)compareSTR:(STR)aString

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

hash

- (unsigned)hash

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

dictCompare:

- (int)dictCompare:aStr

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:

- (BOOL)isEqual:aStr

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

isEqualSTR:

- (BOOL)isEqualSTR:(STR)aString

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

size

- (unsigned)size

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

charAt:

- (char)charAt:(unsigned)anOffset

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

charAt:put:

- (char)charAt:(unsigned)anOffsetput:(char)aChar

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:

- (STR)strcat:(STR)aBuffer

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

concat:

-concat:aString

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

concatSTR:

-concatSTR:(STR)aString

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

concatenateSTR:

-concatenateSTR:(STR)aString

Same as concatSTR. For Stepstone compatibility.

at:insert:count:

-at:(unsigned)anOffsetinsert:(char*)aStringcount:(int)n

at:insert:

-at:(unsigned)anOffsetinsert:aString

deleteFrom:to:

-deleteFrom:(unsigned)pto:(unsigned)q

assignSTR:

-assignSTR:(STR)aString

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

assignSTR:length:

-assignSTR:(STR)aStringlength:(unsigned)nChars

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

asDouble

- (double)asDouble

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

asInt

- (int)asInt

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

asLong

- (long)asLong

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

asSTR:maxSize:

-asSTR:(STR)aBuffermaxSize:(int)aSize

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

str

- (STR)str

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

strCopy

- (STR)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.