3 * Copyright (C) 2007 Jürg Billeter
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.
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.
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
20 * Jürg Billeter <j@bitron.ch>
24 * An object that maps keys to values.
27 public interface Gee.Map<K,V> : Object, Iterable<Map.Entry<K,V>> {
29 * The number of items in this map.
31 public abstract int size { get; }
34 * Specifies whether this map is empty.
36 public virtual bool is_empty { get { return size == 0; } }
39 * Specifies whether this collection can change - i.e. wheather {@link set},
40 * {@link remove} etc. are legal operations.
42 public abstract bool read_only { get; }
45 * The read-only view of the keys of this map.
47 public abstract Set<K> keys { owned get; }
50 * The read-only view of the values of this map.
52 public abstract Collection<V> values { owned get; }
55 * The read-only view of the entries of this map.
57 public abstract Set<Entry<K,V>> entries { owned get; }
62 public abstract class Entry<K,V> : Object {
64 * The key of this entry.
66 public abstract K key { get; }
69 * The value of this entry.
71 public abstract V value { get; set; }
74 * ``true`` if the setting value is permitted.
76 public abstract bool read_only { get; }
80 * Determines whether this map has the specified key.
82 * @param key the key to locate in the map
84 * @return ``true`` if key is found, ``false`` otherwise
86 public abstract bool has_key (K key);
89 * Determines whether this map contains the specified key.
91 * @param key the key to locate in the map
93 * @return ``true`` if key is found, ``false`` otherwise
95 [Deprecated (replacement = "Map.has_key")]
96 public bool contains (K key) {
101 * Determines whether this map has the specified key/value entry.
103 * @param key the key to locate in the map
104 * @param value the corresponding value
106 * @return ``true`` if key is found, ``false`` otherwise
108 public abstract bool has (K key, V value);
111 * Returns the value of the specified key in this map.
113 * @param key the key whose value is to be retrieved
115 * @return the value associated with the key, or ``null`` if the key
118 public abstract V? get (K key);
121 * Inserts a new key and value into this map.
123 * @param key the key to insert
124 * @param value the value to associate with the key
126 public abstract void set (K key, V value);
129 * Removes the specified key from this map.
131 * @param key the key to remove from the map
132 * @param value the receiver variable for the removed value
134 * @return ``true`` if the map has been changed, ``false`` otherwise
136 public abstract bool unset (K key, out V? value = null);
139 * Removes the specified key from this map.
141 * @param key the key to remove from the map
142 * @param value the receiver variable for the removed value
144 * @return ``true`` if the map has been changed, ``false`` otherwise
146 [Deprecated (replacement = "Map.unset")]
147 public bool remove (K key, out V? value = null) {
148 return unset (key, out value);
152 * Removes all items from this collection. Must not be called on
153 * read-only collections.
155 public abstract void clear ();
158 * Returns an iterator for this map.
160 * @return a map iterator
162 public abstract MapIterator<K,V> map_iterator ();
165 * Inserts all items that are contained in the input map to this map.
167 * @param map the map which items are inserted to this map
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);
176 * Removes all items from this map that are common to the input map
179 * @param map the map which common items are deleted from this map
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);
190 * Removes all items from this map that are common to the input map
193 * @param map the map which common items are deleted from this map
195 [Deprecated (replacement = "Map.unset_all")]
196 public bool remove_all (Map<K,V> map) {
197 return unset_all (map);
201 * Returns ``true`` it this map contains all items as the input map.
203 * @param map the map which items will be compared with this map
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)) {
215 * Returns ``true`` it this map contains all items as the input map.
217 * @param map the map which items will be compared with this map
219 [Deprecated (replacement = "Map.has_all")]
220 public bool contains_all (Map<K,V> map) {
221 return has_all (map);
225 * The read-only view this map.
227 public abstract Map<K,V> read_only_view { owned get; }
230 * The type of the keys in this map.
232 public Type key_type { get { return typeof(K); } }
235 * The type of the values in this map.
237 public Type value_type { get { return typeof(V); } }
240 * Returns an immutable empty map.
242 * @return an immutable empty map
244 public static Map<K,V> empty<K,V> () {
245 return new HashMap<K,V> ().read_only_view;