wclist.gml

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

: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.DList
:SAL typ='fun'.~~WC&lpref.DList
:eSALSO.
:eLIBF.
.do end
:CMT.========================================================================
:LIBF cltype='WC&lpref.DList<Type>' fmt='mfun' prot='&lacc.'.WC&lpref.DList
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .&lacc.:
:SNPF index='WC&lpref.DList'.WC&lpref.DList( const WC&lpref.DList & );
:eSNPL.
:SMTICS.
The &fn. is the copy constructor for the double 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.DList
:SAL typ='fun'.~~WC&lpref.DList
: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.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. destroys the
.MONO WC&lpref.DList
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.DList
:INCLUDE file='_DTOR2'.
:RSLTS.
The
.MONO WC&lpref.DList
object is destroyed.
:SALSO.
:SAL typ='fun'.WC&lpref.DList
:SAL typ='fun'.clear
:SAL typ='fun'.clearAndDestroy
:SAL typ='omtyp' ocls='WCExcept'.not_empty
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.append
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
.if &lpref. eq Val .do begin
:SNPF index='append'  .int append( const &lparm. );
.do end
.el .do begin
:SNPF index='append'  .int append( &lparm. );
.do end
:eSNPL.
:SMTICS.
.if &lpref. ne Isv .do begin

The &fn. is used to append the data
to the end of the list.

.if &lpref. eq Val .do begin
The data stored in the list is a copy of the data passed as a parameter.
.do end

:P.
If the
.MONO out_of_memory
.ix out_of_memory exception
exception is enabled and the append fails, the exception is thrown.
:RSLTS.
The data element is appended to the end of the list.  A TRUE value
(non-zero) is returned if the append is successful.  A FALSE (zero)
result is returned if the append fails.

.do end
.el .do begin

The &fn. is used to append the list element
object to the end of the list.
The address of (a pointer to) the list element object should be passed,
not the value.
Since the linkage information is stored in the list element, it is not
possible for the element to be in more than one list, or in the same list
more than once.
:P.
The passed list element should be constructed using
the appropriate link class as a base.
.MONO WCSLink
must be used as a list element base class for single linked lists,
and
.MONO WCDLink
must be used as a list element base class for double linked lists.
:RSLTS.
The list element is appended to the end of the list and a TRUE value
(non-zero) is returned.

.do end
:SALSO.
:SAL typ='fun'.insert
.if &lpref ne Isv .do begin
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
.do end
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.clear
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:SNPF index='clear'.void clear();
:eSNPL.
:SMTICS.
The &fn. is used to clear the list object and set it to the state of the object
just after the initial construction.
The list object is not destroyed and re-created by this operator, so
the object destructor is not invoked.

.if &lpref. eq Val .th .do begin

:P.
The &fn. has the same sematics as the
.MONO clearAndDestroy
member function.

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

The list elements are not cleared.
Any list items still in the list are lost unless pointed to by some
pointer object in the program code.
:P.
If any of the list elements are not allocated with
.MONO new
(local variable or global list elements), then the &fn. must be used.
When all list elements are allocated with
.MONO new,
the
.MONO clearAndDestory
member function should be used.
.do end

:RSLTS.
The &fn. resets the list object to the state of the object immediately
after the initial construction.
:SALSO.
:SAL typ='fun'.~~WC&lpref.SList
:SAL typ='fun'.~~WC&lpref.DList
:SAL typ='fun'.clearAndDestroy
:SAL typ='fun'.get
:SAL typ='fun'.operator~b=
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.clearAndDestroy
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:SNPF index='clearAndDestroy'.void clearAndDestroy();
:eSNPL.
:SMTICS.
The &fn. is used to clear the list object and set it to the state
of the object just after the initial construction.
The list object is not destroyed and re-created by this operator, so
the object destructor is not invoked.

.if &lpref. eq Val .do begin

:P.
Before the list object is re-initialized, the
delete operator is called for each list element.
:RSLTS.
The &fn. resets the list object to the initial state of the object immediately
after the initial construction.

.do end
.el .do begin

.if &lpref. eq Ptr .do begin

Before the list object is re-initialized, the
the values pointed to by the list elements are deleted.

.* end if Ptr
.do end
.el .do begin
.* Isv

The link elements are deleted before the list is re-initialized.
:P.
If any elements in the list were not allocated by the
.MONO new
operator, the &fn must not be called.
The &fn destroys each list element with the destructor for
.MONO Type
even if the list element was created as an object derived from
.MONO Type,
unless
.MONO Type
has a pure virtual destructor.

.* end if Isv
.do end

:RSLTS.
The &fn. resets the list object to the initial state of the object immediately
after the initial construction and deletes the list elements.

.* end if not val
.do end
:SALSO.
:SAL typ='fun'.clear
:SAL typ='fun'.get
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.contains
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:SNPF index='contains'  .int contains( const &lparm. ) const;
:eSNPL.
:SMTICS.
The &fn. is used to determine if a list element
object is already contained in the list.

.if &lpref. eq Isv .th .do begin
The address of (a pointer to) the list element object should be passed,
not the value.
Each list element is compared to the passed element object to determine
if it has the same address.
Note that the comparison is of the addresses of the elements, not the
contained values.

.do end
.el .do begin

Each list element is compared to the passed element using
.MONO Type's operator ==
to determine if the passed element is contained in the list.

.if &lpref eq Ptr .do begin
Note that the comparison is of the objects pointed to.
.do end

.* end if not Isv
.do end
:RSLTS.
Zero(0) is returned
if the passed list element object is not found in the list.
A non-zero result is returned if the element is found in the list.
:SALSO.
:SAL typ='fun'.find
:SAL typ='fun'.index
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.entries
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:MFN index='entries'  .int entries() const;
:eSNPL.
:SMTICS.
The &fn. is used to determine the number of list elements contained
in the list object.
:RSLTS.
The number of entries stored in the list is returned, zero(0) is returned
if there are no list elements.
:SALSO.
:SAL typ='fun'.isEmpty
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.find
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:MFN index='find'     .&lret. find( int = 0 ) const;
:eSNPL.
:SMTICS.
.if &lpref. eq Isv .th .do begin
The &fn. returns a pointer to a list element in the list object.
The list element is not removed from the list, so care must be
taken not to delete the element returned to you.
.do end
.el .do begin
The &fn. returns the value of a list element in the list object.
.do end
The optional parameter specifies which element to locate, and defaults
to the first element.
Since the first element of the list is the zero'th element, the last
element will be the number of list entries minus one.
:P.
If the list is empty and the
.MONO empty_container
.ix empty_container exception
exception is enabled, the exception is thrown.
If the
.MONO index_range
exception is enabled,
the exception is thrown if the index value is negative or
is greater than the number of list entries minus one.
:RSLTS.
.if &lpref. eq Isv .th .do begin

A pointer to the selected list element or the closest list element is returned.
If the index value is negative, the closest list element is the first element.
The last element is the closest element if the index value is greater than the
number of list entries minus one.
A value of NULL(0) is returned if there are no elements in the list.

.do end
.el .do begin

The value of the selected list element or the closest element is returned.
If the index value is negative, the closest list element is the first element.
The last element is the closest element if the index value is greater than the
number of list entries minus one.

.if &lpref eq Val .do begin
A default initialized value is returned if there are no elements in the list.
.do end
.el .do begin
An uninitialized pointer is returned if there are no elements in the list.
.do end

.* end if not isv
.do end
:SALSO.
:SAL typ='fun'.findLast
:SAL typ='fun'.get
:SAL typ='fun'.index
:SAL typ='fun'.isEmpty
:SAL typ='omtyp' ocls='WCExcept'.empty_container
:SAL typ='omtyp' ocls='WCExcept'.index_range
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.findLast
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public: