Package squidpony.squidmath

Class K2V1<A,​B,​Q>

java.lang.Object
squidpony.squidmath.K2V1<A,​B,​Q>
All Implemented Interfaces:
Serializable
public class K2V1<A,​B,​Q>
extends Object
implements Serializable
An ordered multi-directional map-like data structure with two sets of keys and one list of values. This is structured so that the two keys, of types A and B, are always associated with each other and the same value, of type Q, but may have their index in the ordering change. You can look up a B key with an A key or index, an A key with a B key or index, and a Q value with an A key, B key, or index. Created by Tommy Ettinger on 10/27/2016.
See Also:
Serialized Form

  • Field Summary

    Fields 
    Modifier and Type Field Description
    K2<A,​B> keys  
    ArrayList<Q> values  

  • Constructor Summary

    Constructors 
    Constructor Description
    K2V1()
    Constructs an empty K2V1 with the default parameters: 32 expected indices and a load factor of 0.5f.
    K2V1​(int expected)
    Constructs an empty K2V1 that can hold expected indices before resizing and has a load factor of 0.5f.
    K2V1​(int expected, float f)
    Constructs an empty K2V1 that can hold expected indices before resizing and has load factor f.
    K2V1​(Iterable<A> aKeys, Iterable<B> bKeys, Iterable<Q> qValues)
    Constructs a K2V1 from an A iterable, a B iterable, and a Q iterable, where the A and B items should be unique (if they aren't, each item that would be associated with a duplicate A or B will be skipped).
    K2V1​(K2V1<A,​B,​Q> other)
    Constructs a K2V1 from another K2V1 with ths same A, B, and Q types.

  • Method Summary

    Modifier and Type Method Description
    K2V1<A,​B,​Q> alterA​(A past, A future)
    Changes an existing A key, past, to another A key, future, if past exists in this K2V1 and future does not yet exist in this K2V1.
    K2V1<A,​B,​Q> alterAAt​(int index, A future)
    Changes the A key at index to another A key, future, if index is valid and future does not yet exist in this K2V1.
    K2V1<A,​B,​Q> alterB​(B past, B future)
    Changes an existing B key, past, to another B key, future, if past exists in this K2V1 and future does not yet exist in this K2V1.
    K2V1<A,​B,​Q> alterBAt​(int index, B future)
    Changes the B key at index to another B key, future, if index is valid and future does not yet exist in this K2V1.
    K2V1<A,​B,​Q> alterQAt​(int index, Q future)
    Changes the Q value at index to another Q value, future, if index is valid.
    boolean containsA​(A key)
    Returns true if this contains the A, key, in its collection of A items, or false otherwise.
    boolean containsB​(B key)
    Returns true if this contains the B, key, in its collection of B items, or false otherwise.
    boolean containsIndex​(int index)
    Returns true if index is between 0 (inclusive) and size() (exclusive), or false otherwise.
    boolean containsQ​(Q value)
    Returns true if this contains at least one Q value, or false otherwise
    A getAAt​(int index)
    Given an int index, finds the associated A key (using index as a point in the ordering).
    A getAFromB​(Object key)
    Given a B object, finds the associated A object (it will be at the same point in the ordering).
    ArrayList<Q> getArrayListQ()
    Gets the Q values as a freshly-copied ArrayList of Q; unlike getSetA() or getSetB(), this does not cache the value list.
    B getBAt​(int index)
    Given an int index, finds the associated B key (using index as a point in the ordering).
    B getBFromA​(Object key)
    Given an A object, finds the associated B object (it will be at the same point in the ordering).
    ArrayList<Q> getListQ()
    Gets the Q values as a shared reference to the ArrayList of Q this uses; like getSetA() and getSetB(), changes made to the returned list will also change this data structure.
    OrderedSet<A> getOrderedSetA()
    Returns a separate (shallow) copy of the set of A keys as an OrderedSet.
    OrderedSet<B> getOrderedSetB()
    Returns a separate (shallow) copy of the set of B keys as an OrderedSet.
    Q getQAt​(int index)
    Given an int index, finds the associated Q value (using index as a point in the ordering).
    Q getQFromA​(Object key)
    Given an A object, finds the associated Q value (it will be at the same point in the ordering).
    Q getQFromB​(Object key)
    Given a B object, finds the associated Q value (it will be at the same point in the ordering).
    SortedSet<A> getSetA()
    Gets and caches the A keys as a Collection that implements SortedSet (and so also implements Set).
    SortedSet<B> getSetB()
    Gets and caches the B keys as a Collection that implements SortedSet (and so also implements Set).
    int indexOfA​(Object key)
    Given an A object key, finds the position in the ordering which that A has, or -1 if key is not present.
    int indexOfB​(Object key)
    Given a B object key, finds the position in the ordering which that B has, or -1 if key is not present.
    int indexOfQ​(Object value)
    Given a Q value, finds the first position in the ordering which contains that value, or -1 if not present.
    boolean isEmpty()
    I think you can guess what this does.
    Iterator<A> iteratorA()
    Creates a new iterator over the A keys this holds.
    Iterator<B> iteratorB()
    Creates a new iterator over the B keys this holds.
    Iterator<Q> iteratorQ()
    Creates a new iterator over the Q values this holds.
    int keyCount()  
    boolean put​(A aKey, B bKey, Q qValue)
    Adds an A key, a B key, and a Q value at the same point in the ordering (the end) to this K2V1.
    boolean putAll​(Iterable<A> aKeys, Iterable<B> bKeys, Iterable<Q> qValues)  
    boolean putAll​(K2V1<A,​B,​Q> other)
    Puts all unique A and B keys in other into this K2V1, respecting other's ordering.
    boolean putAt​(int index, A a, B b, Q q)
    Adds an A key, a B key, and a Q value at the given index in the ordering to this K2V1.
    A randomA​(IRNG random)
    Gets a random A from this K2V1 using the given IRNG.
    B randomB​(IRNG random)
    Gets a random B from this K2V1 using the given IRNG.
    Q randomQ​(IRNG random)
    Gets a random Q from this K2V1 using the given IRNG.
    K2V1<A,​B,​Q> removeA​(A removing)
    Removes a given A key, if removing exists in this K2V1's A keys, and also removes any B key or Q value associated with its point in the ordering.
    K2V1<A,​B,​Q> removeAt​(int index)
    Removes a given point in the ordering, if index is at least 0 and less than size().
    K2V1<A,​B,​Q> removeB​(B removing)
    Removes a given B key, if removing exists in this K2V1's B keys, and also removes any A key or Q value associated with its point in the ordering.
    K2V1<A,​B,​Q> reorder​(int... ordering)
    Reorders this K2V1 using ordering, which have the same length as this K2V1's size() and can be generated with ArrayTools.range(int) (which, if applied, would produce no change to the current ordering), IRNG.randomOrdering(int) (which gives a random ordering, and if applied immediately would be the same as calling shuffle(IRNG)), or made in some other way.
    K2V1<A,​B,​Q> shuffle​(IRNG rng)
    Generates a random ordering with rng and applies the same ordering to all keys and values this has; they will maintain their current association to other keys and values but their ordering/indices will change.
    int size()
    Gets the size of this collection.
    int valueCount()  

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • K2V1

      public K2V1()
      Constructs an empty K2V1 with the default parameters: 32 expected indices and a load factor of 0.5f.

    • K2V1

      public K2V1​(int expected)
      Constructs an empty K2V1 that can hold expected indices before resizing and has a load factor of 0.5f.
      Parameters:
      expected - the expected number of items of any single type that this will hold; each put counts as one item

    • K2V1

      public K2V1​(int expected, float f)
      Constructs an empty K2V1 that can hold expected indices before resizing and has load factor f.
      Parameters:
      expected - the expected number of items of any single type that this will hold; each put counts as one item
      f - the load factor; must be greater than 0 and less than 1, but should ideally be between 0.2 and 0.8

    • K2V1

      public K2V1​(Iterable<A> aKeys, Iterable<B> bKeys, Iterable<Q> qValues)
      Constructs a K2V1 from an A iterable, a B iterable, and a Q iterable, where the A and B items should be unique (if they aren't, each item that would be associated with a duplicate A or B will be skipped). The K2V1 this constructs will only take enough items from all Iterables to exhaust the shortest Iterable, so the lengths can be different between arguments. If there are no duplicate A keys or duplicate B keys (e.g. you can have an A key that is equal to a B key, but not to another A key), then all items will be used in the order the Iterable parameters provide them; otherwise the keys and value that would be associated with a duplicate are skipped.
      Parameters:
      aKeys - an Iterable of A keys; if null will be considered empty and this K2V1 will be empty
      bKeys - an Iterable of B keys; if null will be considered empty and this K2V1 will be empty
      qValues - an Iterable of Q values; if null will be considered empty and this K2V1 will be empty

    • K2V1

      public K2V1​(K2V1<A,​B,​Q> other)
      Constructs a K2V1 from another K2V1 with ths same A, B, and Q types. This will have an expected size equal to the current size of other, use the same load factor (f) as other, and will have the same items put into it in the same order.
      Parameters:
      other - a K2V1 to copy into this; must have the same A, B, and Q types

  • Method Details

    • containsA

      public boolean containsA​(A key)
      Returns true if this contains the A, key, in its collection of A items, or false otherwise.
      Parameters:
      key - the A to check the presence of
      Returns:
      true if key is present in this; false otherwise

    • containsB

      public boolean containsB​(B key)
      Returns true if this contains the B, key, in its collection of B items, or false otherwise.
      Parameters:
      key - the B to check the presence of
      Returns:
      true if key is present in this; false otherwise

    • containsQ

      public boolean containsQ​(Q value)
      Returns true if this contains at least one Q value, or false otherwise
      Parameters:
      value - the value to check
      Returns:
      true if value is present at least once in this collection's Q collection

    • containsIndex

      public boolean containsIndex​(int index)
      Returns true if index is between 0 (inclusive) and size() (exclusive), or false otherwise.
      Parameters:
      index - the index to check
      Returns:
      true if index is a valid index in the ordering of this K2V1

    • indexOfA

      public int indexOfA​(Object key)
      Given an A object key, finds the position in the ordering which that A has, or -1 if key is not present. Unlike List.indexOf(Object), this runs in constant time.
      Parameters:
      key - the A to find the position of
      Returns:
      the int index of key in the ordering, or -1 if it is not present

    • indexOfB

      public int indexOfB​(Object key)
      Given a B object key, finds the position in the ordering which that B has, or -1 if key is not present. Unlike List.indexOf(Object), this runs in constant time.
      Parameters:
      key - the B to find the position of
      Returns:
      the int index of key in the ordering, or -1 if it is not present

    • indexOfQ

      public int indexOfQ​(Object value)
      Given a Q value, finds the first position in the ordering which contains that value, or -1 if not present. Runs in linear time normally, since this uses ArrayList.indexOf(Object) to search the values.
      Parameters:
      value - the value to find the position of, which should be a Q
      Returns:
      the first int index of value in the ordering, or -1 if it is not present

    • getAAt

      public A getAAt​(int index)
      Given an int index, finds the associated A key (using index as a point in the ordering).
      Parameters:
      index - an int index into this K2V1
      Returns:
      the A object with index for its position in the ordering, or null if index was invalid

    • getBAt

      public B getBAt​(int index)
      Given an int index, finds the associated B key (using index as a point in the ordering).
      Parameters:
      index - an int index into this K2V1
      Returns:
      the B object with index for its position in the ordering, or null if index was invalid

    • getQAt

      public Q getQAt​(int index)
      Given an int index, finds the associated Q value (using index as a point in the ordering).
      Parameters:
      index - an int index into this K2V1
      Returns:
      the Q value with index for its position in the ordering, or null if index was invalid

    • getBFromA

      public B getBFromA​(Object key)
      Given an A object, finds the associated B object (it will be at the same point in the ordering).
      Parameters:
      key - an A object to use as a key
      Returns:
      the B object associated with key, or null if key was not present

    • getAFromB

      public A getAFromB​(Object key)
      Given a B object, finds the associated A object (it will be at the same point in the ordering).
      Parameters:
      key - a B object to use as a key
      Returns:
      the A object associated with key, or null if key was not present

    • getQFromA

      public Q getQFromA​(Object key)
      Given an A object, finds the associated Q value (it will be at the same point in the ordering).
      Parameters:
      key - an A object to use as a key
      Returns:
      the Q value associated with key, or null if key was not present

    • getQFromB

      public Q getQFromB​(Object key)
      Given a B object, finds the associated Q value (it will be at the same point in the ordering).
      Parameters:
      key - a B object to use as a key
      Returns:
      the Q value associated with key, or null if key was not present

    • randomA

      public A randomA​(IRNG random)
      Gets a random A from this K2V1 using the given IRNG.
      Parameters:
      random - generates a random index to get an A with
      Returns:
      a randomly chosen A, or null if this is empty

    • randomB

      public B randomB​(IRNG random)
      Gets a random B from this K2V1 using the given IRNG.
      Parameters:
      random - generates a random index to get a B with
      Returns:
      a randomly chosen B, or null if this is empty

    • randomQ

      public Q randomQ​(IRNG random)
      Gets a random Q from this K2V1 using the given IRNG.
      Parameters:
      random - generates a random index to get a Q with
      Returns:
      a randomly chosen Q, or null if this is empty

    • alterA

      public K2V1<A,​B,​Q> alterA​(A past, A future)
      Changes an existing A key, past, to another A key, future, if past exists in this K2V1 and future does not yet exist in this K2V1. This will retain past's point in the ordering for future, so the associated other key(s) will still be associated in the same way.
      Parameters:
      past - an A key, that must exist in this K2V1's A keys, and will be changed
      future - an A key, that cannot currently exist in this K2V1's A keys, but will if this succeeds
      Returns:
      this for chaining

    • alterB

      public K2V1<A,​B,​Q> alterB​(B past, B future)
      Changes an existing B key, past, to another B key, future, if past exists in this K2V1 and future does not yet exist in this K2V1. This will retain past's point in the ordering for future, so the associated other key(s) will still be associated in the same way.
      Parameters:
      past - a B key, that must exist in this K2V1's B keys, and will be changed
      future - a B key, that cannot currently exist in this K2V1's B keys, but will if this succeeds
      Returns:
      this for chaining

    • alterAAt

      public K2V1<A,​B,​Q> alterAAt​(int index, A future)
      Changes the A key at index to another A key, future, if index is valid and future does not yet exist in this K2V1. The position in the ordering for future will be the same as index, and the same as the key this replaced, if this succeeds, so the other key(s) at that position will still be associated in the same way.
      Parameters:
      index - a position in the ordering to change; must be at least 0 and less than size()
      future - an A key, that cannot currently exist in this K2V1's A keys, but will if this succeeds
      Returns:
      this for chaining

    • alterBAt

      public K2V1<A,​B,​Q> alterBAt​(int index, B future)
      Changes the B key at index to another B key, future, if index is valid and future does not yet exist in this K2V1. The position in the ordering for future will be the same as index, and the same as the key this replaced, if this succeeds, so the other key(s) at that position will still be associated in the same way.
      Parameters:
      index - a position in the ordering to change; must be at least 0 and less than size()
      future - a B key, that cannot currently exist in this K2V1's B keys, but will if this succeeds
      Returns:
      this for chaining

    • alterQAt

      public K2V1<A,​B,​Q> alterQAt​(int index, Q future)
      Changes the Q value at index to another Q value, future, if index is valid. The position in the ordering for future will be the same as index, and the same as the key this replaced, if this succeeds, so the keys at that position will still be associated in the same way.
      Parameters:
      index - a position in the ordering to change; must be at least 0 and less than size()
      future - a Q value that will be set at the given index if this succeeds
      Returns:
      this for chaining

    • put

      public boolean put​(A aKey, B bKey, Q qValue)
      Adds an A key, a B key, and a Q value at the same point in the ordering (the end) to this K2V1. Neither aKey nor bKey can be present in this collection before this is called. If you want to change or update an existing key, use alterA(Object, Object) or alterB(Object, Object). The value, qValue, has no restrictions.
      Parameters:
      aKey - an A key to add; cannot already be present
      bKey - a B key to add; cannot already be present
      qValue - a Q value to add; can be present any number of times
      Returns:
      true if this collection changed as a result of this call

    • putAt

      public boolean putAt​(int index, A a, B b, Q q)
      Adds an A key, a B key, and a Q value at the given index in the ordering to this K2V1. Neither a nor b can be present in this collection before this is called. If you want to change or update an existing key, use alterA(Object, Object) or alterB(Object, Object). The value, q, has no restrictions. The index this is given should be at least 0 and no greater than size().
      Parameters:
      index - the point in the ordering to place a and b into; later entries will be shifted forward
      a - an A key to add; cannot already be present
      b - a B key to add; cannot already be present
      q - a Q value to add; can be present any number of times
      Returns:
      true if this collection changed as a result of this call

    • putAll

      public boolean putAll​(Iterable<A> aKeys, Iterable<B> bKeys, Iterable<Q> qValues)

    • putAll

      public boolean putAll​(K2V1<A,​B,​Q> other)
      Puts all unique A and B keys in other into this K2V1, respecting other's ordering. If an A or a B in other is already present when this would add one, this will not put the A and B keys at that point in the iteration order, and will place the next unique A and B it finds in the arguments at that position instead.
      Parameters:
      other - another K2V1 collection with the same A and B types
      Returns:
      true if this collection changed as a result of this call

    • removeA

      public K2V1<A,​B,​Q> removeA​(A removing)
      Removes a given A key, if removing exists in this K2V1's A keys, and also removes any B key or Q value associated with its point in the ordering.
      Parameters:
      removing - the A key to remove
      Returns:
      this for chaining

    • removeB

      public K2V1<A,​B,​Q> removeB​(B removing)
      Removes a given B key, if removing exists in this K2V1's B keys, and also removes any A key or Q value associated with its point in the ordering.
      Parameters:
      removing - the B key to remove
      Returns:
      this for chaining

    • removeAt

      public K2V1<A,​B,​Q> removeAt​(int index)
      Removes a given point in the ordering, if index is at least 0 and less than size().
      Parameters:
      index - the position in the ordering to remove
      Returns:
      this for chaining

    • reorder

      public K2V1<A,​B,​Q> reorder​(int... ordering)
      Reorders this K2V1 using ordering, which have the same length as this K2V1's size() and can be generated with ArrayTools.range(int) (which, if applied, would produce no change to the current ordering), IRNG.randomOrdering(int) (which gives a random ordering, and if applied immediately would be the same as calling shuffle(IRNG)), or made in some other way. If you already have an ordering and want to make a different ordering that can undo the change, you can use ArrayTools.invertOrdering(int[]) called on the original ordering.
      Parameters:
      ordering - an int array or vararg that should contain each int from 0 to size() (or less)
      Returns:
      this for chaining

    • shuffle

      public K2V1<A,​B,​Q> shuffle​(IRNG rng)
      Generates a random ordering with rng and applies the same ordering to all keys and values this has; they will maintain their current association to other keys and values but their ordering/indices will change.
      Parameters:
      rng - an IRNG to produce the random ordering this will use
      Returns:
      this for chaining

    • iteratorA

      public Iterator<A> iteratorA()
      Creates a new iterator over the A keys this holds. This can be problematic for garbage collection if called very frequently; it may be better to access items by index (which also lets you access other keys associated with that index) using getAAt(int) in a for(int i=0...) loop.
      Returns:
      a newly-created iterator over this K2V1's A keys

    • iteratorB

      public Iterator<B> iteratorB()
      Creates a new iterator over the B keys this holds. This can be problematic for garbage collection if called very frequently; it may be better to access items by index (which also lets you access other keys associated with that index) using getBAt(int) in a for(int i=0...) loop.
      Returns:
      a newly-created iterator over this K2V1's B keys

    • iteratorQ

      public Iterator<Q> iteratorQ()
      Creates a new iterator over the Q values this holds. This can be problematic for garbage collection if called very frequently; it may be better to access values by index (which also lets you access other keys associated with that index) using getQAt(int) in a for(int i=0...) loop.
      Returns:
      a newly-created iterator over this K2V1's Q values

    • getSetA

      public SortedSet<A> getSetA()
      Gets and caches the A keys as a Collection that implements SortedSet (and so also implements Set). It retains the current ordering. This Set is shared with this collection; it is not a copy, and changes to the returned Set will affect this data structure.
      Returns:
      the A keys as a SortedSet

    • getSetB

      public SortedSet<B> getSetB()
      Gets and caches the B keys as a Collection that implements SortedSet (and so also implements Set). It retains the current ordering. This Set is shared with this collection; it is not a copy, and changes to the returned Set will affect this data structure.
      Returns:
      the B keys as a SortedSet

    • getOrderedSetA

      public OrderedSet<A> getOrderedSetA()
      Returns a separate (shallow) copy of the set of A keys as an OrderedSet. To be called sparingly, since this allocates a new OrderedSet instead of reusing one. This can be useful if you were going to copy the set produced by getSetA() anyway.
      Returns:
      the A keys as an OrderedSet

    • getOrderedSetB

      public OrderedSet<B> getOrderedSetB()
      Returns a separate (shallow) copy of the set of B keys as an OrderedSet. To be called sparingly, since this allocates a new OrderedSet instead of reusing one. This can be useful if you were going to copy the set produced by getSetB() anyway.
      Returns:
      the B keys as an OrderedSet

    • getListQ

      public ArrayList<Q> getListQ()
      Gets the Q values as a shared reference to the ArrayList of Q this uses; like getSetA() and getSetB(), changes made to the returned list will also change this data structure. It retains the current ordering.
      Returns:
      the Q values as an ArrayList, shared with this K2V1

    • getArrayListQ

      public ArrayList<Q> getArrayListQ()
      Gets the Q values as a freshly-copied ArrayList of Q; unlike getSetA() or getSetB(), this does not cache the value list. It retains the current ordering.
      Returns:
      the Q values as an ArrayList, copied from this K2V1's internal list

    • size

      public int size()
      Gets the size of this collection. That's the number of A keys, which is always the same as the number of B keys, which is always the same as the number of indices, which is also always the same as the size of the values List.
      Returns:
      the current number of indices in this K2V1, which can be thought of as the number of A keys

    • isEmpty

      public boolean isEmpty()
      I think you can guess what this does.
      Returns:
      true if there are no items in this K2V1; false if there are items present

    • keyCount

      public int keyCount()

    • valueCount

      public int valueCount()