|
Object Specification SheetPortable Object Compiler (c) 1997,98,99,2000. All Rights Reserved.
ObjectNone. (Object is the root class).
Class DescriptionObject is the superclass of all classes. Methods implemented here are inherited by all Objective C classes.
Indexed VariablesThe 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.
LimitsThe 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 typesFactory InitializationCreating, Copying and FreeingIdentity
ComparingResponding to MethodsObject TablesClass ManagementError Handling
Unknown MessagesMethod LookupMethod PerformingPrintingVersionArchivingAsciiFiler MethodsMethodsinitialize+initializeEvery 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+newFactory 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-copyShould 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-deepCopyShould 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-freeSets 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-releaseMessage that is automatically sent to object when using the reference count compiler option. Should free the memory for the instance, and returns nil.
self-selfMethod that does nothing, except for returning self.
yourself-yourselfMethod that does nothing, except for returning self.
class-classReturns the class object for the receiver's class. See also: + class
superclass-superclassReturns the superclass object for the receiver's class. For GNU compatibility. See also: + superclass
superClass-superClassSame as superclass. For Stepstone compatibility.
class+classTraditionally, the class of a class does NOT return the metaclass, but rather self (that, it, the class itself).
superclass+superclassFor GNU compatibility. Returns the superclass of this factory (which is another factory object), or nil for the root.
superClass+superClassSame as superclass, but for Stepstone compatibility. Returns the superclass of this factory (which is another factory object), or nil for the root.
name- (STR)nameReturns the name of the object; implemented by default to return the name of the object's class.
name+ (STR)nameReturns the name of the class.
findClass:-findClass:(STR)nameReturns the id of a Class name, if that class has been linked in this executable image, otherwise returns nil.
findSel:- (SEL)findSel:(STR)nameReturns the selector (uniqued string) of the string name. Returns NULL if name is not in the selector table.
selOfSTR:- (SEL)selOfSTR:(STR)nameSame as findSel:, but raises an exception if the selector is not found.
idOfSTR:-idOfSTR:(STR)aClassNameSame as findClass: , but raises an exception if the class is not found.
hash- (unsigned)hashReturns 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:anObjectShould return YES if the receiver is equal to anObject. By default, compares the pointer addresses of the two objects.
str- (STR)strReturns 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)sizeReturns 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:anObjectTests whether two class objects are the same.
isSame:- (BOOL)isSame:anObjectReturns YES if the pointer addresses of the two objects are equal.
notEqual:- (BOOL)notEqual:anObjectWhether isEqual: returns NO.
notSame:- (BOOL)notSame:anObjectWhether isSame: returns NO.
compare:- (int)compare:anObjectShould 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.
invertCompare:- (int)invertCompare:anObjectThis method simply inverts the return value of compare:.
respondsTo:- (BOOL)respondsTo:(SEL)aSelectorTest 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:aClassReturns YES if the receiver is an instance of aClass, but NO if it's an instance of some subclass of aClass.
isKindOf:- (BOOL)isKindOf:aClassReturns 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:
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).[ foo isKindOf:(id) [Classname class] ]; See also: +inheritsFrom:, -isMemberOf:
someInstance+someInstanceReturns 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-nextInstanceReturns 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:otherSwaps 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+subclassesReturns 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:superClassThe 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.
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.+ initialize { [self poseAs:[Set self]]; return self; } When performing a poseAs:, the following rules must be followed:
Implementation details:
addMethodsTo:+addMethodsTo:superClassThe 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.
subclass:+subclass:(STR)nameMethod to dynamically subclass a class. Returns a new class object, which is still unregistered. With the methods load and unload, one can add or remove the class to the runtime, such that methods like findClass: will also return this new class. Note: Portable Object Compiler only.
subclass:::+subclass:(STR)name:(int)ivars:(int)cvarsMethod to dynamically subclass a class. Returns a new class object, which is still unregistered. With the methods load and unload, one can add or remove the class to the runtime, such that methods like findClass: will also return this new class. Note: Portable Object Compiler only.
load+loadThis method adds a dynamically created class to the runtime. The class will appear to methods such as findClass: or findSel: (for any selectors of methods of the class). Note: Portable Object Compiler only.
unload+unloadThis method removes a dynamically created class from the runtime. The class will appear to be unavailable to methods such as findClass:, after removing the class by an unload message. Note: Portable Object Compiler only.
inheritsFrom:+ (BOOL)inheritsFrom:aClassReturns YES if the receiving class is a subclass (direct or not) from aClass. Returns NO if the receiver is aClass itself, e.g. :
Note: For compatibility with Squeak.- (BOOL)isKindOf:c { return (isa==c) || [isa inheritsFrom:aClass]; }
isSubclassOf:+ (BOOL)isSubclassOf:aClassEquivalent to inheritsFrom:.
subclassResponsibility-subclassResponsibilityUsed in classes to indicate that the functionality is assumed to be implemented by a subclass, as in:
If the subclass does not implement the method, then an error message is generated.- foo { [self subclassResponsibility]; }
subclassResponsibility:-subclassResponsibility:(SEL)aSelectorFor Stepstone compatibility.
notImplemented-notImplementedMethod to indicate that a method is temporarily not implemented :
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.-foo { [self notImplemented]; }
notImplemented:-notImplemented:(SEL)aSelectorFor Stepstone compatibility.
shouldNotImplement-shouldNotImplementThis 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) :
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.+new { [self shouldNotImplement]; } +foo:aBar { self = [super new];bar = aBar; return self; }
shouldNotImplement:-shouldNotImplement:(SEL)aSelectorMethod for Stepstone compatibility.
shouldNotImplement:from:-shouldNotImplement:(SEL)aSelectorfrom:superClassMethod 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:messageThis 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)aSelectorAutomatically 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:aMessageThis 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,
which means that code that was overriding doesNotRecognize: to do forwarding of (unary) messages can continue to work.[self doesNotRecognize:[aMessage selector]]; 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)aSelectorReturns 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) :
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.((int (*) (id,id,BOOL))[object methodFor:selector])(object,arg,flag);
instanceMethodFor:+ (IMP)instanceMethodFor:(SEL)aSelectorReturns 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)aSelectorReturns the value that would result when sending aSelector to the receiver.
perform:with:-perform:(SEL)aSelectorwith:anObjectReturns the value that would result when sending aSelector to the receiver with a single argument anObject. The following are equivalent :
and[aReceiver perform:@selector(do:) with:anObject];
[aReceiver do:anObject]; perform:with:with:-perform:(SEL)aSelectorwith:anObjectwith:otherObjectReturns the value that would result when sending aSelector to the receiver with arguments anObject and otherObject.
perform:with:with:with:-perform:(SEL)aSelectorwith:anObjectwith:otherObjectwith:thirdObjReturns the value that would result when sending aSelector to the receiver with arguments anObject and otherObject.
meaning that if you implement printOn:, then this method will work.return [self printOn:stdout];
printLine-printLinePrints the object (in the sense of print) and then a newline.
show-showDisplays 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)anIODShould 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)objcrtRevisionReturns the version string of the runtime being used.
readFrom:+readFrom:(STR)aFileNameActivates 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
will work, ie. the receiver doesn't need to be OrdCltn. Returns nil on failure.id myCollection = [Object readFrom:"foo"];
storeOn:- (BOOL)storeOn:(STR)aFileNameStores 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:aFilerWrites 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:aFilerCreates 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:aFilerReads 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 *)valuetype:(char)typeDescMethod to be implemented by Filer class.
fileIn:type:-fileIn:(void *)valuetype:(char)typeDescMethod to be implemented by Filer class.
awake-awakeThis 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:aFilerAllows 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.
|