---

d_Dictionary.h

Go to the documentation of this file.

#ifndef d_Dictionary_h
#define d_Dictionary_h 1

//------------------------------------------------------------------------------
#include "d_Collection.h"

//------------------------------------------------------------------------------
template <class K, class V> class _ODLL d_Association;
template <class T> class _ODLL d_Iterator;
//------------------------------------------------------------------------------

/**
 * It's an unordered collection of associations.
 * 
 * An association is compound of the couple key and value. Key and value can be
 * of any types. It's like to the C++ STL map<> container, but the collection is
 * transparently persistent.
 * 
 * This collection type is useful when items in the collection can be associated
 * with keys. This collection offers methods to retrieve an item by a key.
 *
 * LOCATION:
 * d_Dictionary.h
 *
 * USAGE:
 * d_Dictionary< <key_type>, <value-type> >     <property-name>;
 * 
 * Where:
 * 
 * <key-type >:           Key type. Can be a literal or a user type
 * <value-type >:               Value type. Can be a literal or a user type
 * <PROPERTY-NAME>:     NAME OF PROPERTY
 * 
 * <key-type> must be an ODMG literal or a user type but with the definition of
 *            operator<.
 *
 * EXAMPLES:
 *  * DEFINITION OF A DICTIONARY OF CODE/PRODUCT
 * d_Dictionary< d_String, d_Ref<Product> >     Code_Products;
 * 
 * ...
 * 
 *  * INSERT A PRODUCT WITH ASSOCIATED ITS CODE
 *
 * Code_Products.bind( "10345", product );
 * 
 * ...
 * 
 *  * LOOKUP OF A PRODUUCT BY CODE
 * d_Ref<Product>       product = Code_Products.lookup( "10345" );
 *
 * SEE ALSO:
 * d_Association, d_Collection, d_Iterator
 *
 * ODMG:
 * Compliant 
 */

template <class K, class V>
class _ODLL d_Dictionary : public d_Collection< d_Association<K,V> >
{
  public:

    /**
     * Default Constructor.
     *
     * ODMG    :        Compliant 
     */
    d_Dictionary ();

    /**
     * Destructor.
     *
     * ODMG    :        Compliant 
     */
    ~d_Dictionary();

    /**
     * Insert a new association in the dictionary.
     *
     * Creates a new association between <iKey> and <iValue> and insert it in
     * the dictionary. If an association with key <iKey> is already present in
     * the dictionary, the old value is replaced with the new value <iValue>.
     *
     * SEE ALSO:        unbind(), lookup()
     * ODMG    :        Compliant 
     */
    void bind (const K& iKey, const V& iValue);

    /**
     * Remove an association by the dictionary.
     *
     * If the dictionary contains an association with the key <iKey>, it is
     * removed from the dictionary.
     *
     * SEE ALSO:        bind()
     * ODMG    :        Compliant 
     */
    void unbind (const K& iKey);

    /**
     * Retrieve an association by key.
     *
     * Searches, in the dictionary, the association with key <iKey>. If found
     * returns the value of the association, otherwise a
     * d_Error_ElementNotFound exception is thrown.
     *
     * SEE ALSO:        contains_key()
     * ODMG    :        Compliant 
     */
    V lookup (const K& iKey);

    /**
     * Check if an association is present in the dictionary.
     *
     * Searches, in the dictionary, the association with key <iKey>. If found
     * returns true, otherwise false.
     *
     * SEE ALSO:        lookup()
     * ODMG    :        Compliant 
     */
    d_Boolean contains_key (const K& iKey);

    /**
     * Returns always false.
     *
     * ODMG    :  Compliant 
     */
    virtual d_Boolean allows_duplicates () const;

    /**
     * Returns always false.
     *
     * ODMG    :  Compliant 
     */
    virtual d_Boolean is_ordered () const;

    /**
     * Returns an iterator that points to the first element.
     *
     * SEE ALSO:  begin()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Association<K,V> > create_iterator();

    /**
     * Returns an iterator that points to the first element.
     *
     * Permits to handle the container by STL classes.
     *
     * SEE ALSO:  create_iterator()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Association<K,V> > begin();

    /**
     * Returns an iterator that points to the last element.
     *
     * Permits to handle the container by STL classes.
     *
     * SEE ALSO:  begin()
     * ODMG    :  Compliant
     */
    d_Iterator< d_Association<K,V> > end();
    
    // INTERNAL CONSTRUCTOR
    d_Dictionary( d_Object::DynaFactoryConstructor* iObj ){;}

    d_Iterator< d_Association<K,V> > iter;
};

//------------------------------------------------------------------------------
#include "d_Dictionary.cti"

//------------------------------------------------------------------------------
//------------------------------------------------------------------------------

#endif

---