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 ValueMapIterator} is used to iterate over the values 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 ValueMapIterator(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 values of a map using the {@link Map#valueIterator} method.
    44   * The 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.valueIterator();
    51   *   // ...
    52   * </code>
    53   *
    54   * @author Simon Wacker
    55   * @author Michael Hermann
    56   */
    57  class org.as2lib.data.holder.map.ValueMapIterator extends BasicClass implements Iterator {
    58  	
    59  	/** The target map to iterate over. */
    60  	private var target:Map;
    61  	
    62  	/** The iterator used as a helper. */
    63  	private var iterator:ArrayIterator;
    64  	
    65  	/** The presently selected key. */
    66  	private var key;
    67  	
    68  	/**
    69  	 * Constructs a new {@code ValueMapIterator} instance.
    70  	 * 
    71  	 * @param target the map to iterate over
    72  	 * @throws IllegalArgumentException if the passed-in {@code target} map is {@code null}
    73  	 * or {@code undefined}
    74  	 */
    75  	public function ValueMapIterator(target:Map) {
    76  		if (!target) throw new IllegalArgumentException("The passed-in target map '" + target + "' is not allowed to be null or undefined.", this, arguments);
    77  		this.target = target;
    78  		iterator = new ArrayIterator(target.getKeys());
    79  	}
    80  	
    81  	/**
    82  	 * Returns whether there exists another value to iterate over.
    83  	 * 
    84  	 * @return {@code true} if there is at least one value left to iterate over
    85  	 */
    86  	public function hasNext(Void):Boolean {
    87  		return iterator.hasNext();
    88  	}
    89  	
    90  	/**
    91  	 * Returns the next value.
    92  	 * 
    93  	 * @return the next value
    94  	 * @throws org.as2lib.data.holder.NoSuchElementException if there is no next value
    95  	 */
    96  	public function next(Void) {
    97  		key = iterator.next();
    98  		return target.get(key);
    99  	}
   100  	
   101  	/**
   102  	 * Removes the currently selected key-value pair from this iterator and from the
   103  	 * map this iterator iterates over.
   104  	 * 
   105  	 * @throws org.as2lib.env.except.IllegalStateException if you try to remove a
   106  	 * key-value pair when none is selected
   107  	 */
   108  	public function remove(Void):Void {
   109  		iterator.remove();
   110  		target.remove(key);
   111  	}
   112  	
   113  }
as2api