K2 (squidlib-util 3.0.6 API)

java.lang.Object
- squidpony.squidmath.K2<A,B>

All Implemented Interfaces:

java.io.Serializable
```
public class K2<A,B>
extends java.lang.Object
implements java.io.Serializable
```
An ordered bidirectional map-like data structure, with unique A keys and unique B keys updated together like a map that can be queried by A keys, B keys, or int indices. Does not implement any interfaces that you would expect for a data structure, because almost every method it has needs to specify whether it applies to A or B items, but you can get collections that implement SortedSet of its A or B keys.
Called K2 because it has 2 key sets; other collections can have other keys or have values, like K2V1. Created by Tommy Ettinger on 10/25/2016.

See Also:

Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

Arrangement<A> keysA

Arrangement keysB

Fields
Modifier and Type	Field and Description
`Arrangement<A>`	`keysA`
`Arrangement<B>`	`keysB`

Constructor Summary

Constructors
Constructor and Description
`K2()` Constructs an empty K2.
`K2(Arrangement<A> aItems, Arrangement<B> bItems)`
`K2(int expected)` Constructs a K2 with the expected number of indices to hold (the number of A and number of B items is always the same, and this will be more efficient if expected is greater than that number).
`K2(int expected, float f)` Constructs a K2 with the expected number of indices to hold (the number of A and number of B items is always the same, and this will be more efficient if expected is greater than that number) and the load factor to use, between 0.1f and 0.8f usually (using load factors higher than 0.8f can cause problems).
`K2(int expected, float f, CrossHash.IHasher hasherA, CrossHash.IHasher hasherB)` Constructs a K2 with the expected number of indices to hold (the number of A and number of B items are always equal, and this will be more efficient if expected is greater than that number), the load factor to use, between 0.1f and 0.8f usually (using load factors higher than 0.8f can cause problems), and two IHasher implementations, such as `CrossHash.generalHasher`, that will be used to hash and compare for equality with A keys and B keys, respectively.
`K2(java.lang.Iterable<? extends A> aKeys, java.lang.Iterable<? extends B> bKeys)` Constructs a K2 from a pair of Iterables that will be processed in pairs, adding a unique A from aKeys if and only if it can also add a unique B from bKeys, otherwise skipping that pair.
`K2(K2<? extends A,? extends B> other)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`K2<A,B>`	`alterA(A past, A future)` Changes an existing A key, `past`, to another A key, `future`, if past exists in this K2 and future does not yet exist in this K2.
`K2<A,B>`	`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 K2.
`K2<A,B>`	`alterB(B past, B future)` Changes an existing B key, `past`, to another B key, `future`, if past exists in this K2 and future does not yet exist in this K2.
`K2<A,B>`	`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 K2.
`boolean`	`containsA(A key)` Returns true if this contains the A, key, in its collection of A items.
`boolean`	`containsB(B key)` Returns true if this contains the B, key, in its collection of B items.
`boolean`	`containsIndex(int index)` Returns true if index is between 0 (inclusive) and `size()` (exclusive), 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(java.lang.Object key)` Given a B object, finds the associated A object (it will be at the same point in the ordering).
`B`	`getBAt(int index)` Given an int index, finds the associated B key (using index as a point in the ordering).
`B`	`getBFromA(java.lang.Object key)` Given an A object, finds the associated B object (it will be at the same point in the ordering).
`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`.
`java.util.SortedSet<A>`	`getSetA()` Gets and caches the A keys as a Collection that implements SortedSet (and so also implements Set).
`java.util.SortedSet<B>`	`getSetB()` Gets and caches the B keys as a Collection that implements SortedSet (and so also implements Set).
`int`	`indexOfA(java.lang.Object key)` Given an A object key, finds the position in the ordering that A has, or -1 if key is not present.
`int`	`indexOfB(java.lang.Object key)` Given a B object key, finds the position in the ordering that B has, or -1 if key is not present.
`boolean`	`isEmpty()`
`java.util.Iterator<A>`	`iteratorA()` Creates a new iterator over the A keys this holds.
`java.util.Iterator<B>`	`iteratorB()` Creates a new iterator over the B keys this holds.
`int`	`keyCount()`
`boolean`	`put(A a, B b)` Adds an A key and a B key at the same point in the ordering (the end) to this K2.
`boolean`	`putAll(java.lang.Iterable<? extends A> aKeys, java.lang.Iterable<? extends B> bKeys)` Puts all unique A and B keys in `aKeys` and `bKeys` into this K2 at the end.
`boolean`	`putAll(K2<? extends A,? extends B> other)` Puts all unique A and B keys in `other` into this K2, respecting other's ordering.
`boolean`	`putAt(int index, A a, B b)` Adds an A key and a B key at the given index in the ordering to this K2.
`A`	`randomA(IRNG random)` Gets a random A from this K2 using the given IRNG.
`B`	`randomB(IRNG random)` Gets a random B from this K2 using the given IRNG.
`K2<A,B>`	`removeA(A removing)` Removes a given A key, if `removing` exists in this K2's A keys, and also removes any keys associated with its point in the ordering.
`K2<A,B>`	`removeAt(int index)` Removes a given point in the ordering, if `index` is at least 0 and less than `size()`.
`K2<A,B>`	`removeB(B removing)` Removes a given B key, if `removing` exists in this K2's B keys, and also removes any keys associated with its point in the ordering.
`K2<A,B>`	`reorder(int... ordering)` Reorders this K2 using `ordering`, which have the same length as this K2'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.
`K2<A,B>`	`shuffle(IRNG rng)` Generates a random ordering with rng and applies the same ordering to all kinds of keys this has; they will maintain their current association to other keys but their ordering/indices will change.
`int`	`size()`
`int`	`valueCount()`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
 - keysA
```
public Arrangement<A> keysA
```
 - keysB
```
public Arrangement keysB
```
- Constructor Detail
 - K2
```
public K2()
```
 Constructs an empty K2.
 - K2
```
public K2(int expected)
```
 Constructs a K2 with the expected number of indices to hold (the number of A and number of B items is always the same, and this will be more efficient if expected is greater than that number).
 
 Parameters:
 
 expected -
 - K2
```
public K2(int expected,
 float f)
```
 Constructs a K2 with the expected number of indices to hold (the number of A and number of B items is always the same, and this will be more efficient if expected is greater than that number) and the load factor to use, between 0.1f and 0.8f usually (using load factors higher than 0.8f can cause problems).
 
 Parameters:
 
 expected - the amount of indices (the count of A items is the same as the count of B items) this should hold
 
 f - the load factor, probably between 0.1f and 0.8f
 - K2
```
public K2(int expected,
 float f,
 CrossHash.IHasher hasherA,
 CrossHash.IHasher hasherB)
```
 Constructs a K2 with the expected number of indices to hold (the number of A and number of B items are always equal, and this will be more efficient if expected is greater than that number), the load factor to use, between 0.1f and 0.8f usually (using load factors higher than 0.8f can cause problems), and two IHasher implementations, such as CrossHash.generalHasher, that will be used to hash and compare for equality with A keys and B keys, respectively. Specifying an IHasher is usually needed if your keys are arrays (there are existing implementations for 1D arrays of all primitive types, CharSequence, and Object in CrossHash), or if you want hashing by identity and reference equality (which would use CrossHash.identityHasher, and might be useful if keys are mutable). Other options are possible with custom IHashers, like hashing Strings but ignoring, or only considering, a certain character for the hash and equality checks.
 
 Parameters:
 
 expected - the amount of indices (the count of A items is the same as the count of B items) this should hold
 
 f - the load factor, probably between 0.1f and 0.8f
 
 hasherA - an implementation of CrossHash.IHasher meant for A keys
 
 hasherB - an implementation of CrossHash.IHasher meant for B keys
 - K2
```
public K2(java.lang.Iterable<? extends A> aKeys,
 java.lang.Iterable<? extends B> bKeys)
```
 Constructs a K2 from a pair of Iterables that will be processed in pairs, adding a unique A from aKeys if and only if it can also add a unique B from bKeys, otherwise skipping that pair.
 
 Parameters:
 
 aKeys - an Iterable of A that should all be unique
 
 bKeys - an Iterable of B that should all be unique
 - K2
```
public K2(K2<? extends A,? extends B> other)
```
 - K2
```
public K2(Arrangement<A> aItems,
 Arrangement bItems)
```
- Method Detail
 - containsA
```
public boolean containsA(A key)
```
 Returns true if this contains the A, key, in its collection of A items.
 
 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.
 
 Parameters:
 
 key - the B to check the presence of
 
 Returns:
 
 true if key is present in this; false otherwise
 - 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 K2
 - indexOfA
```
public int indexOfA(java.lang.Object key)
```
 Given an A object key, finds the position in the ordering 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(java.lang.Object key)
```
 Given a B object key, finds the position in the ordering 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
 - 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 K2
 
 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 K2
 
 Returns:
 
 the B object with index for its position in the ordering, or null if index was invalid
 - getBFromA
```
public B getBFromA(java.lang.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(java.lang.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
 - randomA
```
public A randomA(IRNG random)
```
 Gets a random A from this K2 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 K2 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
 - alterA
```
public K2<A,B> alterA(A past,
 A future)
```
 Changes an existing A key, past, to another A key, future, if past exists in this K2 and future does not yet exist in this K2. 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 K2's A keys, and will be changed
 
 future - an A key, that cannot currently exist in this K2's A keys, but will if this succeeds
 
 Returns:
 
 this for chaining
 - alterB
```
public K2<A,B> alterB(B past,
 B future)
```
 Changes an existing B key, past, to another B key, future, if past exists in this K2 and future does not yet exist in this K2. 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 K2's B keys, and will be changed
 
 future - a B key, that cannot currently exist in this K2's B keys, but will if this succeeds
 
 Returns:
 
 this for chaining
 - alterAAt
```
public K2<A,B> 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 K2. 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 K2's A keys, but will if this succeeds
 
 Returns:
 
 this for chaining
 - alterBAt
```
public K2<A,B> 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 K2. 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 K2's B keys, but will if this succeeds
 
 Returns:
 
 this for chaining
 - put
```
public boolean put(A a,
 B b)
```
 Adds an A key and a B key at the same point in the ordering (the end) to this K2. Neither parameter 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).
 
 Parameters:
 
 a - an A key to add; cannot already be present
 
 b - a B key to add; cannot already be present
 
 Returns:
 
 true if this collection changed as a result of this call
 - putAll
```
public boolean putAll(java.lang.Iterable<? extends A> aKeys,
 java.lang.Iterable<? extends B> bKeys)
```
 Puts all unique A and B keys in aKeys and bKeys into this K2 at the end. If an A in aKeys or a B in bKeys 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:
 
 aKeys - an Iterable or Collection of A keys to add; should all be unique (like a Set)
 
 bKeys - an Iterable or Collection of B keys to add; should all be unique (like a Set)
 
 Returns:
 
 true if this collection changed as a result of this call
 - putAll
```
public boolean putAll(K2<? extends A,? extends B> other)
```
 Puts all unique A and B keys in other into this K2, 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 K2 collection with the same A and B types
 
 Returns:
 
 true if this collection changed as a result of this call
 - putAt
```
public boolean putAt(int index,
 A a,
 B b)
```
 Adds an A key and a B key at the given index in the ordering to this K2. 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 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
 
 Returns:
 
 true if this collection changed as a result of this call
 - removeA
```
public K2<A,B> removeA(A removing)
```
 Removes a given A key, if removing exists in this K2's A keys, and also removes any keys associated with its point in the ordering.
 
 Parameters:
 
 removing - the A key to remove
 
 Returns:
 
 this for chaining
 - removeB
```
public K2<A,B> removeB(B removing)
```
 Removes a given B key, if removing exists in this K2's B keys, and also removes any keys associated with its point in the ordering.
 
 Parameters:
 
 removing - the B key to remove
 
 Returns:
 
 this for chaining
 - removeAt
```
public K2<A,B> 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 K2<A,B> reorder(int... ordering)
```
 Reorders this K2 using ordering, which have the same length as this K2'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 K2<A,B> shuffle(IRNG rng)
```
 Generates a random ordering with rng and applies the same ordering to all kinds of keys this has; they will maintain their current association to other keys but their ordering/indices will change.
 
 Parameters:
 
 rng - an IRNG to produce the random ordering this will use
 
 Returns:
 
 this for chaining
 - iteratorA
```
public java.util.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 K2's A keys
 - iteratorB
```
public java.util.Iterator 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 K2's B keys
 - getSetA
```
public java.util.SortedSet<A> getSetA()
```
 Gets and caches the A keys as a Collection that implements SortedSet (and so also implements Set). This Set is shared with this collection; it is not a copy.
 
 Returns:
 
 the A keys as a SortedSet
 - getSetB
```
public java.util.SortedSet getSetB()
```
 Gets and caches the B keys as a Collection that implements SortedSet (and so also implements Set). This Set is shared with this collection; it is not a copy.
 
 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 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
 - keyCount
```
public int keyCount()
```
 - valueCount
```
public int valueCount()
```
 - size
```
public int size()
```
 - isEmpty
```
public boolean isEmpty()
```

Class K2<A,B>

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

keysA

keysB

Constructor Detail

K2

K2

K2

K2

K2

K2

K2

Method Detail

containsA

containsB

containsIndex

indexOfA

indexOfB

getAAt

getBAt

getBFromA

getAFromB

randomA

randomB

alterA

alterB

alterAAt

alterBAt

put

putAll

putAll

putAt

removeA

removeB

removeAt

reorder

shuffle

iteratorA

iteratorB

getSetA

getSetB

getOrderedSetA

getOrderedSetB

keyCount

valueCount

size

isEmpty