wcvectos.gml

开放源码的编译器open watcom 1.6.0版的源代码

.*
.* generator for ordered and sorted vectors
.*
:CLFNM cl2='WC&lpref.OrderedVector<Type>'.WC&lpref.SortedVector<Type>
:CMT.========================================================================
:LIBF fmt='hdr'.WC&lpref.SortedVector<Type>, WC&lpref.OrderedVector<Type>
:HFILE.wcvector.h
:CLSS.
The &cls. are templated classes used to store objects in a vector.
Ordered and Sorted vectors are powerful arrays which can be resized and provide
an abstract interface to insert, find and remove elements.
An ordered vector maintains the order in which elements are added, and
allows more than one copy of an element that is equivalent.
The sorted vector allow only one copy of an equivalent element, and inserts
them in a sorted order.
The sorted vector is less efficient when inserting elements, but can provide
a faster retrieval time.
:P.
Elements cannot be inserted into these vectors by assigning to a vector index.
Vectors automatically grow when necessary to insert an element if the
.MONO resize_required
.ix resize_required exception
exception is not enabled.
:P.
In the description of each member function, the text
.MONO Type
is used to indicate the template parameter defining

.if &lpref. eq Val .do begin
the type of the elements stored in the vector.
:P.
Values are copied into the vector, which could be undesirable
if the stored objects are complicated and copying is expensive.
Value vectors should not be used to store objects of a base class if any
derived types of different sizes would be stored in the vector, or if the
destructor for a derived class must be called.
.do end
.el .do begin
the type pointed to by the pointers stored in the vector.
:P.
Note that lookups are performed on the types pointed to, not just
by comparing pointers.  Two pointer elements are equivalent if the values
they point to are equivalent.  The values pointed to do not need to
be the same object.
.do end

:P.
The
.MONO WC&lpref.OrderedVector
class stores elements in the order which they are inserted using the
.MONO insert, append, prepend
and
.MONO insertAt
member functions.  Linear searches are performed to locate entries, and
the less than operator is not required.
:P.
The
.MONO WC&lpref.SortedVector
class stores elements in ascending order.  This requires that
.MONO Type
provides
a less than operator.  Insertions are more expensive than inserting or
appending into an ordered vector, since entries must be moved to make
room for the new element.  A binary search is used to locate elements in
a sorted vector, making searches quicker than in the ordered vector.
:P.
Care must be taken when using the
.MONO WC&lpref.SortedVector
class not to change the ordering of the vector
elements.

.if &lpref. eq Val .do begin
The result returned by the index operator must not be assigned to or
modified in such a way that it is no longer equivalent to the value inserted
into the vector.
Lookups assume elements are in sorted order.
.do end
.el .do begin
An object pointed to by a vector element must not be changed so that
it is not equivalent to the value when the pointer was inserted into the
vector.
The index operator and the member functions
.MONO find, first,
and
.MONO last
all return pointers the elements pointed to by the vector elements.
Lookups assume elements are in sorted order, so you should not
use the returned pointers to change the ordering of the value
pointed to.
.do end

:P.
The
.MONO WC&lpref.Vector
class is also available.  It provides a resizable and boundary safe vector
similar to standard arrays.
:P.
:CMT. state WCExcept is base class
:INCLUDE file='_EXPT_BC'.
:HDG.Requirements of Type
Both the &cls. require
.MONO Type
to have:

.if &lpref. eq Val .do begin
:P.
A default constructor (
.MONO Type::Type()
).
:P.
A well defined copy constructor (
.MONO Type::Type( const Type & )
).
:P.
A well defined assignment operator
.br
(
.MONO Type & operator =( const Type & )
).
:P.
The following override of
.MONO operator new()
if
.MONO Type
overrides the global
.MONO operator new():
:XMPL
void * operator new( size_t, void *ptr ) { return( ptr ); }
:eXMPL
.do end

:P
A well defined equivalence operator with constant parameters
.br
(
.MONO int operator ==( const Type & ) const
).
:P.
Additionally the
.MONO WC&lpref.SortedVector
class requires
.MONO Type
to have:
:P
A well defined less than operator with constant parameters
.br
(
.MONO int operator <( const Type & ) const
).
:HDG.Public Member Functions
The following member functions are declared in the public interface:
:MFNL.
:MFN index='WC&lpref.OrderedVector' .WC&lpref.OrderedVector( size_t = WCDEFAULT_VECTOR_LENGTH, unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
:MFN index='WC&lpref.OrderedVector' .WC&lpref.OrderedVector( const WC&lpref.OrderedVector & );
:MFN index='~~WC&lpref.OrderedVector' .virtual ~~WC&lpref.OrderedVector();
:MFN index='WC&lpref.SortedVector' .WC&lpref.SortedVector( size_t = WCDEFAULT_VECTOR_LENGTH, unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
:MFN index='WC&lpref.SortedVector' .WC&lpref.SortedVector( const WC&lpref.SortedVector & );
:MFN index='~~WC&lpref.SortedVector' .virtual ~~WC&lpref.SortedVector();
:MFN index='clear'          .void clear();
.if &lpref eq Ptr .do begin
:MFN index='clearAndDestroy'.void clearAndDestroy();
.do end
:MFN index='contains'       .int contains( const &lparm. ) const;
:MFN index='entries'        .unsigned entries() const;
.if &lpref. eq Val .do begin
:MFN index='find'           .int find( const Type &, Type & ) const;
.do end
.el .do begin
:MFN index='find'           .Type * find( const Type * ) const;
.do end
:MFN index='first'          .&lret first() const;
:MFN index='index'          .int index( const &lparm. ) const;
.if &lpref. eq Val .do begin
:MFN index='insert'         .int insert( const &lparm. );
.do end
.el .do begin
:MFN index='insert'         .int insert( &lparm. );
.do end
:MFN index='isEmpty'        .int isEmpty() const;
:MFN index='last'           .&lret. last() const;
:MFN index='occurrencesOf'  .int occurrencesOf( const &lparm. ) const;
.if &lpref. eq Val .do begin
:MFN index='remove'         .int remove( const Type & );
.do end
.el .do begin
:MFN index='remove'         .Type * remove( const Type * );
.do end
:MFN index='removeAll'      .unsigned removeAll( const &lparm. );
.if &lpref. eq Val .do begin
:MFN index='removeAt'       .int removeAt( int );
:MFN index='removeFirst'    .int removeFirst();
:MFN index='removeLast'     .int removeLast();
.do end
.el .do begin
:MFN index='removeAt'       .Type * removeAt( int );
:MFN index='removeFirst'    .Type * removeFirst();
:MFN index='removeLast'     .Type * removeLast();
.do end
:MFN index='resize'         .int resize( size_t );
:eMFNL.
The following public member functions are available for the
.MONO WC&lpref.OrderedVector
class only:
:MFNL.
.if &lpref. eq Val .do begin
:MFN index='append'         .int append( const &lparm. );
:MFN index='insertAt'       .int insertAt( int, const &lparm. );
:MFN index='prepend'        .int prepend( const &lparm. );
.do end
.el .do begin
:MFN index='append'         .int append( &lparm. );
:MFN index='insertAt'       .int insertAt( int, &lparm. );
:MFN index='prepend'        .int prepend( &lparm. );
.do end
:eMFNL.
:HDG.Public Member Operators
The following member operators are declared in the public interface:
:MFNL.
:MFN index='operator []'     .&lret. & operator []( int );
.if &lpref. eq Val .do begin
:MFN index='operator []'     .const Type & operator []( int ) const;
.do end
.el .do begin
:MFN index='operator []'     .Type * const & operator []( int ) const;
.do end
:MFN index='operator ='      .WC&lpref.OrderedVector & WC&lpref.OrderedVector::operator =( const WC&lpref.OrderedVector & );
:MFN index='operator ='      .WC&lpref.SortedVector & WC&lpref.SortedVector::operator =( const WC&lpref.SortedVector & );
:MFN index='operator =='     .int WC&lpref.OrderedVector::operator ==( const WC&lpref.OrderedVector & ) const;
:MFN index='operator =='     .int WC&lpref.SortedVector::operator ==( const WC&lpref.SortedVector & ) const;
:eMFNL.
:eCLSS.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.OrderedVector<Type>' fmt='ctor' prot='public'.WC&lpref.OrderedVector
:SNPL.
:SNPFLF                    .#include <wcvector.h>
:SNPFLF                    .public:
:SNPCD cd_idx='c'.WC&lpref.OrderedVector( size_t = WCDEFAULT_VECTOR_LENGTH,
:SNPFLF          .            unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.OrderedVector<Type>
constructor creates an empty
.MONO WC&lpref.OrderedVector
object able to store the number of elements specified
in the first optional parameter, which defaults to the constant
.MONO WCDEFAULT_VECTOR_LENGTH
(currently defined as 10).
If the
.MONO resize_required
.ix resize_required exception
exception is not enabled, then the second optional parameter is used to
specify the value to increase the vector size
when an element is inserted
into a full vector.
If zero(0) is specified as the second parameter, any attempt to insert into
a full vector fails.
This parameter defaults to the constant
.MONO WCDEFAULT_VECTOR_RESIZE_GROW
(currently defined as 5).
:P.
If the vector object cannot be fully initialized, the vector is created
with length zero.
:RSLTS.
The
.MONO WC&lpref.OrderedVector<Type>
constructor creates an empty initialized
.MONO WC&lpref.OrderedVector
object.
:SALSO.
:SAL typ='omtyp' ocls='WCExcept'.resize_required
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.OrderedVector<Type>' fmt='ctor' prot='public'.WC&lpref.OrderedVector
:SNPL.
:SNPFLF                    .#include <wcvector.h>
:SNPFLF                    .public:
:SNPCD cd_idx='c'.WC&lpref.OrderedVector( const WC&lpref.OrderedVector & );
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.OrderedVector<Type>
constructor is the copy constructor for the
.MONO WC&lpref.OrderedVector
class.
The new vector is created with the same length and
resize value as the passed vector.
All of the vector elements and exception trap states are copied.
:P.
If the new vector cannot be fully created, it will have length zero.  The
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if enabled in the vector being copied.
:RSLTS.
The
.MONO WC&lpref.OrderedVector<Type>
creates a
.MONO WC&lpref.OrderedVector
object which is a copy of the passed vector.
:SALSO.
:SAL typ='fun'.operator~b=
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.OrderedVector<Type>' fmt='dtor' prot='public'.~~WC&lpref.OrderedVector
:SNPL.
:SNPFLF                    .#include <wcvector.h>
:SNPFLF                    .public:
:SNPCD cd_idx='d'.virtual ~~WC&lpref.OrderedVector();
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.OrderedVector<Type>
destructor is the destructor for the
.MONO WC&lpref.OrderedVector
class.
If the vector is not length zero and the
.MONO not_empty
.ix not_empty exception
exception is enabled, the exception is thrown.
Otherwise, the vector entries are cleared using the
.MONO clear
member function.

.if &lpref. eq Ptr .do begin
The objects which the vector entries point to are not deleted unless the
.MONO clearAndDestroy
member function is explicitly called before the destructor is called.
.do end
The call to the
.MONO WC&lpref.OrderedVector<Type>
destructor is inserted implicitly by the compiler at the point where the
.MONO WC&lpref.OrderedVector
object goes out of scope.
:RSLTS.
The
.MONO WC&lpref.OrderedVector<Type>
destructor destroys an
.MONO WC&lpref.OrderedVector
object.
:SALSO.
:SAL typ='fun'.clear
.if &lpref. eq Ptr .do begin
:SAL typ='fun'.clearAndDestroy
.do end
:SAL typ='omtyp' ocls='WCExcept'.not_empty
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.SortedVector<Type>' fmt='ctor' prot='public'.WC&lpref.SortedVector
:SNPL.
:SNPFLF                    .#include <wcvector.h>
:SNPFLF                    .public:
:SNPCD cd_idx='c'.WC&lpref.SortedVector( size_t = WCDEFAULT_VECTOR_LENGTH,
:SNPFLF          .            unsigned = WCDEFAULT_VECTOR_RESIZE_GROW );
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.SortedVector<Type>
constructor creates an empty
.MONO WC&lpref.SortedVector
object able to store the number of elements specified
in the first optional parameter, which defaults to the constant
.MONO WCDEFAULT_VECTOR_LENGTH
(currently defined as 10).
If the
.MONO resize_required
.ix resize_required exception
exception is not enabled, then the second optional parameter is used to
specify the value to increase the vector size when an element is inserted
into a full vector.
If zero(0) is specified as the second parameter, any attempt to insert into
a full vector fails.
This parameter defaults to the constant
.MONO WCDEFAULT_VECTOR_RESIZE_GROW
(currently defined as 5).
:P.
If the vector object cannot be fully initialized, the vector is created
with length zero.
:RSLTS.