wchashst.gml

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

The call to the
.MONO WC&lpref.HashSet<Type>
destructor destroys a
.MONO WC&lpref.HashSet
object.
:SALSO.
:SAL typ='fun'.clear
.if &lpref. eq Ptr .do begin
:SAL typ='fun'.clearAndDestroy
.do end
:SAL typ='omtyp' ocls='WCExcept'.not_empty
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.HashTable<Type>' fmt='ctor' prot='public'.WC&lpref.HashTable
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
:SNPCD cd_idx='c'.WC&lpref.HashTable( unsigned (*hash_fn)( const Type & ),
:SNPFLF          .            unsigned = WC_DEFAULT_HASH_SIZE );
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.HashTable<Type>
constructor creates a
.MONO WC&lpref.HashTable
object with no entries and with the number of buckets
in the second optional parameter, which defaults to the constant
.MONO WC_DEFAULT_HASH_SIZE
(currently defined as 101).
The number of buckets specified must be greater than zero, and will be forced
to at least one.
If the hash object can be created, but an allocation failure
occurs when creating the buckets, the
table will be created with zero buckets.
If the
.MONO out_of_memory
.ix out_of_memory exception
exception is enabled, then attempting to insert into a hash
table with zero buckets with throw an
.MONO out_of_memory
error.
:P.
The hash function
.MONO hash_fn
is used to determine which bucket each value will be assigned to.
If no hash function exists, the
static member function
.MONO bitHash
is available to help create one.

:RSLTS.
The
.MONO WC&lpref.HashTable<Type>
constructor creates an initialized
.MONO WC&lpref.HashTable
object with the specified number of buckets and
hash function.
:SALSO.
:SAL typ='fun'.~~WC&lpref.HashTable
:SAL typ='fun'.bitHash
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.HashTable<Type>' fmt='ctor' prot='public'.WC&lpref.HashTable
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
:SNPCD cd_idx='c'.WC&lpref.HashTable( unsigned (*hash_fn)( const Type & ),
:SNPFLF          .            unsigned = WC_DEFAULT_HASH_SIZE,
:SNPFLF          .            void * (*user_alloc)( size_t ),
:SNPFLF          .            void (*user_dealloc)( void *, size_t ) );
:eSNPL.
:SMTICS.
Allocator and deallocator functions are specified
for use when entries are inserted and removed from the hash.
The semantics of this constructor are the same as the constructor without
the memory management functions.
:P.
The allocation function must return a
zero if it cannot perform the allocation.
The deallocation function is passed the size as well
as the pointer to the data.
Your allocation system may take advantage of the characteristic that
the allocation function will always be called with the same size
value for any particular instantiation of a hash.
To determine the size of
the objects that the memory management functions will be
required to allocate and free, the following macro may be used:
.br
.MONO WC&lpref.HashTableItemSize( Type )
:RSLTS.
The
.MONO WC&lpref.HashTable<Type>
constructor creates an initialized
.MONO WC&lpref.HashTable
object with the specified number of buckets and
hash function.
:SALSO.
:SAL typ='fun'.~~WC&lpref.HashTable
:SAL typ='fun'.bitHash
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.HashTable<Type>' fmt='ctor' prot='public'.WC&lpref.HashTable
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
:SNPCD cd_idx='c'.WC&lpref.HashTable( const WC&lpref.HashTable & );
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.HashTable<Type>
is the copy constructor for the
.MONO WC&lpref.HashTable
class.
The new hash is created with the same number of buckets, hash function,
all values or pointers stored in the hash, and the exception trap states.
If the hash object can be created, but an allocation failure
occurs when creating the buckets, the
hash will be created with zero buckets.
If there is not enough memory to copy all of
the values, then only some will be copied,
and the number of entries will correctly reflect the number copied.
If all of the elements cannot be copied, then the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled.
:RSLTS.
The
.MONO WC&lpref.HashTable<Type>
constructor creates a
.MONO WC&lpref.HashTable
object which is a copy of the passed hash.
:SALSO.
:SAL typ='fun'.~~WC&lpref.HashTable
:SAL typ='fun'.operator~b=
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.========================================================================
:LIBF cltype='WC&lpref.HashTable<Type>' fmt='dtor' prot='public'.~~WC&lpref.HashTable
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
:SNPCD cd_idx='d'.virtual ~~WC&lpref.HashTable();
:eSNPL.
:SMTICS.
The
.MONO WC&lpref.HashTable<Type>
destructor is the destructor for the
.MONO WC&lpref.HashTable
class.
If the number of elements is not zero and the
.MONO not_empty
.ix not_empty exception
exception is enabled, the exception is thrown.
Otherwise, the hash elements are cleared using the
.MONO clear
member function.
.if &lpref. eq Ptr .do begin
The objects which the hash elements point to are not deleted unless the
.MONO clearAndDestroy
member function is explicitly called before the destructor is called.
.do end
The call to the
.MONO WC&lpref.HashTable<Type>
destructor is inserted implicitly by the compiler
at the point where the
.MONO WC&lpref.HashTable
object goes out of scope.
:RSLTS.
The call to the
.MONO WC&lpref.HashTable<Type>
destructor destroys a
.MONO WC&lpref.HashTable
object.
:SALSO.
:SAL typ='fun'.clear
.if &lpref. eq Ptr .do begin
:SAL typ='fun'.clearAndDestroy
.do end
:SAL typ='omtyp' ocls='WCExcept'.not_empty
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.bitHash
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='bitHash'   .static unsigned bitHash( void *, size_t );
:eSNPL.
:SMTICS.
The &fn. can be used to implement a hashing function for any type.
A hashing value is generated from the value stored for the
number of specified bytes pointed to by the first parameter.
.if &lpref. eq Val .do begin
For example:
:XMPL.
unsigned my_hash_fn( const int & elem ) {
    return( WCValHashSet<int,String>::bitHash(&elem, sizeof(int));
}
WCValHashSet<int> data_object( &my_hash_fn );
:eXMPL.
.do end
:RSLTS.
The &fn. returns an unsigned value which can be used as the basis of
a user defined hash function.
:SALSO.
:SAL typ='fun'.WC&lpref.HashSet
:SAL typ='fun'.WC&lpref.HashTable
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.buckets
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='buckets'   .unsigned buckets() const;
:eSNPL.
:SMTICS.
The &fn. is used to find the number of buckets contained in
the hash object.
:RSLTS.
The &fn. returns the number of buckets in the hash.
:SALSO.
:SAL typ='fun'.resize
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.clear
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='clear'     .void clear();
:eSNPL.
:SMTICS.
The &fn. is used to clear the hash so that it has no entries.
The number of buckets remain unaffected.
.if &lpref. eq Val .do begin
Elements stored in the hash are destroyed using
the destructors of
.MONO Type.
.do end
.el .do begin
Objects pointed to by the hash elements are not deleted.
.do end
The hash object is not destroyed and re-created by this function, so
the object destructor is not invoked.
:RSLTS.
The &fn. clears the hash to have no elements.
:SALSO.
:SAL typ='fun'.~~WC&lpref.HashSet
:SAL typ='fun'.~~WC&lpref.HashTable
.if &lpref. eq Ptr .do begin
:SAL typ='fun'.clearAndDestroy
.do end
:SAL typ='fun'.operator~b=
:eSALSO.
:eLIBF.

.if &lpref. eq Ptr .do begin
:CMT.======================================================================
:LIBF fmt='mfun' cllong='yes' prot='public'.clearAndDestroy
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='clearAndDestroy'   .void clearAndDestroy();
:eSNPL.
:SMTICS.
The &fn. is used to clear the hash and delete
the objects pointed to by the hash elements.
The hash object is not destroyed and re-created by this function, so
the hash object destructor is not invoked.
:RSLTS.
The &fn. clears the hash by deleting the objects pointed to by the
hash elements.
:SALSO.
:SAL typ='fun'.clear
:eSALSO.
:eLIBF.
.do end

:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.contains
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref eq Val .do begin
:SNPF index='contains'  .int contains( const Type & ) const;
.do end
.el .do begin
:SNPF index='contains'  .int contains( const Type * ) const;
.do end
:eSNPL.
:SMTICS.
The &fn.
returns non-zero if the element is stored in
the hash, or zero if there is no equivalent element.
:INCLUDE file='_valequ.gml'
:RSLTS.
The &fn. returns a non-zero value if the element is found in the hash.
:SALSO.
:SAL typ='fun'.find
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.entries
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='entries'   .unsigned entries() const;
:eSNPL.
:SMTICS.
The &fn. is used to return the current number of elements
stored in the hash.
:RSLTS.
The &fn. returns the number of elements in the hash.
:SALSO.
:SAL typ='fun'.buckets