Go to the previous, next section.

Object--Root of the NIH Class Library Inheritance Tree

SYNOPSIS

BASE CLASS

DERIVED CLASSES

RELATED CLASSES

DESCRIPTION

The abstract class Object is the most general NIH Library class. Almost all other NIH Library classes are ultimately derived from it and therefore inherit the functions described here. Some of these functions, such as className() or shallowCopy() are completely implemented by class Object and can be applied to objects of any class, particularly those added by the user, without additional code-writing. Other functions, such as isEqual() or printOn() are virtual functions that must be implemented by a class to be useful. Class Object implements these functions either to be pure virtual functions or to raise an NIHCL_DRVDCLASSRSP error if they are applied to objects of a class that does not provide its own implementation.

THE NIL OBJECT POINTER

static Object* const nil

Object::nil is a pointer to the sole instance of class Nil.

TESTING AN OBJECT'S CLASS OR SPECIES

static const Class* desc()

Returns a pointer to the class descriptor object for a class.

virtual const Class* isA() const = 0

Returns a pointer to an object's class descriptor.

virtual const Class* species() const

Returns a pointer to the class descriptor of the species class of an object.
Object::species() is implemented as { returnisA(); }.

const char* className() const

Returns a pointer to the name of an object's class.

bool isMemberOf(const Class& c) const

Returns YES if this object is an instance of the class whose class descriptor is c.

bool isSpecies(const Class& c) const

Returns YES if the species of this object is the class whose class descriptor is c.

bool isKindOf(const Class& c) const

Returns YES if this object is an instance of the class whose class descriptor is c, or is an instance of a class derived from this class.

void assertClass(const Class& expect) const

void assertSpecies(const Class& expect) const

These functions test the class (by calling isKindOf(expect)) or the species (by calling isSpecies(expect) of the object they are applied to. If the test fails, they call invalidClass(expect) or invalidSpecies(expect) to raise an error.

void assertArgClass(const Class& expect, const char* fname) const

void assertArgSpecies(const Class& expect, const char* fname) const

These functions are similar to assertClass(const Class&) and assertSpecies(const Class&), but you can specify the name of the (non-member) function detecting the error as the argument fname, which is included in the error message.

void assertArgClass(const Object& ob, const Class& expect, const char* fname) const

void assertArgSpecies(const Object& ob, const Class& expect, const char* fname) const

These functions are similar to assertArgClass(const Class&, const char*) and assertArgSpecies(const Class&, const char*), but are intended for use within member functions. They test the class or species of the argument ob, and include the value of the this pointer in the error message.

SEARCHING

virtual unsigned hash() const = 0

Returns a number that classes such as Set can use as a hash table probe. If two objects are equal; that is, if isEqual() returns YES for the objects, then the two objects must return the same value for hash().

COMPARING OBJECTS

virtual int compare(const Object& ob) const = 0

Compares this object with the argument object ob and returns a negative result if this object is less than ob, zero if this object equals ob, and a positive result if this object is greater than ob.

TESTING OBJECTS

bool isSame(const Object& ob) const

Returns YES if this object is the same as ob; that is, both objects have the same memory address.

virtual bool isEqual(const Object& ob) const = 0

Returns YES if this object and the argument object ob are comparable and they have equal values. Two objects are comparable if they return the same class descriptor address for species(). Note that the functions isEqual() and hash() must be consistently defined; that is, if isEqual() returns YES for two objects, then they must return the same hash() value.

COPYING OBJECTS

virtual Object* shallowCopy() const = 0

Returns a pointer to a shallow copy of this object. If an object contains pointers to other objects, a shallow copy shares instances of these objects with the original object. The DEFINE_CLASS macros automatically define shallowCopy() for a class X as:

Object* X::shallowCopy() const { return new X(*this); }

Object* deepCopy() const

Returns a pointer to a deep copy of this object. A deep copy of an object does not share the same instances of sub-objects with the original object; i.e., if an object contains pointers to other objects, deepCopy() is called recursively to make copies of those objects.

virtual Object* copy() const

Returns a pointer to a copy of this object. Object::copy() is implemented as a call to shallowCopy(), but other classes may override this to provide a more reasonable default. For example, class Link reimplements copy() as a deepCopy() because Link objects cannot be shared reasonably.

virtual void deepenShallowCopy() = 0

This function is called by deepCopy() to convert a shallow copy of this object into a deep copy. It should be implemented for all classes whose objects contain pointers to other objects, and is normally called only from deepCopy() or from a derived class's implementation of deepenShallowCopy().

READING AND PRINTING OBJECTS

virtual void scanFrom(istream& strm)

Initializes that object by parsing (human readable) input from the input stream strm. Object::scanFrom() is implemented as a derivedClassResponsibility.

virtual void printOn(ostream& strm =cout) const = 0

Prints this object on the output stream strm.

virtual void dumpOn(ostream& strm =cerr) const

Prints this object on the output stream strm. Usually provides more information about the object than printOn() does. Object::dumpOn() is implemented as:

void Object::dumpOn(ostream& strm) const
{
    strm << className() << '[';
    printOn(strm);
    strm << ']' << endl;
}

OBJECT I/O

static Object* readFrom(OIOifd& fd)

static Object* readFrom(OIOin& strm)

Reads an object from the specified input file descriptor (fd) or stream (strm) into space allocated from the free store, and returns a pointer to the object. To read an object back, an OIOifd or OIOin class compatible with the OIOofd or OIOout class used to store the object must be used.

void storeMemberOn(OIOofd& fd) const

void storeMemberOn(OIOout& strm) const

Called by storer() functions to store members that are class instances. The member is stored on the specified output file descriptor (fd) or stream (strm). The OIOofd and OIOout classes determine the format of the external representation of the object.

void storeOn(OIOofd& fd) const

void storeOn(OIOout& strm) const

Stores this object on the specified output file descriptor (fd) or stream (strm) in a format that can be read by readFrom(). The OIOofd and OIOout classes determine the format of the external representation of the object.

DOWNWARD CASTS

static Object& castdown(Object& p)

static const Object& castdown(const Object& p)

static Object* castdown(Object* p)

static const Object* castdown(const Object* p)

Performs a downward cast of a pointer or reference to an object. For class Object, castdown() is a no-op. The DECLARE_MEMBERS macro automatically generates inline definitions for these functions.

virtual void* _castdown(const Class& target) const

Returns the value of the this pointer cast down to the class whose descriptor address is target. Class Object implements _castdown() as follows:

void* Object::_castdown(const Class& target) const
{
    if (&target == Object::desc()) return (void*)this;
    return 0;
}

The DEFINE_CLASS and DEFINE_ABSTRACT_CLASS macros automatically generate a definition for this function.

void* _safe_castdown(const Class& target) const

Calls _castdown(target) and raises an NIHCL_BADCASTDN exception if _castdown() returns 0, indicating that the downward cast was invalid. Called by castdown() when the MI option is enabled.

DEPENDENT OBJECT FACILITY

Unfortunately, since C++ does not have automatic garbage collection as Smalltalk-80 does, it is difficult to know when dependent objects should be destroyed. We do not recommend the use of this facility for that reason.

virtual Object* addDependent(Object& ob)

Adds the object ob to the list of dependents for this object.

virtual void changed()

Applies update(this, *nil) to all objects that depend on this object.

virtual void changed(const Object& ob)

Applies update(this, ob) to all objects that depend on this object. Object::changed() is implemented as:

void Object::changed(const Object& param)
{
    OrderedCltn* depList = &dependents();
    DO(*depList,Object,depob) depob->update(*this,param); OD
    delete depList;
}

virtual OrderedCltn& dependents() const

Returns an OrderedCltn containing all objects that are dependents of this object.

virtual void release()

Removes all dependent objects (i.e., those objects added by addDependent()) from this object's list of dependent objects.

virtual Object* removeDependent(const Object& ob)

Removes the argument object ob from this object's list of dependent objects.

virtual void update(const Object& changed, const Object& param)

This function is called for all objects that are dependents of an object when changed() is applied to an object with dependents. The argument changed is the object that changed() was applied to, and the argument param is the object that was the argument to changed().

CONTAINER CLASS SUPPORT

virtual unsigned capacity() const

Returns the maximum number of objects or items that an object may hold. For some classes, such as those derived from Collection, this is not a hard limit, since instances of these classes can resize themselves to accommodate more objects. For other classes, such as Bitset, this is a hard limit. Object::capacity() returns 0.

virtual unsigned size() const

Returns the number of objects or items that an object currently holds. Object::size() returns 0.

REPORTING ERRORS

void derivedClassResponsibility(const char* fname) const

Raises an NIHCL_DRVDCLASSRSP exception.

void invalidArgClass(const Class& expect, const char* fname) const

Raises an NIHCL_BADARGCL exception. The argument expect indicates the expected class, and fname specifies the name of the function which detected the error.

void invalidArgSpecies(const Class& expect, const char* fname) const

Raises an NIHCL_BADARGSP exception. This object is the instance of the invalid class, the argument expect indicates the expected class, and fname specifies the name of the function which detected the error.

@item{void invalidArgClass(const Object& ob, const Class& expect,} @itemx{const char* fname) const}
Raises an NIHCL_BADARGCLM exception. The argument ob is the instance of the invalid class, the argument expect indicates the expected class, and fname specifies the name of the member function which detected the error.

@item{void invalidArgSpecies(const Object& ob, const Class& expect,} @itemx{const char* fname) const}
Raises an NIHCL_BADARGSPM exception. The argument ob is the instance of the invalid class, the argument expect indicates the expected class, and fname specifies the name of the member function which detected the error.

void invalidClass(const Class& expect) const

void invalidSpecies(const Class& expect) const

Raise an NIHCL_BADCLASS or NIHCL_BADSPEC. The argument expect indicates the expected class.

void shouldNotImplement(const char* fname) const

Raises an NIHCL_ILLEGALMFCN exception.

HANDLING EXCEPTIONS

virtual void destroyer()

Called when an auto object is going out-of-scope as the result of an exception. A class's destroyer() function should clean up the instance as the normal destructor would. Object::destroyer() is implemented as a no-op. Use of the destroyer() function is not recommended because it is too error-prone. It will be eliminated when C++ supports exception handling.

PROTECTED MEMBERS

Deep Copy

void deepenVBase()

Applies deepenShallowCopy() to this object if it has not already been "deepened". Normally called by the deepenShallowCopy() functions of derived classes that have this class as a virtual base. See `Template_h' and `Template_c' for details. The DEFINE_CLASS macros define the deepenVBase() function for each class.

Object I/O

Object(OIOifd&)

Object(OIOin&)

Add the object being stored to Class::readFromTbl.

virtual void storer(OIOofd&) const

virtual void storer(OIOout&) const

These functions currently do nothing.

void storeVBaseOn(OIOofd& fd) const

void storeVBaseOn(OIOout& strm) const

Applies storer() to this object if it has not already been stored on fd or strm. Normally called by the storer() functions of derived classes that have this class as a virtual base. See `Template_h' and `Template_c' for details. The DEFINE_CLASS macros define the storeVBaseOn() functions for class X in terms of StoreOnTbl::_storeVBase() as:

void X::storeVBaseOn(OIOofd& fd) const
{
    if (fd._storeVBase((const void*)this)) X::storer(fd);
}

void X::storeVBaseOn(OIOout& strm) const
{
    if (strm._storeVBase((const void*)this)) X::storer(strm);
}

Ambiguous Castdown Check

void ambigCheck(void*& p, void*& q, const Class&) const

Raises an NIHCL_AMBIGCASTDN error if p and q are both nonzero and unequal. If q is zero, p is assigned to q. Used when writing the _castdown() member function for classes with multiple base classes. See `Template_c' for an example.

EXCEPTIONS RAISED

NIHCL_AMBIGCASTDN, NIHCL_DRVDCLASSRSP, NIHCL_ILLEGALMFCN, NIHCL_BADARGCL,
NIHCL_BADARGSP, NIHCL_BADARGCLM, NIHCL_BADARGSPM, NIHCL_BADCASTDN,
NIHCL_BADCLASS, NIHCL_BADSTMBR, NIHCL_BADSPEC, NIHCL_RDABSTCLASS

Go to the previous, next section.