Class LongPrefix

java.lang.Object
de.calamanari.pk.muhai.LongPrefix
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<LongPrefix>

public final class LongPrefix
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<LongPrefix>
The LongPrefix is a VALUE-object that represents a valid prefix sequence for a long value to define a keyspace. The size of the prefix can be up to 63 bits. 64 bits is invalid because it would create a strange keyspace that has a single member (the prefix itself) but cannot contain any keys. A valid special case is an empty prefix (2^64 keys).
Author:
Karl Eilebrecht
See Also:
Serialized Form
  • Field Summary

    Fields
    Modifier and Type Field Description
    static LongPrefix DEFAULT
    This two-bits prefix '00' (2^62 keys possible) is a convenient default as it still spans a large keyspace, but eliminates the negative values when represented as signed long and it reserves 3 subspaces (e.g. for migration purposes in future).
    static LongPrefix NONE
    Special case, an empty prefix means no prefix at all to leverage the maximum number of keys: 2^64.
    static LongPrefix POSITIVE
    This single-bit prefix '0' (2^63 keys possible) causes the signed long representation to never turn negative.
    static LongPrefix POSITIVE_31
    This prefix sets the first 33 bits '0', so any key in that space of 2^31 keys will be a positive 32-bit integer.
    static LongPrefix STRAIGHT
    This two-bits prefix '01' (2^62 keys possible) spans a large keyspace, eliminates the negative values when represented as signed long and it reserves 3 subspaces (e.g. for migration purposes in future).
    static LongPrefix STRAIGHT_30
    This prefix sets the first 33 bits to '0' followed by a '1' (2^30 keys possible) creating a rather small keyspace with 3 optional subspaces.
  • Method Summary

    Modifier and Type Method Description
    long applyTo​(long key)
    Returns a new long value where the leading bits (length of prefix) have been replaced with the bits of the prefix.
    int compareTo​(LongPrefix other)  
    boolean equals​(java.lang.Object obj)  
    static LongPrefix fromBinaryString​(java.lang.String prefixString)
    Returns the LongPrefix instance for the given prefix string, each character ('0' or '1') stands for a bit.
    int getLength()  
    java.math.BigInteger getSizeOfKeyspace()
    Returns the size of the keyspace with a maximum value of 2^64 = 18_446_744_073_709_551_616 keys (empty prefix).
    int hashCode()  
    boolean match​(long key)
    Checks whether the given key is prefixed with this prefix.
    java.lang.String toBinaryString()
    Returns the string representation of this prefix (provided at construction time), a character (0, 1) per bit.
    java.lang.String toString()
    Returns a description

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, wait, wait, wait
  • Field Details

    • NONE

      public static final LongPrefix NONE
      Special case, an empty prefix means no prefix at all to leverage the maximum number of keys: 2^64.
    • DEFAULT

      public static final LongPrefix DEFAULT
      This two-bits prefix '00' (2^62 keys possible) is a convenient default as it still spans a large keyspace, but eliminates the negative values when represented as signed long and it reserves 3 subspaces (e.g. for migration purposes in future). Because the bits on the left are both zero, the keys in the defined space will have variable length. For economical reasons (e.g. String representation) this is recommended, especially if the keys to be prefixed are expected to be/start rather small.
    • POSITIVE

      public static final LongPrefix POSITIVE
      This single-bit prefix '0' (2^63 keys possible) causes the signed long representation to never turn negative. This is recommended if the storage (db-table) also uses signed longs and negative keys would cause confusion or any processing issues.
    • STRAIGHT

      public static final LongPrefix STRAIGHT
      This two-bits prefix '01' (2^62 keys possible) spans a large keyspace, eliminates the negative values when represented as signed long and it reserves 3 subspaces (e.g. for migration purposes in future). The leading 1-bit on the left causes all keys to have the same length, no matter whether displayed as binary String (62 digits), as signed long (19 digits), unsigned integer (19 digits) or hex String (16 digits).
    • POSITIVE_31

      public static final LongPrefix POSITIVE_31
      This prefix sets the first 33 bits '0', so any key in that space of 2^31 keys will be a positive 32-bit integer.
    • STRAIGHT_30

      public static final LongPrefix STRAIGHT_30
      This prefix sets the first 33 bits to '0' followed by a '1' (2^30 keys possible) creating a rather small keyspace with 3 optional subspaces. All keys are positive 32-bit-integer values. Because of the single '1' to the left, keys will all have the same length no matter if represented binary (31 digits), as signed integer (10 digits) or hex String (8 digits).
  • Method Details

    • fromBinaryString

      public static LongPrefix fromBinaryString​(java.lang.String prefixString)
      Returns the LongPrefix instance for the given prefix string, each character ('0' or '1') stands for a bit.
      Parameters:
      prefixString - composed of '0's and '1's, supports leading zeros, length in range [0 .. 63], empty String is valid, NOT NULL.
      Returns:
      prefix instance
      Throws:
      InvalidPrefixException - if the given prefix cannot be used
    • toBinaryString

      public java.lang.String toBinaryString()
      Returns the string representation of this prefix (provided at construction time), a character (0, 1) per bit.
      Returns:
      prefix as a binary string, may have leading zeros
    • getLength

      public int getLength()
      Returns:
      length of the prefix (number of bits starting from the left [0 .. 63])
    • getSizeOfKeyspace

      public java.math.BigInteger getSizeOfKeyspace()
      Returns the size of the keyspace with a maximum value of 2^64 = 18_446_744_073_709_551_616 keys (empty prefix).
      Returns:
      number of unique keys in this sub-keyspace of long defined by this prefix
    • match

      public boolean match​(long key)
      Checks whether the given key is prefixed with this prefix. The empty prefix matches all keys.
      Parameters:
      key - to be tested
      Returns:
      true if the leading bits from the left of the given long value match this prefix
    • applyTo

      public long applyTo​(long key)
      Returns a new long value where the leading bits (length of prefix) have been replaced with the bits of the prefix. Trailing bits will remain unchanged.
      Parameters:
      key - source bits
      Returns:
      value with the leading prefix
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class java.lang.Object
    • equals

      public boolean equals​(java.lang.Object obj)
      Overrides:
      equals in class java.lang.Object
    • compareTo

      public int compareTo​(LongPrefix other)
      Specified by:
      compareTo in interface java.lang.Comparable<LongPrefix>
    • toString

      public java.lang.String toString()
      Returns a description
      Overrides:
      toString in class java.lang.Object