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.core.BasicClass;
    18  import org.as2lib.env.except.IllegalArgumentException;
    19  import org.as2lib.data.holder.Iterator;
    20  import org.as2lib.data.holder.array.ArrayIterator;
    21  import org.as2lib.data.holder.Map;
    22  
    23  /**
    24   * {@code KeyMapIterator} is used to iterate over the keys of a map.
    25   * 
    26   * <p>This iterator is quite simple to use. There is one method to check whether
    27   * there are more elements left to iterate over {@link #hasNext}, one method to get
    28   * the next element {@link #next} and one to remove the current element {@link #remove}.
    29   *
    30   * <p>Example:
    31   * <code>
    32   *   var map:Map = new HashMap();
    33   *   map.put("key1", 1);
    34   *   map.put("key2", 2);
    35   *   map.put("key3", 3);
    36   *   var iterator:Iterator = new KeyMapIterator(map);
    37   *   while (iterator.hasNext()) {
    38   *       trace(iterator.next());
    39   *   }
    40   * </code>
    41   *
    42   * <p>You normally do not use this class directly, but obtain an iterator that
    43   * iterates over the keys of a map using the {@link Map#keyIterator} method. The
    44   * returned iterator can, but does not have to be an instance of this class.
    45   * 
    46   * <p>Example:
    47   * <code>
    48   *   var map:Map = new HashMap();
    49   *   // ...
    50   *   var iterator:Iterator = map.keyIterator();
    51   *   // ...
    52   * </code>
    53   *
    54   * @author Simon Wacker
    55   */
    56  class org.as2lib.data.holder.map.KeyMapIterator extends BasicClass implements Iterator {
    57  	
    58  	/** The target map to iterate over. */
    59  	private var target:Map;
    60  	
    61  	/** The iterator used as a helper. */
    62  	private var iterator:ArrayIterator;
    63  	
    64  	/** The presently selected key. */
    65  	private var key;
    66  	
    67  	/**
    68  	 * Constructs a new {@code KeyMapIterator} instance.
    69  	 * 
    70  	 * @param target the map to iterate over
    71  	 * @throws IllegalArgumentException if the passed-in {@code target} map is {@code null}
    72  	 * or {@code undefined}
    73  	 */
    74  	public function KeyMapIterator(target:Map) {
    75  		if (!target) throw new IllegalArgumentException("The passed-in target map '" + target + "' is not allowed to be null or undefined.", this, arguments);
    76  		this.target = target;
    77  		iterator = new ArrayIterator(target.getKeys());
    78  	}
    79  	
    80  	/**
    81  	 * Returns whether there exists another key to iterate over.
    82  	 * 
    83  	 * @return {@code true} if there is at least one key left to iterate over
    84  	 */
    85  	public function hasNext(Void):Boolean {
    86  		return iterator.hasNext();
    87  	}
    88  	
    89  	/**
    90  	 * Returns the next key.
    91  	 * 
    92  	 * @return the next key
    93  	 * @throws org.as2lib.data.holder.NoSuchElementException if there is no next key
    94  	 */
    95  	public function next(Void) {
    96  		key = iterator.next();
    97  		return key;
    98  	}
    99  	
   100  	/**
   101  	 * Removes the currently selected key-value pair from this iterator and from the
   102  	 * map this iterator iterates over.
   103  	 * 
   104  	 * @throws org.as2lib.env.except.IllegalStateException if you try to remove a
   105  	 * key-value pair when none is selected
   106  	 */
   107  	public function remove(Void):Void {
   108  		iterator.remove();
   109  		target.remove(key);
   110  	}
   111  	
   112  }
as2api