wcvectos.gml

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

.do end
:P.
The
.MONO WC&lpref.OrderedVector::insert
function inserts the value as the last element of the vector, and has
the same semantics as the
.MONO WC&lpref.OrderedVector::append
member function.
:P.
A binary search is performed to determine where the value should be inserted
for the
.MONO WC&lpref.SortedVector::insert
function.

.if &lpref. eq Ptr .do begin
Note that comparisons are done on the objects pointed to, not the pointers
themselves.
.do end

Any elements greater than the inserted value are copied up one index

.if &lpref. eq Val .do begin
(using
.MONO Type's
assignment operator),
.do end

so that the new element is after all elements
with value less than or equal to it.
:P.
Several different results can occur if the vector is not large enough for
the new element.
If the
.MONO resize_required
.ix resize_required exception
exception is enabled, the exception is thrown.
If the exception is not enabled, the insert fails if the amount the vector
is to be grown (the second parameter to the constructor) is zero(0).
Otherwise, the vector is automatically grown by
the number of elements specified to the constructor, using the
.MONO resize
member function.
If
.MONO resize
fails, the element is not inserted to the vector and the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown, if enabled.
:RSLTS.
The &fn. inserts an element in to the vector.
A TRUE (non-zero) value is returned if the insert is successful.
If the insert fails, a FALSE (zero) value is returned.
:SALSO.
:SAL typ='fun'.append
:SAL typ='fun'.insertAt
:SAL typ='fun'.prepend
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:SAL typ='omtyp' ocls='WCExcept'.resize_required
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF cltype='WC&lpref.OrderedVector<Type>' fmt='mfun' prot='public'.insertAt
:SNPL.
:SNPFLF                 .#include <wcvector.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='insertAt'      .int insertAt( int, const &lparm. );
.do end
.el .do begin
:SNPF index='insertAt'      .int insertAt( int, &lparm. );
.do end
:eSNPL.
:SMTICS.
The &fn. inserts the second argument into the vector before the element at
index given by the first argument.
If the passed index is equal to the number of entries in the vector, the
new value is appended to the vector as the last element.

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

All vector elements with indexes greater than or equal to the first parameter
are copied

.if &lpref. eq Val .do begin
(using
.MONO Type's
assignment operator)
.do end

up one index.
:P.
This function is not provided by the
.MONO WC&lpref.SortedVector
class, since all elements must be inserted in sorted order by the
.MONO insert
member function.
:P.
If the passed index is negative or greater than the number of entries in
the vector and the
.MONO index_range
.ix index_range exception
exception is enabled, the exception is thrown.  If the exception is not
enabled, the new element is inserted as the first element when the index is
negative, or as the last element when the index is too large.
:P.
Several different results can occur if the vector is not large enough for
the new element.
If the
.MONO resize_required
.ix resize_required exception
exception is enabled, the exception is thrown.
If the exception is not enabled, the insert fails if the amount the vector
is to be grown (the second parameter to the constructor) is zero(0).
Otherwise, the vector is automatically grown by
the number of elements specified to the constructor, using the
.MONO resize
member function.
If
.MONO resize
fails, the element is not inserted into the vector and the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown, if enabled.
:RSLTS.
The &fn. inserts an element into the
.MONO WC&lpref.OrderedVector
object before the element at the given index.
A TRUE (non-zero) value is returned if the insert is successful.
If the insert fails, a FALSE (zero) value is returned.
:SALSO.
:SAL typ='fun'.append
:SAL typ='fun'.insert
:SAL typ='fun'.prepend
:SAL typ='fun'.operator~b[]
:SAL typ='fun'.removeAt
:SAL typ='omtyp' ocls='WCExcept'.index_range
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:SAL typ='omtyp' ocls='WCExcept'.resize_required
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.isEmpty
:SNPL.
:SNPFLF                 .#include <wcvector.h>
:SNPFLF                 .public:
:SNPF index='isEmpty'   .int isEmpty() const;
:eSNPL.
:SMTICS.
The &fn. is used to determine if a vector object has any entries contained
in it.
:RSLTS.
A TRUE value (non-zero) is returned if the vector object does not have any
vector elements contained within it.  A FALSE (zero) result is returned if
the vector contains at least one element.
:SALSO.
:SAL typ='fun'.entries
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.last
:SNPL.
:SNPFLF                 .#include <wcvector.h>
:SNPFLF                 .public:
:SNPF index='last'      .&lret last() const;
:eSNPL.
:SMTICS.
The &fn. returns the last element in the vector.  The element is not removed
from the vector.
:P.
If the vector is empty, one of two exceptions can be thrown.  The
.MONO empty_container
.ix empty_container exception
exception is thrown if it is enabled.  Otherwise, if the
.MONO index_range
.ix index_range exception
exception is enabled, it is thrown.
If neither exception is enabled, a first element of the vector is added

.if &lpref. eq Val .do begin
with a default value.
.do end
.el .do begin
with a NULL value.
.do end

:RSLTS.
The &fn. returns the value of the last element in the vector.
:SALSO.
:SAL typ='fun'.first
:SAL typ='fun'.removeLast
:SAL typ='omtyp' ocls='WCExcept'.index_range
:SAL typ='omtyp' ocls='WCExcept'.resize_required
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.occurrencesOf
:SNPL.
:SNPFLF                 .#include <wcvector.h>
:SNPFLF                 .public:
:SNPF index='occurrencesOf'     .int occurrencesOf( const &lparm. ) const;
:eSNPL.
:SMTICS.
The &fn. returns the number of elements contained in the vector that are
equivalent to the passed value.

.if &lpref eq Ptr .do begin
Note that comparisons are done on the objects pointed to, not the pointers
themselves.
.do end

A linear search is used by the
.MONO WC&lpref.OrderedVector
class to find the value.  The
.MONO WC&lpref.SortedVector
class uses a binary search.
:RSLTS.
The &fn. returns the number of elements equivalent to the passed value.
:SALSO.
:SAL typ='fun'.contains
:SAL typ='fun'.find
:SAL typ='fun'.index
:SAL typ='fun'.operator~b[]
:SAL typ='fun'.removeAll
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.operator []
:SNPL.
:SNPFLF                 .#include <wcvector.h>
:SNPFLF                 .public:
:SNPF index='operator []'     .&lret. & operator []( int );
.if &lpref. eq Val .do begin
:SNPF index='operator []'     .const Type & operator []( int ) const;
.do end
.el .do begin
:SNPF index='operator []'     .Type * const & operator []( int ) const;
.do end
:eSNPL.
:SMTICS.
.MONO operator []
is the vector index operator.  A reference to the object stored
in the vector at the given index is returned.  If a constant vector is
indexed, a reference to a constant element is returned.
:P.
The
.MONO append, insert, insertAt
and
.MONO prepend
member functions are used to insert a new element into a vector, and the
.MONO remove, removeAll, removeAt, removeFirst
and
.MONO removeLast
member functions remove elements.
The index operator cannot be used to change the number of entries in the
vector.
Searches may be performed using the
.MONO find
and
.MONO index
member functions.
:P.
If the vector is empty, one of two exceptions can be thrown.  The
.MONO empty_container
.ix empty_container exception
exception is thrown if it is enabled.  Otherwise, if the
.MONO index_range
.ix index_range exception
exception is enabled, it is thrown.
If neither exception is enabled, a first element of the vector is added

.if &lpref. eq Val .do begin
with a default value.
.do end
.el .do begin
with a NULL value.
.do end

This element is added so that a reference to a valid vector element can
be returned.
:P.
If the index value is negative and the
.MONO index_range
.ix index_range exception
exception is enabled, the exception is thrown.
An attempt to index an element with index greater than or equal to the
number of entries in the vector will also cause the
.MONO index_range
exception to be thrown if enabled.
If the exception is not enabled, attempting to index a negative element will
index the first element in the vector, and attempting to index an element
after the last entry will index the last element.
:P.
Care must be taken when using the
.MONO WC&lpref.SortedVector
class not to change the ordering of the vector
elements.
The result returned by the index operator must not be assigned to or
modified in such a way that it is no longer equivalent (by
.MONO Type's
equivalence operator) to the value inserted into the vector.
Failure to comply may cause lookups to work incorrectly, since
the binary search algorithm assumes elements are in sorted order.
:RSLTS.
The &fn. returns a reference to the element at the given index.
If the index is invalid, a reference to the closest valid element is returned.
The result of the non-constant index operator may be assigned to.
:SALSO.
:SAL typ='fun'.append
:SAL typ='fun'.find
:SAL typ='fun'.first
:SAL typ='fun'.index
:SAL typ='fun'.insert
:SAL typ='fun'.insertAt
:SAL typ='fun'.isEmpty
:SAL typ='fun'.last
:SAL typ='fun'.prepend
:SAL typ='fun'.remove
:SAL typ='fun'.removeAt
:SAL typ='fun'.removeAll
:SAL typ='fun'.removeFirst
:SAL typ='fun'.removeLast
:SAL typ='omtyp' ocls='WCExcept'.empty_container
:SAL typ='omtyp' ocls='WCExcept'.index_range
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.operator =
:SNPL.
:SNPFLF                    .#include <wcvector.h>
:SNPFLF                    .public:
:SNPF index='operator ='   .WC&lpref.OrderedVector & WC&lpref.OrderedVector::operator =( const WC&lpref.OrderedVector & );
:SNPF index='operator ='   .WC&lpref.SortedVector & WC&lpref.SortedVector::operator =( const WC&lpref.SortedVector & );
:eSNPL.
:SMTICS.
The &fn. is the assignment operator for the class.
The left hand side vector is first cleared using the
.MONO clear
member function, and then the right hand side vector is copied.
The left hand side vector is made to have the same length and growth amount
as the right hand side (the growth amount is the second argument passed to
the right hand side vector constructor).
All of the vector elements and exception trap states are copied.
:P.
If the left hand side vector cannot be fully created, it will have
zero length.  The
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if enabled in the right hand side vector.
:RSLTS.
The &fn. assigns the left hand side vector to be a copy of the right hand side.
:SALSO.
:SAL typ='fun'.clear
.if &lpref. eq Ptr .do begin
:SAL typ='fun'.clearAndDestroy
.do end
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.operator ==
:SNPL.
:SNPFLF          .#include <wcvector.h>
:SNPFLF          .public:
:SNPF index='operator =='.int WC&lpref.OrderedVector::operator ==( const WC&lpref.OrderedVector & ) const;
:SNPF index='operator =='.int WC&lpref.SortedVector::operator ==( const WC&lpref.SortedVector & ) const;
:eSNPL.
:SMTICS.
The &fn. is the equivalence operator for the class.
Two vector 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 and right
hand side vectors are the same object.  A FALSE (zero) value is returned
otherwise.
:eLIBF.
:CMT.======================================================================
:LIBF cltype='WC&lpref.OrderedVector<Type>' fmt='mfun' prot='public'.prepend
:SNPL.
:SNPFLF                 .#include <wcvector.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin