wchashdi.gml

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

: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 Key & ) const;
.do end
.el .do begin
:SNPF index='contains'  .int contains( const Key * ) const;
.do end
:eSNPL.
:SMTICS.
The &fn.
returns non-zero if an element with the specified key is stored in
the dictionary, or zero if there is no equivalent element.
:INCLUDE file='_keyequ.gml'
:RSLTS.
The &fn. returns a non-zero value if the
.MONO Key
is found in the dictionary.
:SALSO.
:SAL typ='fun'.find
:SAL typ='fun'.findKeyAndValue
: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 dictionary.
:RSLTS.
The &fn. returns the number of elements in the dictionary.
:SALSO.
:SAL typ='fun'.buckets
: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 Key &, Value & ) const;
.do end
.el .do begin
:SNPF index='find'      .Value * find( const Key * ) const;
.do end
:eSNPL.
:SMTICS.
The &fn. is used to find an element with an equivalent key in the dictionary.
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
.MONO Value
.do end
is returned.
.if &lpref. eq Val .do begin
The reference to a
.MONO Value
passed as the second argument is assigned the found element's
.MONO Value.
.do end
Zero is returned if the element is not found.
:INCLUDE file='_keyequ.gml'
:RSLTS.
The element equivalent to the passed key is located in the dictionary.
:SALSO.
:SAL typ='fun'.findKeyAndValue
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.findKeyAndValue
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='findKeyAndValue' .int findKeyAndValue( const Key &, Key &, Value & ) const;
.do end
.el .do begin
:SNPF index='findKeyAndValue'.Value * findKeyAndValue( const Key *,
:SNPFLF                      .                         Key &, Value & ) const;
.do end
:eSNPL.
:SMTICS.
The &fn. is used to find an element in the dictionary with an key
equivalent to the first parameter.
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
.MONO Value
.do end
is returned.
The reference to a
.MONO Key
passed as the second parameter is assigned the found element's key.
.if &lpref. eq Val .do begin
The reference to a
.MONO Value
passed as the third argument is assigned the found element's
.MONO Value.
.do end
Zero is returned if the element is not found.
:INCLUDE file='_keyequ.gml'
:RSLTS.
The element equivalent to the passed key is located in the dictionary.
:SALSO.
:SAL typ='fun'.findKeyAndValue
:eSALSO.
: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)( Key, Value, void * ),
:SNPFLF                 .      void * );
.do end
.el .do begin
:SNPF index='forAll'    .void forAll(
:SNPFLF                 .      void (*user_fn)( Key *, Value *, void * ),
:SNPFLF                 .      void * );
.do end
:eSNPL.
:SMTICS.
The &fn. causes the user supplied function to be invoked for every key-value
pair in the dictionary.
The user function has the prototype
:XMPL.
.if &lpref. eq Val .do begin
void user_func( Key key, Value value, void * data );
.do end
.el .do begin
void user_func( Key * key, Value * value, void * data );
.do end
:eXMPL.
As the elements are visited, the user function is invoked with the
.MONO Key
and
.MONO Value
components of the element passed as the first two parameters.
The second parameter of the
.MONO forAll
function is passed as the third 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 dictionary are all visited, with the user function
being invoked for each one.
:SALSO.
:SAL typ='fun'.find
:SAL typ='fun'.findKeyAndValue
: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 Key &, const Value & );
.do end
.el .do begin
:SNPF index='insert'       .int insert( Key *, Value * );
.do end
:eSNPL.
:SMTICS.
The &fn. inserts
a key and value into the dictionary, using the hash function on the key to
determine to which bucket it should be stored.
If allocation of the
node to store the key-value pair 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.
At some point, the number of buckets initially selected may be too small
for the number of elements inserted.
The resize of the dictionary can be controlled by the insertion mechanism
by using
.MONO WC&lpref.HashDict
as a base class, and providing an insert member function to
do a resize when appropriate.
This insert could then call
.MONO WC&lpref.HashDict::insert
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.HashDict is named MyHashDict):
:XMPL.
inline MyHashDict( const MyHashDict &orig ) : WC&lpref.HashDict( orig ) {};
inline MyHashDict &operator=( const MyHashDict &orig ) {
    return( WC&lpref.HashDict::operator=( orig ) );
}
:eXMPL.
:RSLTS.
The &fn. inserts a key and value into the dictionary.
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 dictionary is empty.
:RSLTS.
The &fn. returns zero if it contains at least one entry,
non-zero if the dictionary is empty.
:SALSO.
:SAL typ='fun'.buckets
:SAL typ='fun'.entries
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.operator []
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
:SNPF index='operator []'     . &lret. & operator[]( const Key & );
:eSNPL.
:SMTICS.
.MONO operator []
is the dictionary index operator.  A reference to the object stored
in the dictionary with the given
.MONO Key
is returned.
If no equivalent element is found, then a new
key-value pair is created with the specified
.MONO Key
value, and initialized with the default constructor.
The returned reference can then be assigned to,
so that insertions can be made with the operator.
.if &lpref. eq Val .do begin
:XMPL
WCValHashDict<int,String> data_object( &my_hash_fn );
data_object[ 5 ] = "Hello";
:eXMPL.
.do end
If an allocation error occurs while inserting a new key-value pair,
then the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled.
If the exception is not enabled, then a reference to address
zero will be returned.
This will result in a run-time error on systems which trap address zero
references.
:RSLTS.
The &fn. returns a reference to the element at the given key value.
If the key does not exist, a reference to a created element is returned.
The result of the operator may be assigned to.
:SALSO.
:SAL typ='omtyp' ocls='WCExcept'.out_of_memory
:eSALSO.
:eLIBF.
:CMT.======================================================================
:LIBF fmt='mfun' prot='public'.operator []
:SNPL.
:SNPFLF                 .#include <wchash.h>
:SNPFLF                 .public:
.if &lpref. eq Val .do begin
:SNPF index='operator []'     .const Value & operator[]( const Key & ) const;
.do end
.el .do begin
:SNPF index='operator []'     .Value * const & operator[]( const Key * ) const;
.do end
:eSNPL.
:SMTICS.
.MONO operator []
is the dictionary index operator.  A constant reference to the object stored
in the dictionary with the given
.MONO Key
is returned.
If no equivalent element is found, then the
.MONO index_range
.ix index_range exception
exception is thrown if it is enabled.
If the exception is not enabled, then a reference to address
zero will be returned.
This will result in a run-time error on systems which trap address zero
references.
:RSLTS.
The &fn. returns a constant reference to the element at the given key value.
The result of the operator may not be assigned to.
:SALSO.
:SAL typ='omtyp' ocls='WCExcept'.index_range
:eSALSO.
:eLIBF.

:CMT.========================================================================
:LIBF fmt='mfun' prot='public'.operator =
:SNPL.
:SNPFLF                    .#include <wchash.h>
:SNPFLF                    .public:
:SNPF index='operator ='   .WC&lpref.HashDict & operator =( const WC&lpref.HashDict & );
:eSNPL.
:SMTICS.
The &fn. is the assignment operator for the &cls.:PERIOD.
The left hand side dictionary is first cleared using the
.MONO clear
member function, and then the right hand side dictionary is copied.
The hash function, exception trap states, and all of the dictionary
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 dictionary, 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 dictionary 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.HashDict & ) const;
:eSNPL.
:SMTICS.
The &fn. is the equivalence operator for the &cls.:PERIOD.
Two dictionary 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 dictionary 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 Key & );
.do end
.el .do begin
:SNPF index='remove'    .Value * remove( const Key * );
.do end
:eSNPL.
:SMTICS.
The &fn. is used to remove the specified element from the dictionary.
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.
:INCLUDE file='_keyequ.gml'
:RSLTS.
The element is removed from the dictionary if it found.
: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 dictionary.
If the new number is larger than the previous dictionary 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 dictionary, the
.MONO out_of_memory
.ix out_of_memory exception
exception is thrown if it is enabled, and the dictionary 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 dictionary is guaranteed to contain the same number of entries after
the resize.
:RSLTS.
The dictionary 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.