--- name: "String" section: "3" platform: "linux" package: "objc-poc" version: "3.1.3-2" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/String" --- # 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** \* new\ \* new:\ \* str:\ \* chars:count:\ \* sprintf:\ \* copy\ \* deepCopy\ \* free **Comparison** \* compare:\ \* compareSTR:\ \* hash\ \* dictCompare:\ \* isEqual:\ \* isEqualSTR: **Interrogation** \* size\ \* 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. 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 \- ( 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: \- **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** 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.