wclist.gml

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

:MFN index='findLast' .&lret. findLast() const;
:eSNPL.
:SMTICS.
.if &lpref. eq Isv .th .do begin
The &fn. returns a pointer to the last 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 the last list element in the list object.
.do end
:P.
If the list is empty, one of two exceptions can be thrown.
If the
.MONO empty_container
.ix empty_container exception
exception is enabled, it is thrown.
The
.MONO index_range
.ix index_range exception
exception is thrown if it is enabled and the
.MONO empty_container
exception is not enabled.
:RSLTS.
.if &lpref. eq Isv .th .do begin
A pointer to the last list element is returned.
A value of NULL(0) is returned if there are no elements in the list.
.do end
.el .do begin
The value of the last list element is returned.

.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

.do end
:SALSO.
:SAL typ='fun'.find
:SAL typ='fun'.get
: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'.forAll
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
.if &lpref. eq Isv .do begin
:MFN index='forAll'   .void forAll( void (*fn)( &lret., void * ), void *);
.do end
.el .do begin
:MFN index='forAll'   .void forAll( void (*)( &lret., void * ), void *) const;
.do end
:eSNPL.
:SMTICS.
The &fn. is used to cause the function :HP1.fn:eHP1. to be invoked
for each list element.
The :HP1.fn:eHP1. function should have the prototype
:XMPL.
void (*fn)( &lret., void * )
:eXMPL.
:P.
The first parameter of :HP1.fn:eHP1. shall accept
.if &lpref. eq Isv .th .do begin
a pointer to
.do end
.el .do begin
the value of
.do end
the list element currently active.
The second argument passed to :HP1.fn:eHP1. is the second argument of
the
.MONO forAll
function.
This allows a callback function to be defined which can accept
data appropriate for the point at which the
.MONO forAll
function is invoked.
:SALSO.
:SAL typ='cls'.WC&lpref.ConstSListIter
:SAL typ='cls'.WC&lpref.ConstDListIter
:SAL typ='cls'.WC&lpref.SListIter
:SAL typ='cls'.WC&lpref.DListIter
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.get
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:MFN index='get'      .&lret. get( int = 0 );
:eSNPL.
:SMTICS.

.if &lpref. eq Isv .th .do begin
The &fn. returns a pointer to a list element in the list object.
.do end
.el .do begin
The &fn. returns the value of the list element in the list object.
.do end

The list element is also removed from the list.
The optional parameter specifies which element to remove, 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 trap 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 removed
and 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 removed
and 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'.clear
:SAL typ='fun'.clearAndDestroy
:SAL typ='fun'.find
:SAL typ='fun'.index
:SAL typ='omtyp' ocls='WCExcept'.empty_container
:SAL typ='omtyp' ocls='WCExcept'.index_range
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.index
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:SNPF index='index'  .int index( const &lparm. ) const;
:eSNPL.
:SMTICS.
The &fn. is used to determine the index of the first list element equivalent to
the passed element.

.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 ==
until the passed element is found, or all list elements have been checked.

.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.
The index of the first element equivalent to the passed element is returned.
If the passed element is not in the list, negative one (-1) is returned.
:SALSO.
:SAL typ='fun'.contains
:SAL typ='fun'.find
:SAL typ='fun'.get
:eSALSO.
:eLIBF.

.if &lpref. eq Isv .do begin
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.index
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:SNPF index='index'   .int index( int (*test_fn)( const Type *, void * ),
:SNPFLF               .           void * ) const;
:eSNPL.
:SMTICS.
The &fn. is used to determine the index of the first list element for which
the supplied :HP1.test_fn:eHP1. function returns true.  The :HP1.test_fn:eHP1.
function must have the prototype:
:XMPL.
int (*test_fn)( const Type *, void * );
:eXMPL.
:P.
Each list element is passed in turn to the :HP1.test_fn:eHP1. function
as the first argument.  The second parameter passed is the second argument
of the
.MONO index
function.  This allows the :HP1.test_fn:eHP1. callback function to
accept data appropriate for the point at which the
.MONO index
function is invoked.
The supplied :HP1.test_fn:eHP1. shall return a TRUE (non-zero) value when the
index of the passed element is desired.
Otherwise, a FALSE (zero) value shall be returned.
:RSLTS.
The index of the first list element for which the :HP1.test_fn:eHP1.
function returns non-zero is returned.
If the :HP1.test_fn:eHP1. function returns zero for all list elements,
negative one (-1) is returned.
:SALSO.
:SAL typ='fun'.contains
:SAL typ='fun'.find
:SAL typ='fun'.get
:eSALSO.
:eLIBF.
.do end

:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.insert
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
.if &lpref. eq Val .do begin
:SNPF index='insert'    .int insert( const &lparm. );
.do end
.el .do begin
:SNPF index='insert'    .int insert( &lparm. );
.do end
:eSNPL.
:SMTICS.
.if &lpref. ne Isv .th .do begin

The &fn. is used to insert the data
as the first element 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 insert fails, the exception is thrown.
:RSLTS.
The data element is inserted into the beginning of the list.  A TRUE value
(non-zero) is returned if the insert is successful.  A FALSE (zero)
result is returned if the insert fails.

.do end
.el .do begin

The &fn. is used to insert the list element
object to the beginning 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 inserted as the first element of the list and a TRUE value
(non-zero) is returned.

.do end
:SALSO.
:SAL typ='fun'.append
.if &lpref ne Isv .do begin
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
.do end
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.isEmpty
:SNPL.
:SNPFLF               .#include <wclist.h>
:SNPFLF               .public:
:MFN index='isEmpty'  .int isEmpty() const;
:eSNPL.
:SMTICS.
The &fn. is used to determine if a list object has any list elements
contained in it.
:RSLTS.
A TRUE value (non-zero) is returned
if the list object does not have any list elements contained within it.
A FALSE (zero) result is returned if the list contains at least one element.
:SALSO.
:SAL typ='fun'.entries
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='&lacc.'.operator =
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .&lacc.:
:SNPF index='operator ='.WC&lpref.SList & WC&lpref.SList::operator =( const WC&lpref.SList & );
:SNPF index='operator ='.WC&lpref.DList & WC&lpref.DList::operator =( const WC&lpref.DList & );
:eSNPL.
:SMTICS.
The &fn. is the assignment operator for the class.
.if &lpref. eq Isv .th .do begin

Since making a copy of the list object would result in a error condition,
it is made inaccessible by making it a private operator.

.do end
.el .do begin

The left hand side of the assignment is first cleared with the
.MONO clear
member function.  All elements in the right hand side list are then
copied, 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 right hand side list, 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. assigns the right hand side to the left hand side and returns
a reference to the left hand side.
:SALSO.
:SAL typ='fun'.WC&lpref.SList
:SAL typ='fun'.WC&lpref.DList
:SAL typ='fun'.clear
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.

.do end
.* if not Isv
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator ==
:SNPL.
:SNPFLF          .#include <wclist.h>
:SNPFLF          .public:
:SNPF index='operator =='.int WC&lpref.SList::operator ==( const WC&lpref.SList & ) const;
:SNPF index='operator =='.int WC&lpref.DList::operator ==( const WC&lpref.DList & ) const;
:eSNPL.
:SMTICS.
The &fn. is the equivalence operator for the &cls.:PERIOD.
Two list objects are equivalent if they are the same object and share the
same address.
:RSLTS.
A TRUE (non-zero) value is returned if the left hand side object and the right
hand side objects are the same object.  A FALSE (zero) value is returned
otherwise.
:eLIBF.