ObjStr Specification Sheet


ObjectPak Objective C Class Library

ObjStr

Inherits from:ObjPak

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 ObjStr 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

NextStep Archiving

Methods



new

+ new

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



str:

+ str :(STR) strValue

Creates an instance whose value is set to a copy of strValue. If strValue is NULL, 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). Returns the comparison value.



compareSTR:

- (int) compareSTR :(STR) strValue

Compares the receiver's string to strValue. 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) strValue

Returns YES if the ordinary C string strValue 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) anOffset put :(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.



concatSTR:

- concatSTR :(STR) strValue

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



assignSTR:

- assignSTR :(STR) strValue

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



assignSTR:length:

- assignSTR :(STR) strValue length :(unsigned) nChars

Copies the C string strValue 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) aBuffer maxSize :(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 malloc()'ed copy of the NULL-terminated C string stored in the receiver. You are responsible for free()'ing the pointer.



toLower

- toLower

Converts the receiver string to lower case.



toUpper

- toUpper

Converts the receiver string to upper case.



printToFile:

- printToFile :(FILE *) aFile

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



write:

- write :(NXTypedStream *) stream

Writes the string to stream. Returns the receiver.



read:

- read :(NXTypedStream *) stream

Reads a string object from stream. Returns the receiver.