Class DBIDUtil


  • public final class DBIDUtil
    extends java.lang.Object
    DBID Utility functions.
    Since:
    0.4.0
    Author:
    Erich Schubert
    • Field Detail

      • EMPTYDBIDS

        public static final EmptyDBIDs EMPTYDBIDS
        Final, global copy of empty DBIDs.
    • Constructor Detail

      • DBIDUtil

        private DBIDUtil()
        Static - no public constructor.
    • Method Detail

      • invalid

        public static DBIDRef invalid()
        Get the invalid special ID.
        Returns:
        invalid ID value
      • importInteger

        public static DBID importInteger​(int id)
        Import and integer as DBID.

        Note: this may not be possible for some factories!

        Parameters:
        id - Integer ID to import
        Returns:
        DBID
      • asInteger

        public static int asInteger​(DBIDRef id)
        Export a DBID as int.

        Note: this may not be possible for some factories!

        Parameters:
        id - DBID to export
        Returns:
        integer value
      • compare

        public static int compare​(DBIDRef id1,
                                  DBIDRef id2)
        Compare two DBIDs.
        Parameters:
        id1 - First ID
        id2 - Second ID
        Returns:
        Comparison result
      • equal

        public static boolean equal​(DBIDRef id1,
                                    DBIDRef id2)
        Test two DBIDs for equality.
        Parameters:
        id1 - First ID
        id2 - Second ID
        Returns:
        Comparison result
      • deref

        public static DBID deref​(DBIDRef ref)
        Dereference a DBID reference.
        Parameters:
        ref - DBID reference
        Returns:
        DBID
      • toString

        public static java.lang.String toString​(DBIDRef id)
        Format a DBID as string.
        Parameters:
        id - DBID
        Returns:
        String representation
      • toString

        public static java.lang.String toString​(DBIDs ids)
        Format a DBID as string.
        Parameters:
        ids - DBIDs
        Returns:
        String representation
      • getDBIDSerializer

        public static ByteBufferSerializer<DBID> getDBIDSerializer()
        Get a serializer for DBIDs.
        Returns:
        DBID serializer
      • getDBIDSerializerStatic

        public static ByteBufferSerializer<DBID> getDBIDSerializerStatic()
        Get a serializer for DBIDs with static size.
        Returns:
        DBID serializer
      • generateSingleDBID

        public static DBID generateSingleDBID()
        Generate a single DBID.
        Returns:
        A single DBID
      • deallocateSingleDBID

        public static void deallocateSingleDBID​(DBID id)
        Return a single DBID for reuse.
        Parameters:
        id - DBID to deallocate
      • generateStaticDBIDRange

        public static DBIDRange generateStaticDBIDRange​(int size)
        Generate a static DBID range.
        Parameters:
        size - Requested size
        Returns:
        DBID range
      • deallocateDBIDRange

        public static void deallocateDBIDRange​(DBIDRange range)
        Deallocate a static DBID range.
        Parameters:
        range - Range to deallocate
      • newVar

        public static DBIDVar newVar​(DBIDRef val)
        Make a new DBID variable.
        Parameters:
        val - Initial value.
        Returns:
        Variable
      • newVar

        public static DBIDVar newVar()
        Make a new DBID variable.
        Returns:
        Variable
      • newArray

        public static ArrayModifiableDBIDs newArray()
        Make a new (modifiable) array of DBIDs.
        Returns:
        New array
      • newHashSet

        public static HashSetModifiableDBIDs newHashSet()
        Make a new (modifiable) hash set of DBIDs.
        Returns:
        New hash set
      • newArray

        public static ArrayModifiableDBIDs newArray​(int size)
        Make a new (modifiable) array of DBIDs.
        Parameters:
        size - Size hint
        Returns:
        New array
      • newHashSet

        public static HashSetModifiableDBIDs newHashSet​(int size)
        Make a new (modifiable) hash set of DBIDs.
        Parameters:
        size - Size hint
        Returns:
        New hash set
      • newArray

        public static ArrayModifiableDBIDs newArray​(DBIDs existing)
        Make a new (modifiable) array of DBIDs.
        Parameters:
        existing - Existing DBIDs
        Returns:
        New array
      • newHashSet

        public static HashSetModifiableDBIDs newHashSet​(DBIDs existing)
        Make a new (modifiable) hash set of DBIDs.
        Parameters:
        existing - Existing DBIDs
        Returns:
        New hash set
      • intersection

        public static ModifiableDBIDs intersection​(DBIDs first,
                                                   DBIDs second)
        Compute the set intersection of two sets.
        Parameters:
        first - First set
        second - Second set
        Returns:
        intersection
      • internalIntersection

        private static ModifiableDBIDs internalIntersection​(DBIDs first,
                                                            DBIDs second)
        Compute the set intersection of two sets.
        Parameters:
        first - First set
        second - Second set
        Returns:
        result.
      • intersectionSize

        public static int intersectionSize​(DBIDs first,
                                           DBIDs second)
        Compute the set intersection size of two sets.
        Parameters:
        first - First set
        second - Second set
        Returns:
        size
      • internalIntersectionSize

        private static int internalIntersectionSize​(DBIDs first,
                                                    DBIDs second)
        Compute the set intersection size of two sets.
        Parameters:
        first - First set
        second - Second set
        Returns:
        size
      • symmetricIntersection

        public static void symmetricIntersection​(DBIDs first,
                                                 DBIDs second,
                                                 HashSetModifiableDBIDs firstonly,
                                                 HashSetModifiableDBIDs intersection,
                                                 HashSetModifiableDBIDs secondonly)
        Compute the set symmetric intersection of two sets.
        Parameters:
        first - First set
        second - Second set
        firstonly - OUTPUT: elements only in first. MUST BE EMPTY
        intersection - OUTPUT: elements in intersection. MUST BE EMPTY
        secondonly - OUTPUT: elements only in second. MUST BE EMPTY
      • union

        public static ModifiableDBIDs union​(DBIDs ids1,
                                            DBIDs ids2)
        Returns the union of the two specified collection of IDs.
        Parameters:
        ids1 - the first collection
        ids2 - the second collection
        Returns:
        the union of ids1 and ids2 without duplicates
      • difference

        public static ModifiableDBIDs difference​(DBIDs ids1,
                                                 DBIDs ids2)
        Returns the difference of the two specified collection of IDs.
        Parameters:
        ids1 - the first collection
        ids2 - the second collection
        Returns:
        the difference of ids1 minus ids2
      • makeUnmodifiable

        public static StaticDBIDs makeUnmodifiable​(DBIDs existing)
        Wrap an existing DBIDs collection to be unmodifiable.
        Parameters:
        existing - Existing collection
        Returns:
        Unmodifiable collection
      • ensureArray

        public static ArrayDBIDs ensureArray​(DBIDs ids)
        Ensure that the given DBIDs are array-indexable.
        Parameters:
        ids - IDs
        Returns:
        Array DBIDs.
      • ensureSet

        public static SetDBIDs ensureSet​(DBIDs ids)
        Ensure that the given DBIDs support fast "contains" operations.
        Parameters:
        ids - IDs
        Returns:
        Set DBIDs.
      • ensureModifiable

        public static ModifiableDBIDs ensureModifiable​(DBIDs ids)
        Ensure modifiable.
        Parameters:
        ids - IDs
        Returns:
        Modifiable DBIDs.
      • newPair

        public static DBIDPair newPair​(DBIDRef id1,
                                       DBIDRef id2)
        Make a DBID pair.
        Parameters:
        id1 - first ID
        id2 - second ID
        Returns:
        DBID pair
      • newPair

        public static DoubleDBIDPair newPair​(double val,
                                             DBIDRef id)
        Make a DoubleDBIDPair.
        Parameters:
        val - double value
        id - ID
        Returns:
        new pair
      • newMinHeap

        public static DoubleDBIDHeap newMinHeap​(int k)
        Create a min heap for Double+DBID pairs.
        Parameters:
        k - K value
        Returns:
        New heap of size k
      • newMaxHeap

        public static DoubleDBIDHeap newMaxHeap​(int k)
        Create a max heap for Double+DBID pairs.
        Parameters:
        k - K value
        Returns:
        New heap of size k
      • newHeap

        public static KNNHeap newHeap​(int k)
        Create a heap for the k nearest neighbors (with ties).
        Parameters:
        k - K value
        Returns:
        New heap of size k.
      • newHeap

        public static KNNHeap newHeap​(KNNList exist)
        Build a new heap from a given list.
        Parameters:
        exist - Existing result
        Returns:
        New heap
      • randomShuffle

        public static void randomShuffle​(ArrayModifiableDBIDs ids,
                                         RandomFactory rnd)
        Produce a random shuffling of the given DBID array.
        Parameters:
        ids - Original DBIDs, no duplicates allowed
        rnd - Random generator
      • randomShuffle

        public static void randomShuffle​(ArrayModifiableDBIDs ids,
                                         java.util.Random random)
        Produce a random shuffling of the given DBID array.
        Parameters:
        ids - Original DBIDs, no duplicates allowed
        random - Random generator
      • randomShuffle

        public static void randomShuffle​(ArrayModifiableDBIDs ids,
                                         java.util.Random random,
                                         int limit)
        Produce a random shuffling of the given DBID array.

        Only the first limit elements will be fully randomized, but the remaining objects will also be changed.

        Parameters:
        ids - Original DBIDs, no duplicates allowed
        random - Random generator
        limit - Shuffling limit.
      • randomSample

        public static ModifiableDBIDs randomSample​(DBIDs source,
                                                   int k,
                                                   int seed)
        Produce a random sample of the given DBIDs.
        Parameters:
        source - Original DBIDs, no duplicates allowed
        k - k Parameter
        seed - Random generator seed
        Returns:
        new DBIDs
      • randomSample

        public static ModifiableDBIDs randomSample​(DBIDs source,
                                                   int k,
                                                   java.lang.Long seed)
        Produce a random sample of the given DBIDs.
        Parameters:
        source - Original DBIDs, no duplicates allowed
        k - k Parameter
        seed - Random generator seed
        Returns:
        new DBIDs
      • randomSample

        public static ModifiableDBIDs randomSample​(DBIDs source,
                                                   int k,
                                                   RandomFactory rnd)
        Produce a random sample of the given DBIDs.
        Parameters:
        source - Original DBIDs, no duplicates allowed
        k - k Parameter
        rnd - Random generator
        Returns:
        new DBIDs
      • randomSampleExcept

        public static ModifiableDBIDs randomSampleExcept​(DBIDs source,
                                                         DBIDRef except,
                                                         int k,
                                                         RandomFactory rnd)
        Produce a random sample of the given DBIDs.
        Parameters:
        source - Original DBIDs, no duplicates allowed
        except - Excluded object
        k - k Parameter
        rnd - Random generator
        Returns:
        new DBIDs
      • randomSample

        public static ModifiableDBIDs randomSample​(DBIDs source,
                                                   int k,
                                                   java.util.Random random)
        Produce a random sample of the given DBIDs.
        Parameters:
        source - Original DBIDs, no duplicates allowed
        k - k Parameter
        random - Random generator
        Returns:
        new DBIDs
      • randomSampleExcept

        public static ModifiableDBIDs randomSampleExcept​(DBIDs source,
                                                         DBIDRef except,
                                                         int k,
                                                         java.util.Random random)
        Produce a random sample of the given DBIDs.
        Parameters:
        source - Original DBIDs, no duplicates allowed
        except - Excluded object
        k - k Parameter
        random - Random generator
        Returns:
        new DBIDs
      • randomSample

        public static DBIDs randomSample​(DBIDs ids,
                                         double rate,
                                         RandomFactory random)
        Produce a random sample of the given DBIDs.
        Parameters:
        ids - Original ids, no duplicates allowed
        rate - Sampling rate
        random - Random generator
        Returns:
        Sample
      • randomSample

        public static DBIDs randomSample​(DBIDs ids,
                                         double rate,
                                         java.util.Random random)
        Produce a random sample of the given DBIDs.
        • values less or equal 0 mean no sampling.
        • values larger than 0, but at most 1, are relative rates.
        • values larger than 1 are supposed to be integer counts.
        Parameters:
        ids - Original ids, no duplicates allowed
        rate - Sampling rate
        random - Random generator
        Returns:
        Sample
      • randomSample

        public static DBIDVar randomSample​(DBIDs ids,
                                           java.util.Random random)
        Draw a single random sample.
        Parameters:
        ids - IDs to draw from
        random - Random value
        Returns:
        Random ID
      • randomSample

        public static DBIDVar randomSample​(DBIDs ids,
                                           RandomFactory random)
        Draw a single random sample.
        Parameters:
        ids - IDs to draw from
        random - Random value
        Returns:
        Random ID
      • randomSplit

        public static ArrayDBIDs[] randomSplit​(DBIDs ids,
                                               int p,
                                               RandomFactory rnd)
        Randomly split IDs into p partitions of almost-equal size.
        Parameters:
        ids - Original DBIDs
        p - Desired number of partitions.
        rnd - Random generator
      • randomSplit

        public static ArrayDBIDs[] randomSplit​(DBIDs oids,
                                               int p,
                                               java.util.Random random)
        Randomly split IDs into p partitions of almost-equal size.
        Parameters:
        oids - Original DBIDs
        p - Desired number of partitions.
        random - Random generator
      • newDistanceDBIDList

        public static ModifiableDoubleDBIDList newDistanceDBIDList​(int size)
        Create a modifiable list to store distance-DBID pairs.
        Parameters:
        size - Estimated upper list size
        Returns:
        Empty list
      • newDistanceDBIDList

        public static ModifiableDoubleDBIDList newDistanceDBIDList()
        Create a modifiable list to store distance-DBID pairs.
        Returns:
        Empty list
      • assertRange

        public static DBIDRange assertRange​(DBIDs ids)
        Assert that the presented ids constitute a continuous DBIDRange.
        Parameters:
        ids - ID range.
        Returns:
        DBID range.
        Throws:
        AbortException