--- name: "objc_Object" section: "3" platform: "linux" package: "objc-poc" version: "3.1.3-2" release: "Debian 2.2 (Potato)" platforms: ["linux"] url: "https://new.carta.tech/objc_Object" --- # objc\_Object(3) ## Object None. (Object is the root class). ## Class Description **Object** is the superclass of all classes. Methods implemented here are inherited by all Objective C classes. ## Indexed Variables The Portable Object Compiler does not support indexed variables (variable sized objects). It is best to store data of variable size, by using a pointer to the data, instead of placing the data in the object itself. ## Limits The Portable Object Compiler stores the size of instances of subclasses of **Object** in a *short* C integer, so it's better to use a pointer to large blocks of data, as opposed to placing the data in the object itself (as an instance variable). The number of instance methods and class methods that a class can have, is also limited by the size of C *short* integer (depends on the target platform). ## Method types **Factory Initialization** \* initialize **Creating, Copying and Freeing** \* new\ \* copy\ \* deepCopy\ \* free\ \* release **Identity** \* self\ \* yourself\ \* class\ \* superclass\ \* superClass\ \* class\ \* superclass\ \* superClass\ \* name\ \* name\ \* findClass:\ \* findSel:\ \* selOfSTR:\ \* idOfSTR: **Comparing** \* hash\ \* isEqual:\ \* str\ \* size\ \* isEqual:\ \* isSame:\ \* notEqual:\ \* notSame:\ \* compare: **Responding to Methods** \* respondsTo:\ \* isMemberOf:\ \* isKindOf: **Object Tables** \* someInstance\ \* nextInstance\ \* become: **Class Management** \* subclasses\ \* poseAs:\ \* addMethodsTo:\ \* subclass:\ \* inheritsFrom: **Error Handling** \* subclassResponsibility\ \* subclassResponsibility:\ \* notImplemented\ \* notImplemented:\ \* shouldNotImplement\ \* shouldNotImplement:\ \* shouldNotImplement:from:\ \* error:\ \* halt: **Unknown Messages** \* doesNotRecognize:\ \* doesNotUnderstand: **Method Lookup** \* methodFor:\ \* instanceMethodFor: **Method Performing** \* perform:\ \* perform:with:\ \* perform:with:with:\ \* perform:with:with:with: **Printing** \* print\ \* print\ \* printLine\ \* show\ \* printOn: **Version** \* objcrtRevision **Archiving** \* readFrom:\ \* storeOn: **AsciiFiler Methods** \* fileOutOn:\ \* fileInFrom:\ \* fileInFrom:\ \* fileOut:type:\ \* fileIn:type:\ \* awake\ \* awakeFrom: ## Methods initialize \+ **initialize** Every class in the application, receives an **initialize** message when the program starts. By default this method doesn't do anything. It can be overridden to do class initialization. Note that all classes are guarantueed to receive **initialize** , before any other message is sent. Other runtimes differ with ours in this respect, that **initialize** is sometimes sent to a class, just before an instance of that particular class is being used (as opposed to all classes receiving **initialize** , before any instance receives a message). **Note:** In some runtimes, the equivalent functionality is called **+load** instead of **+initialize** . new \+ **new** Factory method to create and return a new instance of the class. The default implementation clears (zeroes) the memory for instance variables and initializes the *isa* pointer. On systems that allow to recover from a failed memory allocation call, **new** might raise an exception that can be handled with **ifOutOfMemory:** . The default handler for this exception aborts the process. copy \- **copy** Should return a copy of the object. The difference with **deepCopy** is, that this copy might share pointers etc. with the receiver of the message. By default, **copy** just makes a byte copy of the memory for instance variables. deepCopy \- **deepCopy** Should return a *deep copy* of the object. Usually this means a copy that doesn't share objects with the original object and that can be **free** 'ed independently. By default, **deepCopy** just makes a byte copy of the memory for instance variables. free \- **free** Sets the **isa** pointer for this instance to **nil** , frees the memory for the instance, and returns **nil** . When compiling with the -gc option, the memory for the instance is not being freed. The garbage collector takes cares of this. **Note:** This method is implemented as **shouldNotImplement** when using reference counted memory management. This is so that the user doesn't accidentally sends **free** messages that interfere with the reference counted memory management. release \- **release** Message that is automatically sent to object when using the reference count compiler option. Should free the memory for the instance, and returns **nil** . self \- **self** Method that does nothing, except for returning **self** . yourself \- **yourself** Method that does nothing, except for returning **self** . class \- **class** Returns the class object for the receiver's class. **See also:** \+ class superclass \- **superclass** Returns the superclass object for the receiver's class. For GNU compatibility. **See also:** \+ superclass superClass \- **superClass** Same as **superclass** . For Stepstone compatibility. class \+ **class** Traditionally, the *class* of a class does NOT return the metaclass, but rather **self** (that, it, the class itself). superclass \+ **superclass** For GNU compatibility. Returns the superclass of this factory (which is another factory object), or **nil** for the root. superClass \+ **superClass** Same as **superclass** , but for Stepstone compatibility. Returns the superclass of this factory (which is another factory object), or **nil** for the root. name \- ( STR ) **name** Returns the name of the object; implemented by default to return the name of the object's class. name \+ ( STR ) **name** Returns the name of the class. findClass: \- **findClass** :(STR) *name* Returns the id of a Class name, if that class has been linked in this executable image, otherwise returns **nil** . findSel: \- ( SEL ) **findSel** :(STR) *name* Returns the selector (uniqued string) of the string *name* . Returns NULL if *name* is not in the selector table. selOfSTR: \- ( SEL ) **selOfSTR** :(STR) *name* Same as **findSel:** , but raises an exception if the selector is not found. idOfSTR: \- **idOfSTR** :(STR) *aClassName* Same as **findClass:** , but raises an exception if the class is not found. hash \- ( unsigned ) **hash** Returns a small integer value derived from the object, that should be equal for two objects for which **isEqual:** returns YES. By default, returns the pointer address of the object as an unsigned integer. isEqual: \- ( BOOL ) **isEqual** : *anObject* Should return YES if the receiver is equal to *anObject* . By default, compares the pointer addresses of the two objects. str \- ( STR ) **str** Returns the name of the object; implemented by default to return the name of the object's class. The String subclass overrides this method to return its contents. The method **isEqual:** of the String class is implemented in terms of **str** , and String instances can therefore be compared with arbitrary objects. size \- ( unsigned ) **size** Returns the number of other objects that this object contains. Returns 0 by default, but the Collection subclasses override this method to return the size of their contents. isEqual: \+ ( BOOL ) **isEqual** : *anObject* Tests whether two class objects are the same. isSame: \- ( BOOL ) **isSame** : *anObject* Returns YES if the pointer addresses of the two objects are equal. notEqual: \- ( BOOL ) **notEqual** : *anObject* Whether **isEqual:** returns NO. notSame: \- ( BOOL ) **notSame** : *anObject* Whether **isSame:** returns NO. compare: \- ( int ) **compare** : *anObject* Should return an integer which is less than, equal to, or greater than zero, if the receiver is less than, equal to, or greater than *anObject* . The return value is called the method's comparison value. respondsTo: \- ( BOOL ) **respondsTo** :(SEL) *aSelector* Test whether the class implements a certain method. Returns YES if the class itself, or one of its superclasses, implements the method, otherwise NO. The method does *not* generate an error if the class does not implement the method. isMemberOf: \- ( BOOL ) **isMemberOf** : *aClass* Returns YES if the receiver is an instance of *aClass* , but NO if it's an instance of some subclass of *aClass* . isKindOf: \- ( BOOL ) **isKindOf** : *aClass* Returns YES if the receiver is an instance of *aClass* or an instance from some subclass of *aClass* . If the receiver is a class, returns YES if *aClass* is the rootclass ( **Object** ) and NO otherwise. **Note:** For portability, this method always needs to be used as follows: \[ foo isKindOf:(id) \[Classname class\] \];\ The reason is that some compilers do not allow class names as expressions, so the class must be obtained by sending a **class** message. In addition, some compilers have a **isKindOf:** method that takes an *id* argument, but the return value of **self** or **class** can be SHR for those compilers. Therefore, it's necessary to cast the return value to *id* (to avoid compiler warnings). **See also:** \+inheritsFrom:, -isMemberOf: someInstance \+ **someInstance** Returns the first instance in an enumeration of instances, or **nil** when there is no instance. **Note:** Works only when using the -otb compiler switch. nextInstance \- **nextInstance** Returns the next instance in the enumeration of instances of a class, or **nil** when there are no more instances. **Note:** Works only when using the -otb compiler switch. become: \- **become** : *other* Swaps pointers for the receiver of the message and the argument. All variables that used to point to the receiver, now point to the argument, and vice-versa. **Note:** Works only when using the -otb compiler switch. subclasses \+ **subclasses** Returns a **OrdCltn** of direct subclasses of the class that receives the message. If the class has no subclasses, then this method returns an empty **OrdCltn** (not **nil** ). The class itself is not considered subclass of itself. **Note:** This method is Portable Object Compiler only. **See also:** \+class, +superclass, +inheritsFrom: poseAs: \+ **poseAs** : *superClass* The **poseAs:** method permits to modify a supplied *superClass* (for which, for example, no source code is available) by substituting a direct subclass of *superClass* . It is normally used inside **+initialize** , but the Portable Object Compiler allows **poseAs:** to be used anywhere in the program. \+ initialize { \[self poseAs:\[Set self\]\]; return self; }\ The example shows how the **initialize** of some subclass, called for example **SubSet** , can substitute **SubSet** for **Set** . Methods defined in **SubSet** override those defined in the superclass, and new methods from **SubSet** , will appear to have come from the **Set** class. When performing a **poseAs:** , the following rules must be followed: \* The posing class must be an immediate subclass of the class that it is to impersonate.\ \* The posing class may define or redefine only methods.\ \* Specifically, the posing class may NOT add any new instance variables. The Portable Object Compiler implementation of **poseAs:** differs from some other runtimes, since it allows **poseAs:** to happen, even after messages have been sent to instances of posing or impersonated class. Implementation details: \* poseAs: patches the superclass pointer of all subclasses (other than the posing class) that inherit from *superClass*\ \* poseAs: changes the name of *superClass* by prefixing the name with \_%\ \* findClass: for the name of *superClass* will return the posing subclass. **Note:** All Objective-C compilers provide this functionality (sometimes with restrictions on when the method can be called) addMethodsTo: \+ **addMethodsTo** : *superClass* The **addMethodsTo:** method permits to modify a supplied *superClass* (for which, for example, no source code is available) by adding the (instance and factory) methods of a direct subclass, to *superClass* . It is normally used inside **+initialize** , but the Portable Object Compiler allows **addMethodsTo:** to be used anywhere in the program. The same restrictions apply as for **poseAs:** : the subclass needs to be a direct subclass of *superClass* and it may not add instance variables. However, unlike **poseAs:** , the subclass will not be substituted for the *superClass* for purposes as **fileIn:** etc. Also, (unlike **poseAs:** ) when the subclass adds a method to the *superClass* that was overridden from the *superClass* , then this method will not replace the method of the *superClass* . **Note:** Portable Object Compiler only. subclass: \+ **subclass** :(STR) *name* Method to dynamically subclass a class. Returns a new class object, registered under the name *name* , as subclass of *self* . Methods like **findClass:** will also return this new class. **Note:** Portable Object Compiler only. inheritsFrom: \+ ( BOOL ) **inheritsFrom** : *aClass* Returns YES if the receiving class is a subclass (direct or not) from *aClass* . Returns NO if the receiver is *aClass* itself, e.g. : \- (BOOL)isKindOf:c { return (isa==c) \|\| \[isa inheritsFrom:aClass\]; }\ **Note:** For compatibility with Squeak. subclassResponsibility \- **subclassResponsibility** Used in classes to indicate that the functionality is assumed to be implemented by a subclass, as in: \- foo { \[self subclassResponsibility\]; }\ If the subclass does not implement the method, then an error message is generated. subclassResponsibility: \- **subclassResponsibility** :(SEL) *aSelector* For Stepstone compatibility. notImplemented \- **notImplemented** Method to indicate that a method is temporarily not implemented : \-foo { \[self notImplemented\]; }\ When designing a class, the method **notImplemented** can be used to implement stubs for the methods that make up the class. When the design phase is finished, the actual implementation can begin. If later, by accident, not all functionality is properly implemented, the method **notImplemented** will help finding this. notImplemented: \- **notImplemented** :(SEL) *aSelector* For Stepstone compatibility. shouldNotImplement \- **shouldNotImplement** This is the opposite of **subclassResponsibility** and a stronger form of **notImplemented** : **shouldNotImplement** should be used, when the class is not supposed to implement some method, i.e. when the method is not appropriate for the class and its subclasses. An abstract superclass, called *MyClass* for example, can use this method to indicate that subclasses should not send (or be sent) a **new** message, but that they are supposed to send some other method (such as **foo:** perhaps) : \+new { \[self shouldNotImplement\]; }\ \+foo:aBar { self = \[super new\];bar = aBar; return self; }\ This announces that **new** , which would otherwise have been inherited from the root class, is not an appropriate way to create an instance of a subclass of MyClass. shouldNotImplement: \- **shouldNotImplement** :(SEL) *aSelector* Method for Stepstone compatibility. shouldNotImplement:from: \- **shouldNotImplement** :(SEL) *aSelector* **from** : *superClass* Method for Stepstone compatibility. error: \- **error** :(STR) *format,...* Generate an error message. Takes a format string in the style of the C library function *printf* , with a variable number of arguments. Returns **self** . This method is present in most runtimes, but it was reimplemented in the Portable Object Compiler, so that the error can be *caught* , using the Block instance method **ifError:** . Traditionally, the method **error:** simply aborts the process, and the default error handler in our implementation does the same thing. halt: \- **halt** : *message* This method is equivalent to the **error:** method but takes an object as argument. The halt method pops an error handler from the stack of handlers, as maintained by **ifError:** . The handler is evaluated with the message and the receiver of the **halt:** message, as arguments. If the handler returns, it is pushed again on the stack. If there were no handlers on the stack, the default error handler is used instead, as returned by **errorHandler** . **Note:** Portable Object Compiler specific doesNotRecognize: \- **doesNotRecognize** :(SEL) *aSelector* Automatically sent by the *runtime* when the class does not implement *aSelector* . **Note:** The Portable Object Compiler offers a generalization of this method, called **doesNotUnderstand:** . The **doesNotRecognize:** method is sent *via* **doesNotUnderstand:** and not directly by the messenger. **See also:** doesNotUnderstand: doesNotUnderstand: \- **doesNotUnderstand** : *aMessage* This method is sent by the messenger when a message is sent to an object, that is not implemented by that object. The default implementation is, \[self doesNotRecognize:\[aMessage selector\]\];\ which means that code that was overriding **doesNotRecognize:** to do forwarding of (unary) messages can continue to work. However, the new (Portable Object Compiler specific) **doesNotUnderstand:** method, together with the **Message** class, provides a way of forwarding messages with arbitrary return values and arguments. **See also:** Message Class methodFor: \- ( IMP ) **methodFor** :(SEL) *aSelector* Returns a function implementation pointer for *aSelector* . Returns a pointer to an error handling function if the object does not respond to *aSelector* . Use of this method for reasons of performance, is not encouraged, because by repeatedly using the resulting function pointer, one is bypassing (the benefits of) dynamic binding. A good use of **methodFor:** however, is, because this method is supported by various runtimes, to send a message in a runtime independent, portable way, without using runtime specific functions (such as \_imp(), \_msg(), objc\_msg\_Send() etc. which have, unlike **methodFor:** non-standard names) : ((int (\*) (id,id,BOOL))\[object methodFor:selector\])(object,arg,flag);\ The same thing can be achieved by using the \_imp() function immediately, but the above is preferred usage, since it will also work for NeXT, Stepstone and GNU. instanceMethodFor: \+ ( IMP ) **instanceMethodFor** :(SEL) *aSelector* Returns a function implementation pointer for *aSelector* . Returns a pointer to an error handling function if the object does not respond to *aSelector* . Use of this method is not encouraged, because by using the resulting function pointer, one is bypassing (the benefits of) dynamic binding. perform: \- **perform** :(SEL) *aSelector* Returns the value that would result when sending *aSelector* to the receiver. perform:with: \- **perform** :(SEL) *aSelector* **with** : *anObject* Returns the value that would result when sending *aSelector* to the receiver with a single argument *anObject* . The following are equivalent : \[aReceiver perform:@selector(do:) with:anObject\];\ and \[aReceiver do:anObject\];\ perform:with:with: \- **perform** :(SEL) *aSelector* **with** : *anObject* **with** : *otherObject* Returns the value that would result when sending *aSelector* to the receiver with arguments *anObject* and *otherObject* . perform:with:with:with: \- **perform** :(SEL) *aSelector* **with** : *anObject* **with** : *otherObject* **with** : *thirdObj* Returns the value that would result when sending *aSelector* to the receiver with arguments *anObject* and *otherObject* . print \- **print** Prints the object to the *stdout* and returns **self** . Implemented as, return \[self printOn:stdout\]; \ meaning that if you implement **printOn:** , then this method will work. print \+ **print** Factory method to print the name of the class to the *stdout* and to return **self** . printLine \- **printLine** Prints the object (in the sense of **print** ) and then a newline. show \- **show** Displays the object on the *stderr* , by using Filer code, and returns **self** . Because it is implemented in terms of Filer code, this method is completely unrelated to the **print** method, although that the goal in both cases is to print a symbolic representation of the object. This method is extremely useful for debugging. The compiler automatically implements Filer methods, so this method *dumps* instance variables of the object in a symbolic format, without the programmer having to implement debug/printing routines. Method for Stepstone compatibility. Used in Producer code. printOn: \- **printOn** :(IOD) *anIOD* Should print the object to *anIOD* , which is of type **IOD** (defined as an *input output device* , a **FILE** pointer, to be used with standard I/O). Should return the receiver. By default, the method prints nothing. This is the method to override in subclasses to make **print** , **printLine** etc. to work. objcrtRevision \+ ( STR ) **objcrtRevision** Returns the version string of the runtime being used. readFrom: \+ **readFrom** :(STR) *aFileName* Activates the object stored in the file *aFileName* . The object will in all respects be functional, as it was before being stored. Works by indirectly calling *fileIn()* . The class AsciiFiler must be linked into the application for this method to work. This message can be sent to any factory object without regard of the class of the object being read in. In other words, if file *foo* contains a saved instance of a **OrdCltn** , then id myCollection = \[Object readFrom:"foo"\];\ will work, ie. the receiver doesn't need to be **OrdCltn** . Returns **nil** on failure. storeOn: \- ( BOOL ) **storeOn** :(STR) *aFileName* Stores the receiver to a file named *aFileName* , in a format such that the object can then be activated later, using the **readFrom:** method. Works by indirectly calling the function *storeOn()* . The class AsciiFiler must be linked into the application for this method to work fileOutOn: \- **fileOutOn** : *aFiler* Writes the receiver on *aFiler* . This is the method that a subclass will override to do it own processing, if the default implementation, which automatically writes out all instance variables of type *id* , does not suffice. This method will be invoked twice by the Filer class, during archiving. fileInFrom: \+ **fileInFrom** : *aFiler* Creates a new instance of the class, files in the instance from *aFiler* (by sending the new object a **fileInFrom:** ) message, and returns the new object. fileInFrom: \- **fileInFrom** : *aFiler* Reads the receiver from *aFiler* . The default implementation automatically reads in instance variables of type *id* . This method must be overridden to match **fileOutFor:** , if that method was implemented by the subclass. One should realize that, at the time this method is invoked, not all objects are guarantueed to be in a usable state. This is only true once the filer starts sending **awakeFrom:** messages. fileOut:type: \- **fileOut** :(void \*) *value* **type** :(char) *typeDesc* Method to be implemented by Filer class. fileIn:type: \- **fileIn** :(void \*) *value* **type** :(char) *typeDesc* Method to be implemented by Filer class. awake \- **awake** This message is sent to every object when it is filed in, after all the objects it references are in a usable state. The default implementation simply returns self. awakeFrom: \- **awakeFrom** : *aFiler* Allows the receiver to do some cleanup work after an object has been filed in. It is a generalization of the old **-awake** method. The difference is that this method passes *aFiler* as an argument. The default implementation is to send the **awake** message.