mccallum@gnu.ai.mit.edu
)Version: 1.191
Date: 2003/12/01 06:55:40
Copyright: (C) 1995, 1996, 1998 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSObject.h
- Conforms to:
- NSObject
Standards:
- MacOS-X
- OpenStep
- GNUstep
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
Allocates a new instance of the receiver from the
default zone, by invoking
+allocWithZone:
with
NSDefaultMallocZone()
as the zone argument.
Returns the created
instance.
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.
Returns the receiver.
Returns a string describing the receiving class. The default implementation gives the name of the class by calling NSStringFromClass() .
Description forthcoming.
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.
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.
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.
Returns YES
if the receiver is
aClass or a subclass of aClass.
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];}
Sets up the ObjC runtime so that the receiver is used wherever code calls for aClassObject to be used.
Description forthcoming.
Sets the version number of the receiving class.
Returns the super class from which the recevier was derived.
Returns the version number of the receiving class.
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.
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.
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.
Description forthcoming.
Description forthcoming.
Description forthcoming.
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.
Returns a flag to say whether the class of the receiver conforms to aProtocol.
Creates and returns a copy of the reciever by calling -copyWithZone: passing NSDefaultMallocZone()
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.
Returns a string describing the receiver. The default implementation gives the class and memory location of the receiver.
Raises an invalid argument exception providing infomration about the receivers inability to handle aSelector.
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:
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.
Initialises the receiver... the NSObject implementation simply returns self.
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.
Returns YES
if the class of the
receiver is either the same as aClass
or is derived from (a subclass of) aClass.
Returns YES
if the class of the
receiver is aClass
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
.
Returns a pointer to the C function implementing
the method used to respond to messages with
aSelector.
Raises
NSInvalidArgumentException if
given a null selector.
Returns the method signature describing how the
receiver would handle a message with
aSelector.
Raises
NSInvalidArgumentException if
given a null selector.
Creates and rturns a mutable copy of the receiver by calling -mutableCopyWithZone: passing NSDefaultMallocZone() .
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.
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.
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.
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.
Description forthcoming.
Description forthcoming.
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.
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.
Increments the reference count and returns the
receiver.
The default implementation does
this by calling
NSIncrementExtraRefCount()
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.
Returns the reciever.
Returns the super class from which the receviers class was derived.
Returns the memory allocation zone in which the receiver is located.
- Declared in:
- Foundation/NSObject.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Description forthcoming.
Method summaryreturns the class used to autorelease objects.
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.
Called to change the class used for autoreleasing objects.
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.
Description forthcoming.
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.
Description forthcoming.
- Declared in:
- Foundation/NSObject.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Description forthcoming.
Method summaryDescription forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSObject.h
Standards:
- NotOpenStep
- NotMacOS-X
- GNUstep
Description forthcoming.
Method summaryDescription forthcoming.
- Declared in:
- Foundation/NSObject.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
Description forthcoming.
Method summaryDescription forthcoming.
Description forthcoming.
Description forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSObject.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
Description forthcoming.
Method summaryDescription forthcoming.
- Declared in:
- Foundation/NSObject.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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 summaryDescription forthcoming.
Description forthcoming.
- Declared in:
- Foundation/NSObject.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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
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.
- Declared in:
- Foundation/NSObject.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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
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.
- Declared in:
- Foundation/NSObject.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
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 summarySee [NSObject -conformsToProtocol:]
See [NSObject -hash]
See [NSObject -isKindOfClass:]
See [NSObject -isMemberOfClass:]
See [NSObject -performSelector:]
See [NSObject -performSelector:withObject:]
See [NSObject -performSelector:withObject:withObject:]
See [NSObject -respondsToSelector:]
See [NSObject -self]
See [NSObject -zone]