library of assembled shared sources

 http://lass.cocamware.com

lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess > Class Template Reference

a wrapper around a std::map to translate keys in values and back. More...

#include <dictionary.h>


Public Types

typedef KeyType TKey
typedef ValueType TValue
typedef KeyLess TKeyLess
typedef ValueLess TValueLess
typedef std::set< KeyType,
KeyLess > 		TKeys
typedef std::set< ValueType,
ValueLess > 		TValues
typedef CallTraits< KeyType >
::TParam 		TKeyParam
typedef CallTraits< ValueType >
::TParam 		TValueParam

Public Member Functions

 Dictionary ()
 Dictionary (TKeyLess iKeyLess)
 Dictionary (TKeyLess iKeyLess, TValueLess iValueLess)
void add (const TKey &iKey, const TValue &iValue)
 add a key and value to dictionary as new entry.
void remove (const TKey &iKey, const TValue &iValue)
 remove a key and value from the dictionary.
void setDefault (const TKey &iKey, const TValue &iValue)
 set key and value to be used as default ones.
void clearDefault ()
 clear default key and value.
bool hasDefault () const
 return true if dictionary has value
void enableSuggestions (bool enable=true)
 if enabled, suggestions of valid keys or values will be included in the exception that is thrown in case a key or value is not found and there's no default.
const TValue & operator[] (TKeyParam iKey) const
 look up a value by key
const TKey & key (TValueParam iValue) const
 look up a key by value
TKeys keys () const
 return all keys in the dictionary
TValues values () const
 return all values in the dictionary
TKeys keys (TValueParam iValue) const
 return all keys that have value iValue.
TValues values (TKeyParam iKey) const
 return all values in the dictionary
bool isKey (TKeyParam iKey) const
 return true if iKey is a key of dictionary
bool isValue (TValueParam iValue) const
 return true if iValue is a value of dictionary

Private Types

typedef std::multimap< TKey,
TValue, KeyLess > 		TMap

Private Member Functions

bool equalValues (TValueParam iA, TValueParam iB) const

Private Attributes

TMap map_
TKey defaultKey_
TValue defaultValue_
TKeyLess keyLess_
TValueLess valueLess_
bool hasDefault_
bool enableSuggestions_

Detailed Description

template<typename KeyType, typename ValueType, typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
class lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >

a wrapper around a std::map to translate keys in values and back.

Author:
[Bramz]
This utility class has been written for the purpose of translating enumeration values to strings. Enumerations are a handy concept for the programmer to enumerate different options, cases. However, they only have names in code. For the compiler these are just numbers, and if you want to use these enumerations in your user interface you again stumble on the fact that these are nothing but fancy numbers.

This dictionary has been made to make it possible to translate these numbers to text. Typically you'd set up a dictionary that translates each enumeration to a string, and then you use this dictionary as an interface between your code and your user interface. It is also possible to set a default key and value that must be returned in no match can be found during the lookup. This default could indicate for an invalid state.

  #include <lass/util/dictionary.h>

  enum FooBar
  {
      fbInvalid,
      fbEggs,
      fbSpam,
      fbHam
  };
  typedef lass::util::Dictionary<std::string, FooBar> TFooBarDictionary;

  TFooBarDictionary fooBarDictionary;
  fooBarDictionary.add("eggs", fbEggs);
  fooBarDictionary.add("spam", fbSpam);
  fooBarDictionary.add("ham", fbHam);
  fooBarDictionary.setDefault("invalid", fbInvalid);

  // to user interface
  //
  FooBar fooBar = fbEggs;
  LASS_COUT << fooBarDictionary.key(fooBar);

  // from user interface.
  //
  std::string input;
  LASS_CIN >> input;
  fooBar = fooBarDictionary[input];
  if (fooBar == fbInvalid)
  {
      doSomethingSpecial();
  }

To end this discussion, we have one more suggestion to make of this dictionary a singleton. You create a singleton accessor function and you init the dictionary by using LASS_EXECUTE_BEFORE_MAIN.

  #include <lass/util/dictionary.h>
  #include <lass/util/singleton.h>

  enum FooBar
  {
      fbInvalid,
      fbEggs,
      fbSpam,
      fbHam
  };
  typedef lass::util::Dictionary<std::string, FooBar> TFooBarDictionary;

  TFooBarDictionary& fooBarDictionary()
  {
      return *lass::util::Singleton<TFooBarDictionary>::instance();
  }

  LASS_EXECUTE_BEFORE_MAIN
  (
      fooBarDictionary().add("eggs", fbEggs);
      fooBarDictionary().add("spam", fbSpam);
      fooBarDictionary().add("ham", fbHam);
      fooBarDictionary().setDefault("invalid", fbInvalid);
  )

  // ...

  LASS_COUT << fooBarDictionary().key(fbEggs);

Definition at line 149 of file dictionary.h.

Member Typedef Documentation

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef KeyType lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TKey

Definition at line 153 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef ValueType lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TValue

Definition at line 154 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef KeyLess lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TKeyLess

Definition at line 155 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef ValueLess lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TValueLess

Definition at line 156 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef std::set<KeyType, KeyLess> lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TKeys

Definition at line 157 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef std::set<ValueType, ValueLess> lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TValues

Definition at line 158 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef CallTraits<KeyType>::TParam lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TKeyParam

Definition at line 159 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef CallTraits<ValueType>::TParam lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TValueParam

Definition at line 160 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
typedef std::multimap<TKey, TValue, KeyLess> lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::TMap [private]

Definition at line 187 of file dictionary.h.

Constructor & Destructor Documentation

template<typename K , typename V , typename KL , typename VL >
lass::util::Dictionary< K, V, KL, VL >::Dictionary (  )  [inline]

Definition at line 59 of file dictionary.inl.

template<typename K , typename V , typename KL , typename VL >
lass::util::Dictionary< K, V, KL, VL >::Dictionary ( TKeyLess  iKeyLess  )  [inline, explicit]

Definition at line 69 of file dictionary.inl.

template<typename K , typename V , typename KL , typename VL >
lass::util::Dictionary< K, V, KL, VL >::Dictionary ( TKeyLess  iKeyLess,
TValueLess  iValueLess 
) [inline]

Definition at line 80 of file dictionary.inl.

Member Function Documentation

template<typename K , typename V , typename KL , typename VL >
void lass::util::Dictionary< K, V, KL, VL >::add ( const TKey &  iKey,
const TValue &  iValue 
) [inline]

add a key and value to dictionary as new entry.

Definition at line 94 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::equalValues(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_, and lass::stde::range().

template<typename K , typename V , typename KL , typename VL >
void lass::util::Dictionary< K, V, KL, VL >::remove ( const TKey &  iKey,
const TValue &  iValue 
) [inline]

remove a key and value from the dictionary.

Definition at line 112 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::equalValues(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_, and lass::stde::range().

template<typename K , typename V , typename KL , typename VL >
void lass::util::Dictionary< K, V, KL, VL >::setDefault ( const TKey &  iKey,
const TValue &  iValue 
) [inline]

set key and value to be used as default ones.

Once default key and value are set, these will be returned on occasions you try to look up a key or value but it can't be found.

Definition at line 132 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::defaultKey_, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::defaultValue_, and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault_.

template<typename K , typename V , typename KL , typename VL >
void lass::util::Dictionary< K, V, KL, VL >::clearDefault (  )  [inline]

clear default key and value.

If no default key and value are set, and exception will be thrown on occasions you try to look up a key or value but it can't be found.

Definition at line 146 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault_.

template<typename K , typename V , typename KL , typename VL >
bool lass::util::Dictionary< K, V, KL, VL >::hasDefault (  )  const [inline]

return true if dictionary has value

Definition at line 156 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault_.

template<typename K , typename V , typename KL , typename VL >
void lass::util::Dictionary< K, V, KL, VL >::enableSuggestions ( bool  enable = true  )  [inline]

if enabled, suggestions of valid keys or values will be included in the exception that is thrown in case a key or value is not found and there's no default.

Definition at line 167 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::enableSuggestions_.

template<typename K , typename V , typename KL , typename VL >
const Dictionary< K, V, KL, VL >::TValue & lass::util::Dictionary< K, V, KL, VL >::operator[] ( TKeyParam  iKey  )  const [inline]

look up a value by key

Returns:
  • the value that belongs to the key.
  • if such a value can not be found and an default value is set, then this default will be returned.
Note:
if multiple entries with the same key are found, only one is returned. It is not specified which one this will be. If you want all entries with this key, use values(iKey).
Exceptions:
if no value can be found that belongs to the key and no default value is set, then an exception will be thrown.

Definition at line 188 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::defaultValue_, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::enableSuggestions_, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault_, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::keys(), LASS_THROW, and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_.

template<typename K , typename V , typename KL , typename VL >
const Dictionary< K, V, KL, VL >::TKey & lass::util::Dictionary< K, V, KL, VL >::key ( TValueParam  iValue  )  const [inline]

look up a key by value

Returns:
  • the key to which the value belongs
  • if such a key can not be found and an default key is set, then this default will be returned.
Note:
if multiple entries with the same value are found, only one is returned. It is not specified which one this will be. If you want all entries with this value, use keys(iValue).
Exceptions:
if no key can be found to wich the value belongs and no default key is set, then an exception will be thrown.

Definition at line 225 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::defaultKey_, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::enableSuggestions_, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::equalValues(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault_, LASS_THROW, lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_, and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::values().

template<typename K , typename V , typename KL , typename VL >
Dictionary< K, V, KL, VL >::TKeys lass::util::Dictionary< K, V, KL, VL >::keys (  )  const [inline]

return all keys in the dictionary

Definition at line 255 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::operator[]().

template<typename K , typename V , typename KL , typename VL >
Dictionary< K, V, KL, VL >::TValues lass::util::Dictionary< K, V, KL, VL >::values (  )  const [inline]

return all values in the dictionary

Definition at line 271 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::key().

template<typename K , typename V , typename KL , typename VL >
Dictionary< K, V, KL, VL >::TKeys lass::util::Dictionary< K, V, KL, VL >::keys ( TValueParam  iValue  )  const [inline]

return all keys that have value iValue.

Definition at line 287 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::equalValues(), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_.

template<typename K , typename V , typename KL , typename VL >
Dictionary< K, V, KL, VL >::TValues lass::util::Dictionary< K, V, KL, VL >::values ( TKeyParam  iKey  )  const [inline]

return all values in the dictionary

Definition at line 306 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_, and lass::stde::range().

template<typename K , typename V , typename KL , typename VL >
bool lass::util::Dictionary< K, V, KL, VL >::isKey ( TKeyParam  iKey  )  const [inline]

return true if iKey is a key of dictionary

Definition at line 322 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_.

template<typename K , typename V , typename KL , typename VL >
bool lass::util::Dictionary< K, V, KL, VL >::isValue ( TValueParam  iValue  )  const [inline]

return true if iValue is a value of dictionary

Definition at line 332 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::equalValues(), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_.

template<typename K , typename V , typename KL , typename VL >
bool lass::util::Dictionary< K, V, KL, VL >::equalValues ( TValueParam  iA,
TValueParam  iB 
) const [inline, private]

Definition at line 353 of file dictionary.inl.

References lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::valueLess_.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::add(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::isValue(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::key(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::keys(), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::remove().

Field Documentation

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
TMap lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::map_ [private]

Definition at line 191 of file dictionary.h.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::add(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::isKey(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::isValue(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::key(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::keys(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::operator[](), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::remove(), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::values().

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
TKey lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::defaultKey_ [private]

Definition at line 192 of file dictionary.h.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::key(), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::setDefault().

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
TValue lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::defaultValue_ [private]

Definition at line 193 of file dictionary.h.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::operator[](), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::setDefault().

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
TKeyLess lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::keyLess_ [private]

Definition at line 194 of file dictionary.h.

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
TValueLess lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::valueLess_ [private]

Definition at line 195 of file dictionary.h.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::equalValues().

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
bool lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault_ [private]

Definition at line 196 of file dictionary.h.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::clearDefault(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::hasDefault(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::key(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::operator[](), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::setDefault().

template<typename KeyType , typename ValueType , typename KeyLess = std::less<KeyType>, typename ValueLess = std::less<ValueType>>
bool lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::enableSuggestions_ [private]

Definition at line 197 of file dictionary.h.

Referenced by lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::enableSuggestions(), lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::key(), and lass::util::Dictionary< KeyType, ValueType, KeyLess, ValueLess >::operator[]().

The documentation for this class was generated from the following files:
Generated on Mon Nov 10 14:22:17 2008 for Library of Assembled Shared Sources by doxygen 1.5.7.1
 SourceForge.net Logo