ocstring(3) UNIX System V (Apr 20, 1999) ocstring(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
* new
* new:
* str:
* chars:count:
* sprintf:
* copy
* deepCopy
* free
Comparison
* compare:
* compareSTR:
* hash
* dictCompare:
* isEqual:
* isEqualSTR:
Interrogation
* size
Page 1 (printed 6/28/99)
ocstring(3) UNIX System V (Apr 20, 1999) ocstring(3)
* charAt:
* charAt:put:
Concatenation
* strcat:
* concat:
* concatSTR:
* concatenateSTR:
* at:insert:count:
* at:insert:
* deleteFrom:to:
* assignSTR:
* assignSTR:length:
Format Conversions
* asDouble
* asInt
* asLong
* asSTR:maxSize:
* str
* strCopy
Conversions
* toLower
* toUpper
Printing
* printOn:
Archiving
* fileOutOn:
* fileInFrom:
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.
Page 2 (printed 6/28/99)
ocstring(3) UNIX System V (Apr 20, 1999) ocstring(3)
chars:count:
+ chars :(STR) aString count :(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
Page 3 (printed 6/28/99)
ocstring(3) UNIX System V (Apr 20, 1999) ocstring(3)
- ( 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) 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 .
concat:
Page 4 (printed 6/28/99)
ocstring(3) UNIX System V (Apr 20, 1999) ocstring(3)
- 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) anOffset insert :(char*) aString count
:(int) n
at:insert:
- at :(unsigned) anOffset insert : aString
deleteFrom:to:
- deleteFrom :(unsigned) p to :(unsigned) q
assignSTR:
- assignSTR :(STR) aString
Copies the C string aString into the receiver's string.
Returns the receiver.
assignSTR:length:
- assignSTR :(STR) aString length :(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
Page 5 (printed 6/28/99)
ocstring(3) UNIX System V (Apr 20, 1999) ocstring(3)
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 OC_MallocAtomic() 'ed copy of the NULL-terminated
C string stored in the receiver. You are responsible for
OC_Free() 'ing the pointer.
toLower
- toLower
Converts the receiver string to lower case.
toUpper
- toUpper
Converts the receiver string to upper case.
printOn:
- printOn :(IOD) aFile
Prints the string to aFile without appending a newline.
Returns the receiver.
fileOutOn:
- fileOutOn : aFiler
Writes the string on aFiler . Returns the receiver.
fileInFrom:
- fileInFrom : aFiler
Reads a string object from aFiler . Returns the receiver.
Page 6 (printed 6/28/99)