gee/map.vala

   1 /* map.vala
   2  *
   3  * Copyright (C) 2007  Jürg Billeter
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA
  18  *
  19  * Author:
  20  *      Jürg Billeter <j@bitron.ch>
  21  */
  22
  23 /**
  24  * An object that maps keys to values.
  25  */
  26 [GenericAccessors]
  27 public interface Gee.Map<K,V> : Object, Iterable<Map.Entry<K,V>> {
  28         /**
  29          * The number of items in this map.
  30          */
  31         public abstract int size { get; }
  32
  33         /**
  34          * Specifies whether this map is empty.
  35          */
  36         public virtual bool is_empty { get { return size == 0; } }
  37
  38         /**
  39          * Specifies whether this collection can change - i.e. wheather {@link set},
  40          * {@link remove} etc. are legal operations.
  41          */
  42         public abstract bool read_only { get; }
  43
  44         /**
  45          * The read-only view of the keys of this map.
  46          */
  47         public abstract Set<K> keys { owned get; }
  48
  49         /**
  50          * The read-only view of the values of this map.
  51          */
  52         public abstract Collection<V> values { owned get; }
  53
  54         /**
  55          * The read-only view of the entries of this map.
  56          */
  57         public abstract Set<Entry<K,V>> entries { owned get; }
  58
  59         /**
  60          * An entry of a map.
  61          */
  62         public abstract class Entry<K,V> : Object {
  63                 /**
  64                  * The key of this entry.
  65                  */
  66                 public abstract K key { get; }
  67
  68                 /**
  69                  * The value of this entry.
  70                  */
  71                 public abstract V value { get; set; }
  72
  73                 /**
  74                  * ``true`` if the setting value is permitted.
  75                  */
  76                 public abstract bool read_only { get; }
  77         }
  78
  79         /**
  80          * Determines whether this map has the specified key.
  81          *
  82          * @param key the key to locate in the map
  83          *
  84          * @return    ``true`` if key is found, ``false`` otherwise
  85          */
  86         public abstract bool has_key (K key);
  87
  88         /**
  89          * Determines whether this map contains the specified key.
  90          *
  91          * @param key the key to locate in the map
  92          *
  93          * @return    ``true`` if key is found, ``false`` otherwise
  94          */
  95         [Deprecated (replacement = "Map.has_key")]
  96         public bool contains (K key) {
  97                 return has_key(key);
  98         }
  99
 100         /**
 101          * Determines whether this map has the specified key/value entry.
 102          *
 103          * @param key the key to locate in the map
 104          * @param value the corresponding value
 105          *
 106          * @return    ``true`` if key is found, ``false`` otherwise
 107          */
 108         public abstract bool has (K key, V value);
 109
 110         /**
 111          * Returns the value of the specified key in this map.
 112          *
 113          * @param key the key whose value is to be retrieved
 114          *
 115          * @return    the value associated with the key, or ``null`` if the key
 116          *            couldn't be found
 117          */
 118         public abstract V? get (K key);
 119
 120         /**
 121          * Inserts a new key and value into this map.
 122          *
 123          * @param key   the key to insert
 124          * @param value the value to associate with the key
 125          */
 126         public abstract void set (K key, V value);
 127
 128         /**
 129          * Removes the specified key from this map.
 130          *
 131          * @param key   the key to remove from the map
 132          * @param value the receiver variable for the removed value
 133          *
 134          * @return    ``true`` if the map has been changed, ``false`` otherwise
 135          */
 136         public abstract bool unset (K key, out V? value = null);
 137
 138         /**
 139          * Removes the specified key from this map.
 140          *
 141          * @param key   the key to remove from the map
 142          * @param value the receiver variable for the removed value
 143          *
 144          * @return    ``true`` if the map has been changed, ``false`` otherwise
 145          */
 146         [Deprecated (replacement = "Map.unset")]
 147         public bool remove (K key, out V? value = null) {
 148                 return unset (key, out value);
 149         }
 150
 151         /**
 152          * Removes all items from this collection. Must not be called on
 153          * read-only collections.
 154          */
 155         public abstract void clear ();
 156
 157         /**
 158          * Returns an iterator for this map.
 159          *
 160          * @return a map iterator
 161          */
 162         public abstract MapIterator<K,V> map_iterator ();
 163
 164         /**
 165          * Inserts all items that are contained in the input map to this map.
 166          *
 167          * @param map the map which items are inserted to this map
 168          */
 169         public virtual void set_all (Map<K,V> map) {
 170                 foreach (Map.Entry<K,V> entry in map.entries) {
 171                         set (entry.key, entry.value);
 172                 }
 173         }
 174
 175         /**
 176          * Removes all items from this map that are common to the input map
 177          * and this map.
 178          *
 179          * @param map the map which common items are deleted from this map
 180          */
 181         public virtual bool unset_all (Map<K,V> map) {
 182                 bool changed = false;
 183                 foreach (K key in map.keys) {
 184                         changed = changed | unset (key);
 185                 }
 186                 return changed;
 187         }
 188
 189         /**
 190          * Removes all items from this map that are common to the input map
 191          * and this map.
 192          *
 193          * @param map the map which common items are deleted from this map
 194          */
 195         [Deprecated (replacement = "Map.unset_all")]
 196         public bool remove_all (Map<K,V> map) {
 197                 return unset_all (map);
 198         }
 199
 200         /**
 201          * Returns ``true`` it this map contains all items as the input map.
 202          *
 203          * @param map the map which items will be compared with this map
 204          */
 205         public virtual bool has_all (Map<K,V> map) {
 206                 foreach (Map.Entry<K,V> entry in map.entries) {
 207                         if (!has (entry.key, entry.value)) {
 208                                 return false;
 209                         }
 210                 }
 211                 return true;
 212         }
 213
 214         /**
 215          * Returns ``true`` it this map contains all items as the input map.
 216          *
 217          * @param map the map which items will be compared with this map
 218          */
 219         [Deprecated (replacement = "Map.has_all")]
 220         public bool contains_all (Map<K,V> map) {
 221                 return has_all (map);
 222         }
 223
 224         /**
 225          * The read-only view this map.
 226          */
 227         public abstract Map<K,V> read_only_view { owned get; }
 228
 229         /**
 230          * The type of the keys in this map.
 231          */
 232         public Type key_type { get { return typeof(K); } }
 233
 234         /**
 235          * The type of the values in this map.
 236          */
 237         public Type value_type { get { return typeof(V); } }
 238
 239         /**
 240          * Returns an immutable empty map.
 241          *
 242          * @return an immutable empty map
 243          */
 244         public static Map<K,V> empty<K,V> () {
 245                 return new HashMap<K,V> ().read_only_view;
 246         }
 247 }
 248