wclist.gml

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

:CLFNM cl2='WC&lpref.DList<Type>'.WC&lpref.SList<Type>
:CMT.========================================================================
:LIBF fmt='hdr'.WC&lpref.SList<Type>, WC&lpref.DList<Type>
:HFILE.wclist.h
:CMT.:DVFML.    List classes are not derived from links, they operate on them.
:CMT.:DVFM.WCSLink
:CMT.:DVFM.WCDLink
:CMT.:eDVFML.
:CLSS.
The &cls. are the templated classes used to create objects which
are single or double linked lists.
.*
.if &lpref. eq Isv .th .do begin
The created list is intrusive,
.ix intrusive classes
which means that list elements which
are inserted must be created with a library supplied base class.
The class
.MONO WCSLink
provides the base class definition for single linked lists, and
should be inherited by the definition of any list item for single linked lists.
It provides the linkage that is used to traverse the list elements.
Similarly, the class
.MONO WCDLink
provides the base class definition for double lists, and
should be inherited by the definition of any list item for double lists.

.do end
.el .if &lpref. eq Val .do begin

Values are copied into the list, which could be undesirable
if the stored objects are complicated and copying is expensive.
Value lists should not be used to store objects of a base class if any
derived types of different sizes would be stored in the list, or if the
destructor for a derived class must be called.

.do end
.*
:P.
In the description of each member function, the text
.MONO Type
is used to indicate the type value specified as the template parameter.
.*
.if &lpref. eq Isv .do begin
.MONO Type
is the type of the list elements, derived from
.MONO WCSLink
or
.MONO WCDLink.
.do end
.el .if &lpref. eq Val .do begin
.MONO Type
is the type of the values stored in the list.
.do end
.el .do begin
The pointers stored in the list point to values of type
.MONO Type.
.do end
.*
:P.
:CMT. state WCExcept is base class
:INCLUDE file='_EXPT_BC'.
:HDG.Requirements of Type
.*
.if &lpref. eq Isv .do begin
The
.MONO WCIsvSList<Type>
class requires only that
.MONO Type
is derived from
.MONO WCSLink.
The
.MONO WCIsvDList<Type>
class requires only that
.MONO Type
is derived from
.MONO WCDLink.
.do end
.el .do begin
The &cls requires
.MONO Type
to have:
:P.
.if &lpref. eq Val .do begin
(1) a default constructor (
.MONO Type::Type()
).
:P.
(2) a well defined copy constructor (
.MONO Type::Type( const Type & )
).
:P.
(3) an equivalence operator with constant parameters
.in +10
.MONO Type::operator ==( const Type & ) const
.in -10
.do end
.el .do begin
(1) an equivalence operator with constant parameters
.in +10
.MONO Type::operator ==( const Type & ) const
.in -10
.do end
.do end
.*
.*
.if &lpref. eq Isv .th .do begin
:HDG.Private Member Functions
In an intrusive list, copying a list is undefined.
Setting the copy constructor and assignment operator as private is the
standard mechanism to ensure a copy cannot be made.  The following member
functions are declared private:
:MFNL.
:MFN index='WC&lpref.SList'     .void WC&lpref.SList( const WC&lpref.SList & );
:MFN index='WC&lpref.DList'     .void WC&lpref.DList( const WC&lpref.DList & );
:MFN index='operator ='      .WC&lpref.SList & WC&lpref.SList::operator =( const WC&lpref.SList & );
:MFN index='operator ='      .WC&lpref.DList & WC&lpref.DList::operator =( const WC&lpref.DList & );
:eMFNL.
.do end
.*
:HDG.Public Member Functions
The following member functions are declared in the public interface:
:MFNL.
:MFCD cd_idx='c' .WC&lpref.SList();
.if &lpref. ne Isv .do begin
:MFCD cd_idx='c' .WC&lpref.SList( void * (*)( size_t ), void (*)( void *, size_t ));
:MFCD cd_idx='c' .WC&lpref.SList( const WC&lpref.SList & );
.do end
:MFCD cd_idx='d' .~~WC&lpref.SList();
:MFCD cd_idx='c' .WC&lpref.DList();
.if &lpref. ne Isv .do begin
:MFCD cd_idx='c' .WC&lpref.DList( void * (*)( size_t ), void (*)( void *, size_t ));
:MFCD cd_idx='c' .WC&lpref.DList( const WC&lpref.DList & );
.do end
:MFCD cd_idx='d' .~~WC&lpref.DList();
.if &lpref. eq Val .do begin
:MFN index='append'         .int append( const &lparm. );
.do end
.el .do begin
:MFN index='append'         .int append( &lparm. );
.do end
:MFN index='clear'          .void clear();
:MFN index='clearAndDestroy'.void clearAndDestroy();
:MFN index='contains'       .int contains( const &lparm. ) const;
:MFN index='entries'        .int entries() const;
:MFN index='find'           .&lret. find( int = 0 ) const;
:MFN index='findLast'       .&lret. findLast() const;
.if &lpref. eq Isv .th .do begin
:MFN index='forAll'         .void forAll( void (*)( &lret, void * ), void *);
.do end
.el .do begin
:MFN index='forAll'         .void forAll( void (*)( &lret., void * ), void *) const;
.do end
:MFN index='get'            .&lret. get( int = 0 );
:MFN index='index'          .int index( const &lparm ) const;
.if &lpref. eq Isv .do begin
:MFN index='index'          .int index( int (*)( const Type *, void * ), void * ) const;
.do end
.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;
:eMFNL.
:HDG.Public Member Operators
The following member operators are declared in the public interface:
:MFNL.
.if &lpref. ne Isv .do begin
:MFN index='operator ='      .WC&lpref.SList & WC&lpref.SList::operator =( const WC&lpref.SList & );
:MFN index='operator ='      .WC&lpref.DList & WC&lpref.DList::operator =( const WC&lpref.DList & );
.do end
:MFN index='operator =='     .int WC&lpref.SList::operator ==( const WC&lpref.SList & ) const;
:MFN index='operator =='     .int WC&lpref.DList::operator ==( const WC&lpref.DList & ) const;
:eMFNL.
.if &lpref. eq Isv .th .do begin
:HDG.Sample Program Using an Intrusive List
:XMPL.
:INCLUDE file='wcldintr.cpp'.
:eXMPL.
.do end
.if &lpref. eq Val .th .do begin
:HDG.Sample Program Using a Value List
:XMPL.
:INCLUDE file='wcldval.cpp'.
:eXMPL.
.do end
.if &lpref. eq Ptr .th .do begin
:HDG.Sample Program Using a Pointer List
:XMPL.
:INCLUDE file='wcldptr.cpp'.
:eXMPL.
.do end
:eCLSS.
:eLIBF.
:CMT. for the _ALOCFNS and _DTOR2 include files
.SE lobjtype='WC&lpref.SList<Type>'
:CMT.========================================================================
:LIBF cltype='WC&lpref.SList<Type>' fmt='mfun' prot='public'.WC&lpref.SList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .public:
:SNPF index='WC&lpref.SList'.WC&lpref.SList();
:eSNPL.
:SMTICS.
The &fn. creates an empty
.MONO WC&lpref.SList
object.
:RSLTS.
The &fn. produces an initialized
.MONO WC&lpref.SList
object.
:SALSO.
.if &lpref. ne Isv .do begin
:SAL typ='fun'.WC&lpref.SList
.do end
:SAL typ='fun'.~~WC&lpref.SList
:eSALSO.
:eLIBF.
.if &lpref ne Isv .do begin
:CMT.========================================================================
:LIBF cltype='WC&lpref.SList<Type>' fmt='mfun' prot='public'.WC&lpref.SList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .public:
:SNPF index='WC&lpref.SList'.WC&lpref.SList( void *(*allocator)( size_t ),
:SNPFLF                     .            void (*deallocator)( void *, size_t ) );
:eSNPL.
:SMTICS.
The &fn. creates an empty
.MONO &lobjtype.
object.
The :HP1.allocator:eHP1.
function is registered to perform all memory allocations of the list
elements, and the :HP1.deallocator:eHP1.
function to perform all freeing of the list elements' memory.
:INCLUDE file='_ALOCFNS'.
:P.
The :HP1.allocator:eHP1. and :HP1.deallocator:eHP1. functions may assume
that for a list object instance, the
:HP1.allocator:eHP1. is always called with the same first argument
(the size of the memory to be allocated).
The
.MONO WCValSListItemSize(Type)
.ix WCValSListItemSize macro
macro returns the size of the elements which are allocated by the
:HP1.allocator:eHP1. function.
:RSLTS.
The &fn. creates an initialized
.MONO &lobjtype.
object and registers the :HP1.allocator:eHP1.
and :HP1.deallocator:eHP1. functions.
:SALSO.
:SAL typ='fun'.WC&lpref.SList
:SAL typ='fun'.~~WC&lpref.SList
:eSALSO.
:eLIBF.
.do end
:CMT.========================================================================
:LIBF cltype='WC&lpref.SList<Type>' fmt='mfun' prot='&lacc.'.WC&lpref.SList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .&lacc.:
:SNPF index='WC&lpref.DList'.void WC&lpref.SList( const WC&lpref.SList & );
:eSNPL.
:SMTICS.
The &fn. is the copy constructor for the single linked list class.
.if &lpref. eq Isv .th .do begin

Making a copy of the list object would result in a error condition,
since intrusive lists cannot share data items with other lists.

.do end
.el .do begin

All of the list elements are copied to the new list, as well as the exception
trap states, and any registered :HP1.allocator:eHP1. and :HP1.deallocator:eHP1.
functions.

.if &lpref. eq Val .do begin
.MONO Type's
copy constructor is invoked to copy the values contained by the list
elements.
.do end
.* end if Val

:P.
If all of the elements cannot be copied and the
.MONO out_of_memory
.ix out_of_memory exception
is enabled in the list being copied, the exception is thrown.
The new list is created in a valid state, even if all of the list elements
could not be copied.
:RSLTS.
The &fn. produces a copy of the list.
:SALSO.
:SAL typ='fun'.WC&lpref.SList
:SAL typ='fun'.~~WC&lpref.SList
:SAL typ='fun'.clear
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.

.do end
.* end if not Isv
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.SList<Type>' fmt='mfun' prot='public'.~~WC&lpref.SList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .public:
:SNPF index='WC&lpref.SList'.~~WC&lpref.SList();
:eSNPL.
:SMTICS.
The &fn. destroys the
.MONO WC&lpref.SList
object.
If the list is not empty and the
.MONO not_empty
.ix not_empty exception
exception is enabled, the exception is thrown.
If the
.MONO not_empty
exception is not enabled and the list is not empty,
the list is cleared using the
.MONO clear
member function.
.se lobjtype=WC&lpref.SList
:INCLUDE file='_DTOR2'.
:RSLTS.
The
.MONO WC&lpref.SList
object is destroyed.
:SALSO.
:SAL typ='fun'.WC&lpref.SList
:SAL typ='fun'.clear
:SAL typ='fun'.clearAndDestroy
:SAL typ='omtyp' ocls='WCExcept'.not_empty
:eSALSO.
:eLIBF.
:CMT. for the _ALOCFNS and _DTOR2 include files
.SE lobjtype='WC&lpref.DList<Type>'
:CMT.========================================================================
:LIBF cltype='WC&lpref.DList<Type>' fmt='mfun' prot='public'.WC&lpref.DList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .public:
:SNPF index='WC&lpref.DList'.WC&lpref.DList();
:eSNPL.
:SMTICS.
The &fn. creates an empty
.MONO WC&lpref.DList
object.
:RSLTS.
The &fn. produces an initialized
.MONO WC&lpref.DList
object.
:SALSO.
.if &lpref. ne Isv .do begin
:SAL typ='fun'.WC&lpref.DList
.do end
:SAL typ='fun'.~~WC&lpref.DList
:eSALSO.
:eLIBF.
.if &lpref ne Isv .do begin
:CMT.========================================================================
:LIBF cltype='WC&lpref.DList<Type>' fmt='mfun' prot='public'.WC&lpref.DList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .public:
:SNPF index='WC&lpref.DList'.WC&lpref.DList( void *(*allocator)( size_t ),
:SNPFLF                     .            void (*deallocator)( void *, size_t ) );
:eSNPL.
:SMTICS.
The &fn. creates an empty
.MONO &lobjtype.
object.
The :HP1.allocator:eHP1.
function is registered to perform all memory allocations of the list
elements, and the :HP1.deallocator:eHP1.
function to perform all freeing of the list elements' memory.
:INCLUDE file='_ALOCFNS'.
:P.
The :HP1.allocator:eHP1. and :HP1.deallocator:eHP1. functions may assume that
for a list object instance, the
:HP1.allocator:eHP1. is always called with the same first argument
(the size of the memory to be allocated).
The
.MONO WCValDListItemSize(Type)
.ix WCValDListItemSize macro
macro returns the size of the elements which are allocated by the
:HP1.allocator:eHP1. function.