// Path: hppc/src/main/templates/com/carrotsearch/hppc/cursors/KTypeVTypeCursor.java
// public final class KTypeVTypeCursor<KType, VType> {
//   /**
//    * The current key and value's index in the container this cursor belongs to.
//    * The meaning of this index is defined by the container (usually it will be
//    * an index in the underlying storage buffer).
//    */
//   public int index;
// 
//   /**
//    * The current key.
//    */
//   public KType key;
// 
//   /**
//    * The current value.
//    */
//   public VType value;
// 
//   @Override
//   public String toString() {
//     return "[cursor, index: " + index + ", key: " + key + ", value: " + value + "]";
//   }
// }


import com.carrotsearch.hppc.cursors.KTypeVTypeCursor;
/*! #set($TemplateOptions.ignored = ($TemplateOptions.isKTypeAnyOf("DOUBLE", "FLOAT", "BYTE"))) !*/
package com.carrotsearch.hppc;


/**
 * An associative container with unique binding from keys to a single value.
 */
/*! ${TemplateOptions.generatedAnnotation} !*/
public interface KTypeVTypeMap<KType, VType> extends KTypeVTypeAssociativeContainer<KType, VType> {
  /**
   * @return Returns the value associated with the given key or the default
   *         value for the value type, if the key is not associated with any
   *         value.  For numeric value types, this default value is 0, for
   *         object types it is {@code null}.
   */
  public VType get(KType key);

  /**
   * @return Returns the value associated with the given key or the provided
   *         default value if the key is not associated with any value.
   */
  public VType getOrDefault(KType key, VType defaultValue);

  /**
   * Place a given key and value in the container.
   * 
   * @return The value previously stored under the given key in the map is
   *         returned.
   */
  public VType put(KType key, VType value);

  /**
   * Puts all keys from another container to this map, replacing the values of
   * existing keys, if such keys are present.
   * 
   * @return Returns the number of keys added to the map as a result of this
   *         call (not previously present in the map). Values of existing keys
   *         are overwritten.
   */
  public int putAll(KTypeVTypeAssociativeContainer<? extends KType, ? extends VType> container);

  /**
   * Puts all keys from an iterable cursor to this map, replacing the values of
   * existing keys, if such keys are present.
   * 
   * @return Returns the number of keys added to the map as a result of this
   *         call (not previously present in the map). Values of existing keys
   *         are overwritten.
   */
  public int putAll(Iterable<? extends KTypeVTypeCursor<? extends KType, ? extends VType>> iterable);

  /*! #if ($TemplateOptions.VTypePrimitive) !*/
  /**
   * If <code>key</code> exists, <code>putValue</code> is inserted into the map,
   * otherwise any existing value is incremented by <code>additionValue</code>.
   * 
   * @param key
   *          The key of the value to adjust.
   * @param putValue
   *          The value to put if <code>key</code> does not exist.
   * @param incrementValue
   *          The value to add to the existing value if <code>key</code> exists.
   * @return Returns the current value associated with <code>key</code> (after
   *         changes).
   */
  public VType putOrAdd(KType key, VType putValue, VType incrementValue);
  /*! #end !*/

  /*! #if ($TemplateOptions.VTypePrimitive) !*/
  /**
   * An equivalent of calling
   * 
   * <pre>
   * putOrAdd(key, additionValue, additionValue);
   * </pre>
   * 
   * @param key
   *          The key of the value to adjust.
   * @param additionValue
   *          The value to put or add to the existing value if <code>key</code>
   *          exists.
   * @return Returns the current value associated with <code>key</code> (after
   *         changes).
   */
  public VType addTo(KType key, VType additionValue);

  /*! #end !*/

  /**
   * Remove all values at the given key. The default value for the key type is
   * returned if the value does not exist in the map.
   */
  public VType remove(KType key);

  /**
   * Compares the specified object with this set for equality. Returns
   * {@code true} if and only if the specified object is also a
   * {@link KTypeVTypeMap} and both objects contains exactly the same key-value
   * pairs.
   */
  public boolean equals(Object obj);

  /**
   * @return A hash code of elements stored in the map. The hash code is defined
   *         as a sum of hash codes of keys and values stored within the set).
   *         Because sum is commutative, this ensures that different order of
   *         elements in a set does not affect the hash code.
   */
  public int hashCode();

  /**
   * Returns a logical "index" of a given key that can be used to speed up
   * follow-up value setters or getters in certain scenarios (conditional
   * logic).
   * 
   * The semantics of "indexes" are not strictly defined. Indexes may (and
   * typically won't be) contiguous.
   * 
   * The index is valid only between map modifications (it will not be affected
   * by read-only operations like iteration or value retrievals).
   * 
   * @see #indexExists
   * @see #indexGet
   * @see #indexInsert
   * @see #indexReplace
   * 
   * @param key
   *          The key to locate in the map.
   * @return A non-negative value of the logical "index" of the key in the map
   *         or a negative value if the key did not exist.
   */
  public int indexOf(KType key);

  /**
   * @see #indexOf
   * 
   * @param index
   *          The index of a given key, as returned from {@link #indexOf}.
   * @return Returns <code>true</code> if the index corresponds to an existing
   *         key or false otherwise. This is equivalent to checking whether the
   *         index is a positive value (existing keys) or a negative value
   *         (non-existing keys).
   */
// Path: hppc/src/main/templates/com/carrotsearch/hppc/cursors/KTypeVTypeCursor.java
// public final class KTypeVTypeCursor<KType, VType> {
//   /**
//    * The current key and value's index in the container this cursor belongs to.
//    * The meaning of this index is defined by the container (usually it will be
//    * an index in the underlying storage buffer).
//    */
//   public int index;
// 
//   /**
//    * The current key.
//    */
//   public KType key;
// 
//   /**
//    * The current value.
//    */
//   public VType value;
// 
//   @Override
//   public String toString() {
//     return "[cursor, index: " + index + ", key: " + key + ", value: " + value + "]";
//   }
// }


// Path: hppc/src/main/templates/com/carrotsearch/hppc/KTypeVTypeMap.java
import com.carrotsearch.hppc.cursors.KTypeVTypeCursor;

/*! #set($TemplateOptions.ignored = ($TemplateOptions.isKTypeAnyOf("DOUBLE", "FLOAT", "BYTE"))) !*/
package com.carrotsearch.hppc;


/**
 * An associative container with unique binding from keys to a single value.
 */
/*! ${TemplateOptions.generatedAnnotation} !*/
public interface KTypeVTypeMap<KType, VType> extends KTypeVTypeAssociativeContainer<KType, VType> {
  /**
   * @return Returns the value associated with the given key or the default
   *         value for the value type, if the key is not associated with any
   *         value.  For numeric value types, this default value is 0, for
   *         object types it is {@code null}.
   */
  public VType get(KType key);

  /**
   * @return Returns the value associated with the given key or the provided
   *         default value if the key is not associated with any value.
   */
  public VType getOrDefault(KType key, VType defaultValue);

  /**
   * Place a given key and value in the container.
   * 
   * @return The value previously stored under the given key in the map is
   *         returned.
   */
  public VType put(KType key, VType value);

  /**
   * Puts all keys from another container to this map, replacing the values of
   * existing keys, if such keys are present.
   * 
   * @return Returns the number of keys added to the map as a result of this
   *         call (not previously present in the map). Values of existing keys
   *         are overwritten.
   */
  public int putAll(KTypeVTypeAssociativeContainer<? extends KType, ? extends VType> container);

  /**
   * Puts all keys from an iterable cursor to this map, replacing the values of
   * existing keys, if such keys are present.
   * 
   * @return Returns the number of keys added to the map as a result of this
   *         call (not previously present in the map). Values of existing keys
   *         are overwritten.
   */
  public int putAll(Iterable<? extends KTypeVTypeCursor<? extends KType, ? extends VType>> iterable);

  /*! #if ($TemplateOptions.VTypePrimitive) !*/
  /**
   * If <code>key</code> exists, <code>putValue</code> is inserted into the map,
   * otherwise any existing value is incremented by <code>additionValue</code>.
   * 
   * @param key
   *          The key of the value to adjust.
   * @param putValue
   *          The value to put if <code>key</code> does not exist.
   * @param incrementValue
   *          The value to add to the existing value if <code>key</code> exists.
   * @return Returns the current value associated with <code>key</code> (after
   *         changes).
   */
  public VType putOrAdd(KType key, VType putValue, VType incrementValue);
  /*! #end !*/

  /*! #if ($TemplateOptions.VTypePrimitive) !*/
  /**
   * An equivalent of calling
   * 
   * <pre>
   * putOrAdd(key, additionValue, additionValue);
   * </pre>
   * 
   * @param key
   *          The key of the value to adjust.
   * @param additionValue
   *          The value to put or add to the existing value if <code>key</code>
   *          exists.
   * @return Returns the current value associated with <code>key</code> (after
   *         changes).
   */
  public VType addTo(KType key, VType additionValue);

  /*! #end !*/

  /**
   * Remove all values at the given key. The default value for the key type is
   * returned if the value does not exist in the map.
   */
  public VType remove(KType key);

  /**
   * Compares the specified object with this set for equality. Returns
   * {@code true} if and only if the specified object is also a
   * {@link KTypeVTypeMap} and both objects contains exactly the same key-value
   * pairs.
   */
  public boolean equals(Object obj);

  /**
   * @return A hash code of elements stored in the map. The hash code is defined
   *         as a sum of hash codes of keys and values stored within the set).
   *         Because sum is commutative, this ensures that different order of
   *         elements in a set does not affect the hash code.
   */
  public int hashCode();

  /**
   * Returns a logical "index" of a given key that can be used to speed up
   * follow-up value setters or getters in certain scenarios (conditional
   * logic).
   * 
   * The semantics of "indexes" are not strictly defined. Indexes may (and
   * typically won't be) contiguous.
   * 
   * The index is valid only between map modifications (it will not be affected
   * by read-only operations like iteration or value retrievals).
   * 
   * @see #indexExists
   * @see #indexGet
   * @see #indexInsert
   * @see #indexReplace
   * 
   * @param key
   *          The key to locate in the map.
   * @return A non-negative value of the logical "index" of the key in the map
   *         or a negative value if the key did not exist.
   */
  public int indexOf(KType key);

  /**
   * @see #indexOf
   * 
   * @param index
   *          The index of a given key, as returned from {@link #indexOf}.
   * @return Returns <code>true</code> if the index corresponds to an existing
   *         key or false otherwise. This is equivalent to checking whether the
   *         index is a positive value (existing keys) or a negative value
   *         (non-existing keys).
   */
  public boolean indexExists(int index);