Go to the previous, next section.
#include <nihcl/Object.h>
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.
static Object* const nil
Object::nil
is a pointer to the sole instance of class
Nil
.static const Class* desc()
virtual const Class* isA() const = 0
virtual const Class* species() const
Object::species()
is implemented as
{ returnisA(); }
.
const char* className() const
bool isMemberOf(const Class&
c) const
YES
if this object is an instance of the class whose class descriptor is
c.
bool isSpecies(const Class&
c) const
YES
if the species of this object is the class whose class descriptor is
c.
bool isKindOf(const Class&
c) const
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
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
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
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.
virtual unsigned hash() const = 0
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()
.
virtual int compare(const Object&
ob) const = 0
bool isSame(const Object&
ob) const
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
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.
virtual Object* shallowCopy() const = 0
DEFINE_CLASS
macros automatically define
shallowCopy()
for a class
X
as:
Object* X::shallowCopy() const { return new X(*this); }
Object* deepCopy() const
deepCopy()
is called recursively to make copies of those objects.
virtual Object* copy() const
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
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()
.
virtual void scanFrom(istream&
strm)
Object::scanFrom()
is implemented as a
derivedClassResponsibility
.
virtual void printOn(ostream&
strm
=cout) const = 0
virtual void dumpOn(ostream&
strm
=cerr) const
printOn()
does.
Object::dumpOn()
is implemented as:
void Object::dumpOn(ostream& strm) const { strm << className() << '['; printOn(strm); strm << ']' << endl; }
static Object* readFrom(OIOifd&
fd)
static Object* readFrom(OIOin&
strm)
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
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
readFrom()
. The
OIOofd
and
OIOout
classes determine the format of the external representation of the object.
static Object& castdown(Object&
p)
static const Object& castdown(const Object&
p)
static Object* castdown(Object*
p)
static const Object* castdown(const Object*
p)
Object
,
castdown()
is a no-op. The
DECLARE_MEMBERS
macro automatically generates inline definitions for these functions.
virtual void* _castdown(const Class&
target) const
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
_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.
changed()
is applied to this object, the member function
update()
is applied to all of its dependents.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)
virtual void changed()
update(this, *nil)
to all objects that depend on this object.
virtual void changed(const Object&
ob)
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
OrderedCltn
containing all objects that are dependents of this object.
virtual void release()
addDependent()
) from this object's list of dependent objects.
virtual Object* removeDependent(const Object&
ob)
virtual void update(const Object&
changed, const Object&
param)
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()
.
virtual unsigned capacity() const
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
Object::size()
returns 0.
void derivedClassResponsibility(const char*
fname) const
NIHCL_DRVDCLASSRSP
exception.
void invalidArgClass(const Class&
expect, const char*
fname) const
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
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
NIHCL_BADCLASS
or
NIHCL_BADSPEC
. The argument
expect
indicates the expected class.
void shouldNotImplement(const char*
fname) const
NIHCL_ILLEGALMFCN
exception.
virtual void destroyer()
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.
void deepenVBase()
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(OIOifd&)
Object(OIOin&)
Class::readFromTbl
.
virtual void storer(OIOofd&) const
virtual void storer(OIOout&) const
void storeVBaseOn(OIOofd&
fd) const
void storeVBaseOn(OIOout&
strm) const
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); }
void ambigCheck(void*&
p, void*&
q, const Class&) const
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.
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.