org.grouplens.lenskit.collections

## Class LongKeyDomain

• All Implemented Interfaces:
Serializable

public abstract class LongKeyDomain
extends Object
implements Serializable
Implement a domain of long keys, sorted by key. Keys can be mapped back to indexes and vice versa; it has a fixed domain, and a bitmask of active entries. This is a helper class for implementing LongSortedArraySet, SparseVector, etc. This class should not be directly used outside of the LensKit data structures.

A key set has a domain, which is the set of all possible keys that it can contain. These keys are stored in an array. The active keys are those that are actually in the set. Active/inactive status is tracked with a bitmask.

Since:
2.0
Serialized Form
Compatibility
Private
• ### Method Summary

All Methods
Modifier and Type Method and Description
void acquire()
Mark the key set as owned, but don't copy it.
LongKeyDomain activate(BitSet active)
Activate bits from a bit set.
IntBidirectionalIterator activeIndexIterator(boolean mayBeModified)
Get an iterator over active indexes.
IntBidirectionalIterator activeIndexIterator(int min, int max, int idx)
Get an iterator over active indexes, initialized to the specified index and limited to a particular range.
LongSortedSet activeSetView()
Get a vew of this key set as a set.
LongKeyDomain clone()
Return a copy of this key set.
LongKeyDomain compactCopy()
Make a compact copy of this key set.
LongKeyDomain compactCopy(boolean active)
Make a compact copy of this key set.
boolean containsKey(long key)
Query whether this set contains the specified key in its domain.
static LongKeyDomain create(long... keys)
Create a key set with some keys.
LongSortedSet domain()
Get the key set's domain as a set.
int domainSize()
Get the domain size of this set.
static LongKeyDomain empty()
Create an empty key domain.
static LongKeyDomain fromCollection(Collection<Long> keys)
Create a key set from a collection of keys.
static LongKeyDomain fromCollection(Collection<Long> keys, boolean initiallyActive)
Create a key set from a collection of keys.
BitSet getActiveMask()
Get the active keys as a bit set.
abstract int getIndex(long key)
Get the index for a key, regardless of its active state.
int getIndexIfActive(long key)
Get the index for a key if that key is active.
abstract long getKey(int idx)
Get the key at an index.
LongKeyDomain inactiveCopy()
Return a copy of this key set that is entirely inactive.
boolean indexIsActive(int idx)
Query whether an index is active.
LongKeyDomain invert()
Invert the active status of all keys in the set.
abstract boolean isCompatibleWith(LongKeyDomain other)
Query whether this key set is compatible with another.
boolean isCompletelySet()
Query whether this domain is completely set (has no unset keys).
boolean keyIsActive(long key)
Query whether a key is active.
LongBidirectionalIterator keyIterator(IntBidirectionalIterator iter)
Wrap an index iterator into a key iterator.
LongList keyList()
Get the key set's list of keys (domain) as a list.
int lowerBound(long key)
Get the lower bound, the first index whose key is greater than or equal to the specified key.
LongSortedSet modifiableActiveSetView()
Get a view of this key set as a set that supports limited mutation.
LongKeyDomain setActive(BitSet active)
Set the active bits from a bit set.
LongKeyDomain setActive(int idx, boolean active)
Set the active flag for a single key.
LongKeyDomain setAllActive(boolean active)
Set the active status of all entries in the key set.
int size()
Get the number of active keys in this set.
LongKeyDomain unowned()
Mark this key set as unowned.
int upperBound(long key)
Get the upper bound, the first index whose key is greater than the specified key.
static LongKeyDomain wrap(long[] keys, int size, boolean initiallyActive)
Wrap a key array (with a specified size) into a key set.
• ### Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
• ### Method Detail

• #### wrap

public static LongKeyDomain wrap(long[] keys,
int size,
boolean initiallyActive)
Wrap a key array (with a specified size) into a key set.
Parameters:
keys - The key array. This array must be sorted, and must not contain duplicates. For efficiency, this condition is not checked unless assertions are enabled. Since this method is only intended to be used when implementing test cases or other data structures, callers of this method should ensure sortedness and throw the appropriate exception.
size - The length of the array to actually use.
initiallyActive - true to activate all keys initially, false to leave them inactive.
Returns:
The key set.
• #### fromCollection

public static LongKeyDomain fromCollection(Collection<Long> keys,
boolean initiallyActive)
Create a key set from a collection of keys.
Parameters:
keys - The key collection.
initiallyActive - true if the elements of the key set should be initially activated; false to make all keys initially inactive.
Returns:
The key set.
• #### fromCollection

public static LongKeyDomain fromCollection(Collection<Long> keys)
Create a key set from a collection of keys. All keys are initially active.
Parameters:
keys - The keys.
Returns:
The key set.
• #### create

public static LongKeyDomain create(long... keys)
Create a key set with some keys. All keys are initially active.
Parameters:
keys - The keys.
Returns:
The key set.
• #### empty

public static LongKeyDomain empty()
Create an empty key domain.
Returns:
An empty key domain.
• #### getIndex

public abstract int getIndex(long key)
Get the index for a key, regardless of its active state.
Parameters:
key - The key.
Returns:
The index, or a negative value if the key is not in the domain. Such a negative value is the insertion point, as defined by Arrays.binarySearch(long[], int, int, long).
• #### getIndexIfActive

public int getIndexIfActive(long key)
Get the index for a key if that key is active.
Parameters:
key - The key.
Returns:
The index, or a negative value if the key is not in the domain or is inactive.
• #### upperBound

public int upperBound(long key)
Get the upper bound, the first index whose key is greater than the specified key.
Parameters:
key - The key to search for.
Returns:
The first index greater than the specified key, or domainSize() if the key is the last key in the domain. The index is not necessarily active.
• #### lowerBound

public int lowerBound(long key)
Get the lower bound, the first index whose key is greater than or equal to the specified key. This method is paired with upperBound(long); the interval [lowerBound(k),upperBound(k)) contains the index of k, if the key is in the domain, and is empty if the key is not in the domain.
Parameters:
key - The key to search for.
Returns:
The index of the first key greater than or equal to key.
• #### clone

public LongKeyDomain clone()
Return a copy of this key set. The resulting key set has an independent mask. Key storage is shared for efficiency.
Overrides:
clone in class Object
Returns:
The copied key set.
• #### unowned

public LongKeyDomain unowned()
Mark this key set as unowned. The next call to clone() will mark the key set as owned and return it rather than making a copy. This allows code to avoid an extra copy when creating a key set to pass off to another method or object that will make a defensive copy.

You almost certainly do not want to call this method.

Any object or method that receives a key set that it intends to take ownership of must call clone() to make sure that it owns the set.

Returns:
This key set (for chaining).
• #### acquire

public void acquire()
Mark the key set as owned, but don't copy it. Used by views to make sure that someone owns the key set.
• #### inactiveCopy

public LongKeyDomain inactiveCopy()
Return a copy of this key set that is entirely inactive.
Returns:
The new key set, with the same keys but all of them deactivated.
• #### compactCopy

public LongKeyDomain compactCopy()
Make a compact copy of this key set. In a compact copy, the key array has no extra storage and only the active keys are retained. All keys are active in the resulting set.
Returns:
A compacted copy of this key set.
• #### compactCopy

public LongKeyDomain compactCopy(boolean active)
Make a compact copy of this key set. In a compact copy, the key array has no extra storage and only the active keys are retained.
Parameters:
active - Whether the keys should be active or inactive in the compacted key set.
Returns:
A compacted copy of this key set.
• #### indexIsActive

public boolean indexIsActive(int idx)
Query whether an index is active.
Parameters:
idx - The index.
Returns:
true if the key at the index is active.
• #### keyIsActive

public boolean keyIsActive(long key)
Query whether a key is active.
Parameters:
key - The key to query.
Returns:
true if the key is in the domain and active.
• #### containsKey

public boolean containsKey(long key)
Query whether this set contains the specified key in its domain.
Parameters:
key - The key.
Returns:
true if the key is in the domain.
• #### getKey

public abstract long getKey(int idx)
Get the key at an index.
Parameters:
idx - The index to query.
Returns:
The key at the specified index.
• #### domainSize

public int domainSize()
Get the domain size of this set.
Returns:
The domain size.
• #### size

public int size()
Get the number of active keys in this set.
Returns:
The number of active keys.
• #### isCompletelySet

public boolean isCompletelySet()
Query whether this domain is completely set (has no unset keys).
Returns:
true if the domain is completely set.
• #### activeIndexIterator

public IntBidirectionalIterator activeIndexIterator(boolean mayBeModified)
Get an iterator over active indexes.
Parameters:
mayBeModified - Whether the set's active/inactive flags may be modified during iteration. If false, this method is slightly more efficient; if true, the iterator will iterate over a snapshot of the current active/inactive state.
Returns:
An iterator over active indexes.
• #### activeIndexIterator

public IntBidirectionalIterator activeIndexIterator(int min,
int max,
int idx)
Get an iterator over active indexes, initialized to the specified index and limited to a particular range.
Parameters:
min - The minimum index for the iterator.
max - The maximum index for the iterator.
idx - The starting index for the iterator. The iterator can go backwards from this index, if it is greater than min.
Returns:
An iterator over active indexes.
• #### keyIterator

public LongBidirectionalIterator keyIterator(IntBidirectionalIterator iter)
Wrap an index iterator into a key iterator.
Parameters:
iter - The index iterator.
Returns:
An iterator over the keys corresponding to the iterator's indexes.
• #### activeSetView

public LongSortedSet activeSetView()
Get a vew of this key set as a set.
Returns:
A view of the active keys as a set.
• #### modifiableActiveSetView

public LongSortedSet modifiableActiveSetView()
Get a view of this key set as a set that supports limited mutation. The set can have items removed (using methods such as remove(Object), rem(long), removeAll(Collection), and retainAll(Collection)), and those removals will be reflected by marking the associated entries as inactive in the key set.
Returns:
A view of this key set as a set with limited mutation capabilities.
activeSetView()
• #### domain

public LongSortedSet domain()
Get the key set's domain as a set.
Returns:
A view of the key domain as a set.
• #### keyList

public LongList keyList()
Get the key set's list of keys (domain) as a list.
Returns:
A list of all keys in the key domain.

public BitSet getActiveMask()
Get the active keys as a bit set. The returned bit set must not be modified.
Returns:
The active bit mask. Do not modify this bit set.
• #### isCompatibleWith

public abstract boolean isCompatibleWith(@Nonnull
LongKeyDomain other)
Query whether this key set is compatible with another. Two key sets are compatible if indexes are compatible (that is, the same index will refer to the same key). This method is conservative and efficient; it may claim that two sets are incompatible even if indexes may compatible. Key sets generated with clone() are compatible with their parent and each other.
Parameters:
other - The other key set.
Returns:
true if the two key sets are compatible.
• #### invert

public LongKeyDomain invert()
Invert the active status of all keys in the set. The set is modified in place; it is just returned for chaining.
Returns:
this (for chaining).
• #### setAllActive

public LongKeyDomain setAllActive(boolean active)
Set the active status of all entries in the key set.
Parameters:
active - true to activate, false to deactivate.
Returns:
The key set (for chaining).
• #### setActive

public LongKeyDomain setActive(int idx,
boolean active)
Set the active flag for a single key.
Parameters:
idx - The key's index.
active - Whether the key is active.
Returns:
The key set (for chaining).
• #### setActive

public LongKeyDomain setActive(BitSet active)
Set the active bits from a bit set.
Parameters:
active - The bits to set. Unset bits in this set are cleared.
Returns:
The key domain (for chaining).
• #### activate

public LongKeyDomain activate(BitSet active)
Activate bits from a bit set.
Parameters:
active - The bits to set. Unset bits in this set are left unchanged.
Returns:
The key domain (for chaining).