Up

NSObject class reference

Authors

Andrew Kachites McCallum (mccallum@gnu.ai.mit.edu)

Version: 1.188

Date: 2003/09/10 08:34:24

Copyright: (C) 1995, 1996, 1998 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the NSObject class
  2. Software documentation for the NSObject(GNU) category
  3. Software documentation for the NSObject(GSCategories) informal protocol
  4. Software documentation for the NSObject(NEXTSTEP) category
  5. Software documentation for the NSObject(TimedPerformers) informal protocol
  6. Software documentation for the GCFinalization protocol
  7. Software documentation for the NSCoding protocol
  8. Software documentation for the NSCopying protocol
  9. Software documentation for the NSMutableCopying protocol
  10. Software documentation for the NSObject protocol

Software documentation for the NSObject class

NSObject

Declared in:
Foundation/NSObject.h
Conforms to:
NSObject
Standards:

NSObject is the root class (a root class is a class with no superclass) of the gnustep base library class hierarchy, so all classes normally inherit from NSObject. There is an exception though: NSProxy (which is used for remote messaging) does not inherit from NSObject.

Unless you are really sure of what you are doing, all your own classes should inherit (directly or indirectly) from NSObject (or in special cases from NSProxy). NSObject provides the basic common functionality shared by all gnustep classes and objects.

The essential methods which must be implemented by all classes for their instances to be usable within gnustep are declared in a separate protocol, which is the NSObject protocol. Both NSObject and NSProxy conform to this protocol, which means all objects in a gnustep application will conform to this protocol (btw, if you don't find a method of NSObject you are looking for in this documentation, make sure you also look into the documentation for the NSObject protocol).

Theoretically, in special cases you might need to implement a new root class. If you do, you need to make sure that your root class conforms (at least) to the NSObject protocol, otherwise it will not interact correctly with the gnustep framework. Said that, I must note that I have never seen a case in which a new root class is needed.

NSObject is a root class, which implies that instance methods of NSObject are treated in a special way by the Objective-C runtime. This is an exception to the normal way messaging works with class and instance methods: if the Objective-C runtime can't find a class method for a class object, as a last resort it looks for an instance method of the root class with the same name, and executes it if it finds it. This means that instance methods of the root class (such as NSObject) can be performed by class objects which inherit from that root class ! This can only happen if the class doesn't have a class method with the same name, otherwise that method - of course - takes the precedence. Because of this exception, NSObject 's instance methods are written in such a way that they work both on NSObject 's instances and on class objects.

Method summary

alloc

+ (id) alloc;

Allocates a new instance of the receiver from the default zone, by invoking +allocWithZone: with NSDefaultMallocZone() as the zone argument.
Returns the created instance.


allocWithZone:

+ (id) allocWithZone: (NSZone*)z;

This is the basic method to create a new instance. It allocates a new instance of the receiver from the specified memory zone.

Memory for an instance of the receiver is allocated; a pointer to this newly created instance is returned. All instance variables are set to 0 except the isa pointer which is set to point to the object class. No initialization of the instance is performed: it is your responsibility to initialize the instance by calling an appropriate init method. If you are not using the garbage collector, it is also your responsibility to make sure the returned instance is destroyed when you finish using it, by calling the release method to destroy the instance directly, or by using autorelease and autorelease pools.

You do not normally need to override this method in subclasses, unless you are implementing a class which for some reasons silently allocates instances of another class (this is typically needed to implement class clusters and similar design schemes).

If you have turned on debugging of object allocation (by calling the GSDebugAllocationActive function), this method will also update the various debugging counts and monitors of allocated objects, which you can access using the GSDebugAllocation... functions.


class

+ (Class) class;

Returns the receiver.


description

+ (NSString*) description;

Returns a string describing the receiving class. The default implementation gives the name of the class by calling NSStringFromClass() .


initialize

+ (void) initialize;

Description forthcoming.


instanceMethodForSelector:

+ (IMP) instanceMethodForSelector: (SEL)aSelector;

Returns a pointer to the C function implementing the method used to respond to messages with aSelector by instances of the receiving class.
Raises NSInvalidArgumentException if given a null selector.


instanceMethodSignatureForSelector:

+ (NSMethodSignature*) instanceMethodSignatureForSelector: (SEL)aSelector;

Returns a pointer to the C function implementing the method used to respond to messages with aSelector whihc are sent to instances of the receiving class.
Raises NSInvalidArgumentException if given a null selector.


instancesRespondToSelector:

+ (BOOL) instancesRespondToSelector: (SEL)aSelector;

Returns a flag to say if instances of the receiver class will respond to the specified selector. This ignores situations where a subclass implements -forwardInvocation: to respond to selectors not normally handled... in these cases the subclass may override this method to handle it.
If given a null selector, raises NSInvalidArgumentException when in MacOS-X compatibility more, or returns NO otherwise.


isSubclassOfClass:

+ (BOOL) isSubclassOfClass: (Class)aClass;

Returns YES if the receiver is aClass or a subclass of aClass.


new

+ (id) new;

This method is a short-hand for alloc followed by init, that is,

NSObject *object = [NSObject new];

is exactly the same as

NSObject *object = [[NSObject alloc] init];

This is a general convention: all new... methods are supposed to return a newly allocated and initialized instance, as would be generated by an alloc method followed by a corresponding init... method. Please note that if you are not using a garbage collector, this means that instances generated by the new... methods are not autoreleased, that is, you are responsible for releasing (autoreleasing) the instances yourself. So when you use new you typically do something like:

NSMutableArray *array = AUTORELEASE ([NSMutableArray new]);

You do not normally need to override new in subclasses, because if you override init (and optionally allocWithZone: if you really need), new will automatically use your subclass methods.

You might need instead to define new new... methods specific to your subclass to match any init... specific to your subclass. For example, if your subclass defines an instance method

initWithName:

it might be handy for you to have a class method

newWithName:

which combines alloc and initWithName:. You would implement it as follows:

+ (id) newWithName: (NSString *)aName {return [[self alloc] initWithName: aName];}


poseAsClass:

+ (void) poseAsClass: (Class)aClassObject;

Sets up the ObjC runtime so that the receiver is used wherever code calls for aClassObject to be used.


requiresTypedMemory

+ (BOOL) requiresTypedMemory;

Description forthcoming.


setVersion:

+ (id) setVersion: (int)aVersion;

Sets the version number of the receiving class.


superclass

+ (Class) superclass;

Returns the super class from which the recevier was derived.


version

+ (int) version;

Returns the version number of the receiving class.


autorelease

- (id) autorelease;

Adds the receiver to the current autorelease pool, so that it will be sent a -release message when the pool is destroyed.
Returns the receiver.
In GNUstep, the [NSObject +enableDoubleReleaseCheck:] method may be used to turn on checking for ratain/release errors in this method.


awakeAfterUsingCoder:

- (id) awakeAfterUsingCoder: (NSCoder*)aDecoder;

Called after the receiver has been created by decoding some sort of archive. Returns self. Subclasses may override this to perform some special initialisation upon being decoded.


class

- (Class) class;

Returns the class of which the receiver is an instance.
The default implementation returns the private isa instance variable of NSObject, which is used to store a pointer to the objects class.
NB. When NSZombie is enabled (see NSDebug.h) this pointer is changed upon object deallocation.


classForArchiver

- (Class) classForArchiver;

Description forthcoming.


classForCoder

- (Class) classForCoder;

Description forthcoming.


classForPortCoder

- (Class) classForPortCoder;

Description forthcoming.


className

- (NSString*) className;

Returns the name of the class of the receiving object by using the NSStringFromClass() function.
This is a MacOS-X addition for apple scripting, which is also generally useful.


conformsToProtocol:

- (BOOL) conformsToProtocol: (Protocol*)aProtocol;

Returns a flag to say whether the class of the receiver conforms to aProtocol.


copy

- (id) copy;

Creates and returns a copy of the reciever by calling -copyWithZone: passing NSDefaultMallocZone()


dealloc

- (void) dealloc;

Deallocates the receiver by calling NSDeallocateObject() with self as the argument.

You should normally call the superclass implementation of this method when you override it in a subclass, or the memory occupied by your object will not be released.

NSObject 's implementation of this method destroys the receiver, by returning the memory allocated to the receiver to the system. After this method has been called on an instance, you must not refer the instance in any way, because it does not exist any longer. If you do, it is a bug and your program might even crash with a segmentation fault.

If you have turned on the debugging facilities for instance allocation, NSObject 's implementation of this method will also update the various counts and monitors of allocated instances (see the GSDebugAllocation... functions for more info).

Normally you are supposed to manage the memory taken by objects by using the high level interface provided by the retain, release and autorelease methods (or better by the corresponding macros RETAIN, RELEASE and AUTORELEASE), and by autorelease pools and such; whenever the release/autorelease mechanism determines that an object is no longer needed (which happens when its retain count reaches 0), it will call the dealloc method to actually deallocate the object. This means that normally, you should not need to call dealloc directly as the gnustep base library automatically calls it for you when the retain count of an object reaches 0.

Because the dealloc method will be called when an instance is being destroyed, if instances of your subclass use objects or resources (as it happens for most useful classes), you must override dealloc in subclasses to release all objects and resources which are used by the instance, otherwise these objects and resources would be leaked. In the subclass implementation, you should first release all your subclass specific objects and resources, and then invoke super's implementation (which will do the same, and so on up in the class hierarchy to NSObject 's implementation, which finally destroys the object). Here is an example of the implementation of dealloc for a subclass whose instances have a single instance variable name which needs to be released when an instance is deallocated:

- (void) dealloc {RELEASE (name); [super dealloc];}

dealloc might contain code to release not only objects, but also other resources, such as open files, network connections, raw memory allocated in other ways, etc.

If you have allocated the memory using a non-standard mechanism, you will not call the superclass (NSObject) implementation of the method as you will need to handle the deallocation specially.
In some circumstances, an object may wish to prevent itsself from being deallocated, it can do this simply be refraining from calling the superclass implementation.


description

- (NSString*) description;

Returns a string describing the receiver. The default implementation gives the class and memory location of the receiver.


doesNotRecognizeSelector:

- (void) doesNotRecognizeSelector: (SEL)aSelector;

Raises an invalid argument exception providing infomration about the receivers inability to handle aSelector.


forwardInvocation:

- (void) forwardInvocation: (NSInvocation*)anInvocation;

This method is called automatically to handle a message sent to the receiver for which the receivers class has no method.
The default implemnentation calls -doesNotRecognizeSelector:


hash

- (unsigned) hash;

Returns the hash of the receiver. Subclasses should ensure that their implementations of this method obey the rule that if the -isEqual: method returns YES for two instances of the class, the -hash method returns the same value fro both instances.
The default implementation returns the address of the instance.


init

- (id) init;

Initialises the receiver... the NSObject implementation simply returns self.


isEqual:

- (BOOL) isEqual: (id)anObject;

Tests anObject and the receiver for equality. The default implementation considers two objects to be equal only if they are the same object (ie occupy the same memory location).
If a subclass overrides this method, it should also override the -hash method so that if two objects are equal they both have the same hash.


isKindOfClass:

- (BOOL) isKindOfClass: (Class)aClass;

Returns YES if the class of the receiver is either the same as aClass or is derived from (a subclass of) aClass.


isMemberOfClass:

- (BOOL) isMemberOfClass: (Class)aClass;

Returns YES if the class of the receiver is aClass


isProxy

- (BOOL) isProxy;

Returns a flag to differentiate between 'true' objects, and objects which are proxies for other objects (ie they forward messages to the other objects).
The default implementation returns NO.


methodForSelector:

- (IMP) methodForSelector: (SEL)aSelector;

Returns a pointer to the C function implementing the method used to respond to messages with aSelector.
Raises NSInvalidArgumentException if given a null selector.


methodSignatureForSelector:

- (NSMethodSignature*) methodSignatureForSelector: (SEL)aSelector;

Returns the method signature describing how the receiver would handle a message with aSelector.
Raises NSInvalidArgumentException if given a null selector.


mutableCopy

- (id) mutableCopy;

Creates and rturns a mutable copy of the receiver by calling -mutableCopyWithZone: passing NSDefaultMallocZone() .


performSelector:

- (id) performSelector: (SEL)aSelector;

Causes the receiver to execute the method implementation corresponding to aSelector and returns the result.
The method must be one which takes no arguments and returns an object.
Raises NSInvalidArgumentException if given a null selector.


performSelector:withObject:

- (id) performSelector: (SEL)aSelector withObject: (id)anObject;

Causes the receiver to execute the method implementation corresponding to aSelector and returns the result.
The method must be one which takes one argument and returns an object.
Raises NSInvalidArgumentException if given a null selector.


performSelector:withObject:withObject:

- (id) performSelector: (SEL)aSelector withObject: (id)object1 withObject: (id)object2;

Causes the receiver to execute the method implementation corresponding to aSelector and returns the result.
The method must be one which takes two arguments and returns an object.
Raises NSInvalidArgumentException if given a null selector.


release

- (void) release;

Decrements the retain count for the receiver if greater than zeron, otherwise calls the dealloc method instead.
The default implementation calls the NSDecrementExtraRefCountWasZero() function to test the extra reference count for the receiver (and decrement it if non-zero) - if the extra reference count is zero then the retain count is one, and the dealloc method is called.
In GNUstep, the [NSObject +enableDoubleReleaseCheck:] method may be used to turn on checking for ratain/release errors in this method.


replacementObjectForArchiver:

- (id) replacementObjectForArchiver: (NSArchiver*)anArchiver;

Description forthcoming.


replacementObjectForCoder:

- (id) replacementObjectForCoder: (NSCoder*)anEncoder;

Description forthcoming.


replacementObjectForPortCoder:

- (id) replacementObjectForPortCoder: (NSPortCoder*)aCoder;

Returns the actual object to be encoded for sending over the network on a Distributed Objects connection.
The default implementation returns self if the receiver is being sent bycopy and returns a proxy otherwise.
Subclasses may override this method to change this behavior, eg. to ensure that they are always copied.


respondsToSelector:

- (BOOL) respondsToSelector: (SEL)aSelector;

Returns a flag to say if the receiver will respond to the specified selector. This ignores situations where a subclass implements -forwardInvocation: to respond to selectors not normally handled... in these cases the subclass may override this method to handle it.
If given a null selector, raises NSInvalidArgumentException when in MacOS-X compatibility more, or returns NO otherwise.


retain

- (id) retain;

Increments the reference count and returns the receiver.
The default implementation does this by calling NSIncrementExtraRefCount()


retainCount

- (unsigned) retainCount;

Returns the reference count for the receiver. Each instance has an implicit reference count of 1, and has an 'extra refrence count' returned by the NSExtraRefCount() function, so the value returned by this method is always greater than zero.
By convention, objects which should (or can) never be deallocated return the maximum unsigned integer value.


self

- (id) self;

Returns the reciever.


superclass

- (Class) superclass;

Returns the super class from which the receviers class was derived.


zone

- (NSZone*) zone;

Returns the memory allocation zone in which the receiver is located.


Software documentation for the NSObject(GNU) category

NSObject(GNU)

Declared in:
Foundation/NSObject.h
Standards:

Description forthcoming.

Method summary

autoreleaseClass

+ (Class) autoreleaseClass;

returns the class used to autorelease objects.


enableDoubleReleaseCheck:

+ (void) enableDoubleReleaseCheck: (BOOL)enable;

Enables runtime checking of retain/release/autorelease operations.

Whenever either -autorelease or -release is called, the contents of any autorelease pools will be checked to see if there are more outstanding release operations than the objects retain count. In which case an exception is raised to say that the object is released too many times.

Beware, since this feature entails examining all active autorelease pools every time an object is released or autoreleased, it can cause a massive performance degradation... it should only be enabled for debugging.

When you are having memory allocation problems, it may make more sense to look at the memory allocation debugging functions documented in NSDebug.h, or use the NSZombie features.


setAutoreleaseClass:

+ (void) setAutoreleaseClass: (Class)aClass;

Called to change the class used for autoreleasing objects.


makeImmutableCopyOnFail:

- (id) makeImmutableCopyOnFail: (BOOL)force;

Transmutes the receiver into an immutable version of the same object and returns the result.
If the receiver is not a mutable object or cannot be simply transmuted, then this method either returns the receiver unchanged or, if the force flag is set to YES, returns an autoreleased copy of the receiver.
Mutable classes should override this default implementation.
This method is used in methods which are declared to return immutable objects (eg. an NSArray), but which create and build mutable ones internally.


read:

- (id) read: (TypedStream*)aStream;

Description forthcoming.


transmuteClassTo:

- (Class) transmuteClassTo: (Class)aClassObject;

Changes the class of the receiver (the 'isa' pointer) to be aClassObject, but only if the receiver is an instance of a subclass of aClassObject which has not added extra instance variables.
Returns zero on failure, or the old class on success.


write:

- (id) write: (TypedStream*)aStream;

Description forthcoming.


Software documentation for the NSObject(GSCategories) informal protocol

NSObject(GSCategories)

Declared in:
Foundation/NSObject.h
Standards:

Description forthcoming.

Method summary

compare:

- (NSComparisonResult) compare: (id)anObject;

Description forthcoming.


notImplemented:

- (id) notImplemented: (SEL)aSel;

Description forthcoming.


shouldNotImplement:

- (id) shouldNotImplement: (SEL)aSel;

Description forthcoming.


subclassResponsibility:

- (id) subclassResponsibility: (SEL)aSel;

Description forthcoming.


Software documentation for the NSObject(NEXTSTEP) category

NSObject(NEXTSTEP)

Declared in:
Foundation/NSObject.h
Standards:

Description forthcoming.

Method summary

error:,...

- (id) error: (const char*)aString,...;

Description forthcoming.


Software documentation for the NSObject(TimedPerformers) informal protocol

NSObject(TimedPerformers)

Declared in:
Foundation/NSObject.h
Standards:

Description forthcoming.

Method summary

cancelPreviousPerformRequestsWithTarget:

+ (void) cancelPreviousPerformRequestsWithTarget: (id)obj;

Description forthcoming.


cancelPreviousPerformRequestsWithTarget:selector:object:

+ (void) cancelPreviousPerformRequestsWithTarget: (id)obj selector: (SEL)s object: (id)arg;

Description forthcoming.


performSelector:withObject:afterDelay:

- (void) performSelector: (SEL)s withObject: (id)arg afterDelay: (NSTimeInterval)seconds;

Description forthcoming.


performSelector:withObject:afterDelay:inModes:

- (void) performSelector: (SEL)s withObject: (id)arg afterDelay: (NSTimeInterval)seconds inModes: (NSArray*)modes;

Description forthcoming.


Software documentation for the GCFinalization protocol

GCFinalization

Declared in:
Foundation/NSObject.h
Standards:

Description forthcoming.

Method summary

gcFinalize

- (void) gcFinalize;

Description forthcoming.


Software documentation for the NSCoding protocol

NSCoding

Declared in:
Foundation/NSObject.h
Standards:

This protocol must be adopted by any class wishing to support saving and restoring instances to an archive, or copying them to remote processes via the Distributed Objects mechanism.

Method summary

encodeWithCoder:

- (void) encodeWithCoder: (NSCoder*)aCoder;

Description forthcoming.


initWithCoder:

- (id) initWithCoder: (NSCoder*)aDecoder;

Description forthcoming.


Software documentation for the NSCopying protocol

NSCopying

Declared in:
Foundation/NSObject.h
Standards:

This protocol must be adopted by any class wishing to support copying - ie where instances of the class should be able to create new instances which are copies of the original and, where a class has mutable and immutable versions, where the copies are immutable.

Method summary

copyWithZone:

- (id) copyWithZone: (NSZone*)zone;

Called by [NSObject -copy] passing NSDefaultMallocZone() as zone.
This method returns a copy of the receiver and, where the receiver is a mutable variant of a class which has an immutable partner class, the object returned is an instance of that immutable class.
The new object is not autoreleased, and is considered to be 'owned' by the calling code... which is therefore responsible for releasing it.
In the case where the receiver is an instance of a container class, it is undefined whether contained objects are merely retained in the new copy, or are themselves copied, or whether some other mechanism entirely is used.


Software documentation for the NSMutableCopying protocol

NSMutableCopying

Declared in:
Foundation/NSObject.h
Standards:

This protocol must be adopted by any class wishing to support mutable copying - ie where instances of the class should be able to create mutable copies of themselves.

Method summary

mutableCopyWithZone:

- (id) mutableCopyWithZone: (NSZone*)zone;

Called by [NSObject -mutableCopy] passing NSDefaultMallocZone() as zone.
This method returns a copy of the receiver and, where the receiver is an immmutable variant of a class which has a mutable partner class, the object returned is an instance of that mutable class. The new object is not autoreleased, and is considered to be 'owned' by the calling code... which is therefore responsible for releasing it.
In the case where the receiver is an instance of a container class, it is undefined whether contained objects are merely retained in the new copy, or are themselves copied, or whether some other mechanism entirely is used.


Software documentation for the NSObject protocol

NSObject

Declared in:
Foundation/NSObject.h
Standards:

The NSObject protocol describes a minimal set of methods that all objects are expected to support. You should be able to send any of the messages listed in this protocol to an object, and be safe in assuming that the receiver can handle it.

Method summary

autorelease

- (id) autorelease;

See [NSObject -autorelease]


class

- (Class) class;

See [NSObject -class]


conformsToProtocol:

- (BOOL) conformsToProtocol: (Protocol*)aProtocol;

See [NSObject -conformsToProtocol:]


description

- (NSString*) description;

See [NSObject -description]


hash

- (unsigned) hash;

See [NSObject -hash]


isEqual:

- (BOOL) isEqual: (id)anObject;

See [NSObject -isEqual:]


isKindOfClass:

- (BOOL) isKindOfClass: (Class)aClass;

See [NSObject -isKindOfClass:]


isMemberOfClass:

- (BOOL) isMemberOfClass: (Class)aClass;

See [NSObject -isMemberOfClass:]


isProxy

- (BOOL) isProxy;

See [NSObject -isProxy]


performSelector:

- (id) performSelector: (SEL)aSelector;

See [NSObject -performSelector:]


performSelector:withObject:

- (id) performSelector: (SEL)aSelector withObject: (id)anObject;

See [NSObject -performSelector:withObject:]


performSelector:withObject:withObject:

- (id) performSelector: (SEL)aSelector withObject: (id)object1 withObject: (id)object2;

See [NSObject -performSelector:withObject:withObject:]


release

- (oneway void) release;

See [NSObject -release]


respondsToSelector:

- (BOOL) respondsToSelector: (SEL)aSelector;

See [NSObject -respondsToSelector:]


retain

- (id) retain;

See [NSObject -retain]


retainCount

- (unsigned) retainCount;

See [NSObject -retainCount]


self

- (id) self;

See [NSObject -self]


superclass

- (Class) superclass;

See [NSObject -superclass]


zone

- (NSZone*) zone;

See [NSObject -zone]



Up