1 /* 2 * Copyright the original author or authors. 3 * 4 * Licensed under the MOZILLA PUBLIC LICENSE, Version 1.1 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.mozilla.org/MPL/MPL-1.1.html 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 import org.as2lib.data.holder.Iterator; 18 import org.as2lib.core.BasicInterface; 19 20 /** 21 * {@code Map} is the base interface for data holders that map keys to values. 22 * 23 * <p>A map offers two methods that help you find out whether it contains a specific 24 * key or value. These two methods are {@link #containsKey} and {@link #containsValue}. 25 * 26 * <p>To get the data stored in the map you can use the methods {@link #getKeys}, 27 * {@link #getValues} and {@link #get}. If you want to iterate over the values of 28 * the map you can use the iterators returned by the methods {@link #iterator} or 29 * {@link #valueIterator}. If you want to iterate over the keys you can use the 30 * iterator returned by the {@link #keyIterator} method. 31 * 32 * <p>To add key value pairs to the map you can use the methods {@link #put} and 33 * {@link #putAll}. The {@code putAll} method lets you add all key-value pairs 34 * contained in the passed-in {@code map} to this map. 35 * 36 * <p>To remove key-value pairs you can use the methods {@link #remove} and 37 * {@link #clear}. The {@code remove} method deletes only the key-value pair 38 * corresponding to the passed-in {@code key}, while the clear method removes all 39 * key-value pairs. 40 * 41 * <p>There are two more methods you may need. The {@link #isEmpty} and the 42 * {@link #size} method. These methods give you information about whether this 43 * map contains any mappings and how many mappings it contains. 44 * 45 * <p>Example: 46 * <code> 47 * // the map gets set up somewhere 48 * var map:Map = new MyMap(); 49 * map.put("myKey", "myValue"); 50 * // at some different place in your code 51 * if (map.containsKey("myKey")) { 52 * trace(map.get("myKey")); 53 * } 54 * </code> 55 * 56 * @author Simon Wacker 57 * @author Michael Herrmann 58 */ 59 interface org.as2lib.data.holder.Map extends BasicInterface { 60 61 /** 62 * Checks if the passed-in {@code key} exists. 63 * 64 * <p>That means whether a value has been mapped to it. 65 * 66 * @param key the key to be checked for availability 67 * @return {@code true} if the {@code key} exists else {@code false} 68 */ 69 public function containsKey(key):Boolean; 70 71 /** 72 * Checks if the passed-in {@code value} is mapped to a key. 73 * 74 * @param value the value to be checked for availability 75 * @return {@code true} if the {@code value} is mapped to a key else {@code false} 76 */ 77 public function containsValue(value):Boolean; 78 79 /** 80 * Returns an array that contains all keys that have a value mapped to 81 * it. 82 * 83 * @return an array that contains all keys 84 */ 85 public function getKeys(Void):Array; 86 87 /** 88 * Returns an array that contains all values that are mapped to a key. 89 * 90 * @return an array that contains all mapped values 91 */ 92 public function getValues(Void):Array; 93 94 /** 95 * Returns the value that is mapped to the passed-in {@code key}. 96 * 97 * @param key the key to return the corresponding value for 98 * @return the value corresponding to the passed-in {@code key} 99 */ 100 public function get(key); 101 102 /** 103 * Maps the given {@code key} to the {@code value}. 104 * 105 * @param key the key used as identifier for the {@code value} 106 * @param value the value to map to the {@code key} 107 * @return the value that was originally mapped to the {@code key} 108 */ 109 public function put(key, value); 110 111 /** 112 * Copies all mappings from the passed-in {@code map} to this map. 113 * 114 * @param map the mappings to add to this map 115 */ 116 public function putAll(map:Map):Void; 117 118 /** 119 * Removes the mapping from the given {@code key} to the value. 120 * 121 * @param key the key identifying the mapping to remove 122 * @return the value that was originally mapped to the {@code key} 123 */ 124 public function remove(key); 125 126 /** 127 * Clears all mappings. 128 */ 129 public function clear(Void):Void; 130 131 /** 132 * Returns an iterator to iterate over the values of this map. 133 * 134 * @return an iterator to iterate over the values of this map 135 * @see #valueIterator 136 * @see #getValues 137 */ 138 public function iterator(Void):Iterator; 139 140 /** 141 * Returns an iterator to iterate over the values of this map. 142 * 143 * @return an iterator to iterate over the values of this map 144 * @see #iterator 145 * @see #getValues 146 */ 147 public function valueIterator(Void):Iterator; 148 149 /** 150 * Returns an iterator to iterate over the keys of this map. 151 * 152 * @return an iterator to iterate over the keys of this map 153 * @see #getKeys 154 */ 155 public function keyIterator(Void):Iterator; 156 157 /** 158 * Returns the amount of mappings. 159 * 160 * @return the amount of mappings 161 */ 162 public function size(Void):Number; 163 164 /** 165 * Returns whether this map contains any mappings. 166 * 167 * @return {@code true} if this map contains any mappings else {@code false} 168 */ 169 public function isEmpty(Void):Boolean; 170 171 }