wchashst.gml

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

:SAL typ='fun'.isEmpty
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.find
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='find'      .int find( const Type &, Type & ) const;
.do end
.el .do begin
:SNPF index='find'      .Type * find( const Type * ) const;
.do end
:eSNPL.
:SMTICS.
The &fn. is used to find an element with an equivalent key in the hash.
If an equivalent element is found,
.if &lpref. eq Val .do begin
a non-zero value
.do end
.el .do begin
a pointer to the element
.do end
is returned.
.if &lpref. eq Val .do begin
The reference to the element
passed as the second argument is assigned the found element's value.
.do end
Zero is returned if the element is not found.
:INCLUDE file='_valequ.gml'
:RSLTS.
The element equivalent to the passed key is located in the hash.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.forAll
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='forAll'    .void forAll(
:SNPFLF                 .      void (*user_fn)( Type, void * ),
:SNPFLF                 .      void * );
.do end
.el .do begin
:SNPF index='forAll'    .void forAll(
:SNPFLF                 .      void (*user_fn)( Type *, void * ),
:SNPFLF                 .      void * );
.do end
:eSNPL.
:SMTICS.
The &fn. causes the user supplied function to be invoked for every value
in the hash.
The user function has the prototype
:XMPL.
.if &lpref. eq Val .do begin
void user_func( Type & value, void * data );
.do end
.el .do begin
void user_func( Type * value, void * data );
.do end
:eXMPL.
As the elements are visited, the user function is invoked with the
element passed as the first.
The second parameter of the
.MONO forAll
function is passed as the second parameter to the user function.
This value can be used to pass any appropriate data from the main code to the
user function.
:RSLTS.
The elements in the hash are all visited, with the user function
being invoked for each one.
:SALSO.
:SAL typ='fun'.find
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.insert
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
.if &lpref. eq Val .do begin
:SNPF index='insert'       .int insert( const Type & );
.do end
.el .do begin
:SNPF index='insert'       .int insert( Type * );
.do end
:eSNPL.
:SMTICS.
The &fn. inserts
a value into the hash, using the hash function to
determine to which bucket it should be stored.
If allocation of the
node to store the value fails, then the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled.
If the exception is not enabled, the insert will not be completed.
:P.
With a
.MONO WC&lpref.HashSet,
there must be only one equivalent element in the set.
If an element equivalent to the inserted element is already
in the hash set, the hash set will remain unchanged, and the
.MONO not_unique
.ix not_unique exception
exception is thrown if it is enabled.
If the exception is not enabled, the insert will not be completed.
:P.
At some point, the number of buckets initially selected may be too small
for the number of elements inserted.
The resize of the hash can be controlled by the insertion mechanism
by using
.MONO WC&lpref.HashSet
(or
.MONO WC&lpref.HashTable
.ct )
as a base class, and providing an insert member function to
do a resize when appropriate.
This insert could then call
.MONO WC&lpref.HashSet::insert
(or
.MONO WC&lpref.HashTable::insert
.ct )
to insert the element.
Note that copy constructors and assignment operators are not
inherited in your class, but you can provide the following inline
definitions (assuming that the class inherited
from WC&lpref.HashTable is named MyHashTable):
:XMPL.
inline MyHashTable( const MyHashTable &orig )
     : WC&lpref.HashTable( orig ) {};
inline MyHashTable &operator=( const MyHashTable &orig ) {
    return( WC&lpref.HashTable::operator=( orig ) );
}
:eXMPL.
:RSLTS.
The &fn. inserts a value into the hash.
If the insert is successful, a non-zero will returned.
A zero will be returned if the insert fails.
:SALSO.
:SAL typ='fun'.operator~b=
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.isEmpty
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='isEmpty'   .int isEmpty() const;
:eSNPL.
:SMTICS.
The &fn. is used to determine if the hash is empty.
:RSLTS.
The &fn. returns zero if it contains at least one entry,
non-zero if the hash is empty.
:SALSO.
:SAL typ='fun'.buckets
:SAL typ='fun'.entries
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF cltype='WC&lpref.HashTable<Type>' fmt='mfun' prot='public'.occurencesOf
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='occurrencesOf' .unsigned occurrencesOf( const Type & ) const;
.do end
.el .do begin
:SNPF index='occurrencesOf' .unsigned occurrencesOf( const Type * ) const;
.do end
:eSNPL.
:SMTICS.
The &fn. is used to return the current number of elements
stored in the hash which are equivalent to the passed value.
:INCLUDE file='_valequ.gml'
:RSLTS.
The &fn. returns the number of elements in the hash.
:SALSO.
:SAL typ='fun'.buckets
:SAL typ='fun'.entries
:SAL typ='fun'.find
:SAL typ='fun'.isEmpty
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator =
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
:SNPF index='operator ='   .WC&lpref.HashSet & operator =( const WC&lpref.HashSet & );
:SNPF index='operator ='   .WC&lpref.HashTable & operator =( const WC&lpref.HashTable & );
:eSNPL.
:SMTICS.
The &fn. is the assignment operator for the &cls.:PERIOD.
The left hand side hash is first cleared using the
.MONO clear
member function, and then the right hand side hash is copied.
The hash function, exception trap states, and all of the hash
elements are copied.
If an allocation failure occurs when creating the buckets, the
table will be created with zero buckets, and the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled.
If there is not enough memory to copy all of
the values or pointers in the hash, then only some will be copied, and the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled.
The number of entries will correctly reflect the number copied.
:RSLTS.
The &fn. assigns the left hand side hash to be a copy of the
right hand side.
:SALSO.
:SAL typ='fun'.clear
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator ==
:SNPL.
:SNPFLF          .#include <wchash.h>
:SNPFLF          .public:
:SNPF index='operator =='.int operator ==( const WC&lpref.HashSet & ) const;
:SNPF index='operator =='.int operator ==( const WC&lpref.HashTable & ) const;
:eSNPL.
:SMTICS.
The &fn. is the equivalence operator for the &cls.:PERIOD.
Two hash 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 hash are the same object.  A FALSE (zero) value is returned
otherwise.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.remove
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='remove'    .int remove( const Type & );
.do end
.el .do begin
:SNPF index='remove'    .Type * remove( const Type * );
.do end
:eSNPL.
:SMTICS.
The &fn. is used to remove the specified element from the hash.
If an equivalent element is found,
.if &lpref. eq Val .do begin
a non-zero
.do end
.el .do begin
the pointer
.do end
value is returned.
Zero is returned if the element is not found.
If the hash is a table and there is more than one element equivalent
to the specified element, then the first equivalent element added to the table
is removed.
:INCLUDE file='_valequ.gml'
:RSLTS.
The element is removed from the hash if it found.
:eLIBF.
:CMT.======================================================================
:LIBF cltype='WC&lpref.HashTable<Type>' fmt='mfun' prot='public'.removeAll
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='removeAll' .unsigned removeAll( const Type & );
.do end
.el .do begin
:SNPF index='removeAll' .unsigned removeAll( const Type * );
.do end
:eSNPL.
:SMTICS.
The &fn. is used to remove all elements equivalent to the
specified element from the hash.
Zero is returned if no equivalent elements are found.
:INCLUDE file='_valequ.gml'
:RSLTS.
All equivalent elements are removed from the hash.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.resize
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='resize'    .void resize( unsigned );
:eSNPL.
:SMTICS.
The &fn. is used to change the number of buckets contained in the hash.
If the new number is larger than the previous hash size, then the
hash function will be used on all of the stored elements to determine
which bucket they should be stored into.
Entries are not destroyed or created in the process of being moved.
If there is not enough memory to resize the hash, the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled, and the hash will contain
the number of buckets it contained before the resize.
If the new number is zero, then the
.MONO zero_buckets
.ix zero_buckets exception
exception is thrown if it is enabled, and no resize will be performed.
The hash is guaranteed to contain the same number of entries after
the resize.
:RSLTS.
The hash is resized to the new number of buckets.
:SALSO.
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:SAL typ='omtyp' ocls='WCExcept'.zero_buckets
:eSALSO.
:eLIBF.