content: ///////////////////////////////////////////////////////////////////////////////
  // Copyright (c) 2011, Rob Eden All Rights Reserved.
  //
  // This library is free software; you can redistribute it and/or
  // modify it under the terms of the GNU Lesser General Public
  // License as published by the Free Software Foundation; either
  // version 2.1 of the License, or (at your option) any later version.
  //
  // This library is distributed in the hope that it will be useful,
  // but WITHOUT ANY WARRANTY; without even the implied warranty of
  // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  // GNU General Public License for more details.
  //
  // You should have received a copy of the GNU Lesser General Public
  // License along with this program; if not, write to the Free Software
  // Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  ///////////////////////////////////////////////////////////////////////////////
  
  package gnu.trove.map;
  
  import gnu.trove.function.TObjectFunction;
  import gnu.trove.procedure.TObjectObjectProcedure;
  import gnu.trove.procedure.TObjectProcedure;
  
  import java.util.Map;
  
  
  /**
   * Interface extension to {@link Map} which adds Trove-specific features.
   */
  public interface TMap<K,V> extends Map<K,V> {
  
      /**
       * Inserts a key/value pair into the map if the specified key is not already
       * associated with a value.
       *
       * @param key   an <code>Object</code> value
       * @param value an <code>Object</code> value
       * @return the previous value associated with <tt>key</tt>,
       *         or {@code null} if none was found.
       */
      public V putIfAbsent(K key, V value);
  
  
      /**
       * Executes <tt>procedure</tt> for each key in the map.
       *
       * @param procedure a <code>TObjectProcedure</code> value
       * @return false if the loop over the keys terminated because
       *         the procedure returned false for some key.
       */
      public boolean forEachKey(TObjectProcedure<? super K> procedure);
  
  
      /**
       * Executes <tt>procedure</tt> for each value in the map.
       *
       * @param procedure a <code>TObjectProcedure</code> value
       * @return false if the loop over the values terminated because
       *         the procedure returned false for some value.
       */
      public boolean forEachValue(TObjectProcedure<? super V> procedure);
  
  
      /**
       * Executes <tt>procedure</tt> for each key/value entry in the
       * map.
       *
       * @param procedure a <code>TObjectObjectProcedure</code> value
       * @return false if the loop over the entries terminated because
       *         the procedure returned false for some entry.
       */
      @SuppressWarnings({"unchecked"})
      public boolean forEachEntry(TObjectObjectProcedure<? super K, ? super V> procedure);
  
  
      /**
       * Retains only those entries in the map for which the procedure
       * returns a true value.
       *
       * @param procedure determines which entries to keep
       * @return true if the map was modified.
       */
      @SuppressWarnings({"unchecked"})
      public boolean retainEntries(TObjectObjectProcedure<? super K, ? super V> procedure);
  
  
      /**
       * Transform the values in this map using <tt>function</tt>.
       *
       * @param function a <code>TObjectFunction</code> value
       */
      public void transformValues(TObjectFunction<V, V> function);
  }
  