Package eu.bandm.tools.lexic

Class CodePointMap<V>

java.lang.Object
eu.bandm.tools.lexic.CodePointMap<V>
Type Parameters:
V - the value type
All Implemented Interfaces:
FormatClient, Serializable
public class CodePointMap<V> extends Object implements FormatClient, Serializable
Immutable map of Unicode code point keys encoded as int values to arbitrary values.

Since the number of code points is finite but large, this class provides efficient support for total maps where nearly all points are mapped to the same value. In fact, since null is generally allowed as a value, every map is trivially total in this sense. See getDefaultValue().

The implementation builds on the assumption that maps are constructed in a first phase, and used for lookups in a second. The efficiency of the latter is strongly prioritized.

If an object of this class is to be serialized, make sure that all values are serializable. This cannot be enforced statically in a non-obtrusive way.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    (package private) static final int
    BOOT_CAPACITY
    The initial capacity of the backing hash table.
    static final int
    MAX_SIZE
    The total number of Unicode code points.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    allKeysMatch(IntPredicate pred)
    Performs a check for all specifically mapped or unmapped code points.
    boolean
    anyMatch(Predicate<? super V> pred)
    Checks whether any value of this map satisfies a given predicate.
    static <V> CodePointMap<V>
    anyOf(int[] keys, V value)
    Returns a map containing several entries with the same value.
    static <V> CodePointMap<V>
    anyOf(Collection<Integer> keys, V value)
    Returns a map containing several entries with the same value.
    static <V> CodePointMap<V>
    anyOfRange(int first, int last, IntPredicate cond, V value)
    Returns a map containing parts of an interval of entries with the same value.
    static <V> CodePointMap<V>
    anyOfRange(int first, int last, V value)
    Returns a map containing an interval of entries with the same value.
    static <V> CodePointMap<V>
    constant(V value)
    Returns a total map containing one entry for every code point, all with the same value.
    static <V> CodePointMap<V>
    empty()
    Returns a map containing no entries.
    void
    forEach(Consumer<? super V> action)
    Performs an action for each value of this map.
    void
    forEach(ObjIntConsumer<? super V> keyAction, Consumer<? super V> otherwiseAction)
    Performs an action for all entries.
    (package private) void
    forEachKey(IntConsumer action)
    Performs an action for all specifically mapped or unmapped code points.
    <F> F
    format(FormatServer<F> server)
    Returns a human-readable representation of this map.
    <F> F
    format(FormatServer<F> server, Function<? super V,? extends F> onValue)
    Returns a human-readable representation of this map.
    V
    get(int key)
    Returns the value associated with the given key.
    (package private) int
    getCapacity()
    Returns the number of hashtable entries in this map.
    (package private) int
    getCollisions()
    Returns the number of hashtable collisions in this map.
    (package private) V
    getDefaultValue()
    Returns the value assigned to keys for which nothing particular has been specified.
    (package private) void
    hardPatch(Map<?,?> subst)
    Changes the content of this map according to a given substitution.
    static <V, W, X> CodePointMap<X>
    intersect(CodePointMap<V> a, CodePointMap<W> b, BiFunction<? super V,? super W,? extends X> intersector)
    Returns a map containing the intersected entries of two maps, with conflicting values combined.
    <W> CodePointMap<W>
    map(Function<? super V,? extends W> fun)
    Returns a map containing the entries of this map, with all values transformed.
    static <V> CodePointMap<V>
    merge(CodePointMap<V> a, CodePointMap<V> b, BinaryOperator<V> merger)
    Returns a map containing the merged entries of two maps, with conflicting values combined.
    int
    minKey()
    Returns the smallest key that has a non-null entry in this map.
    static <V> CodePointMap<V>
    of(Map<? extends Number,? extends V> map)
    Returns a map containing the given entries.
    static String
    quote(int c)
    Returns a representation of the given code point that works in Java literals.
    CodePointMap<V>
    simplify()
    Returns a map that differs from this map at most by discarding explicit entries that are already implicit.
    static <V> CodePointMap<V>
    singleton(int key, V value)
    Returns a map containing one entry.
    int
    size()
    Returns the number of entries in this map.
    String
    toString()
    Returns a human-readable representation of this map.
    CodePointMap<V>
    totalize(V otherwise)
    Returns a map that differs from this map by having default entries for all keys previously mapped to null.
    CodePointMap<V>
    translate(Multimap<Integer,Integer> trans, BinaryOperator<V> merge)
    Returns a map where all keys of this map have been translated according to a relational image.
    CodePointMap<V>
    with(int key, V value)
    Returns a map containing the entries of this map with one value added or overwritten.
    CodePointMap<V>
    with(int key, V value, @Opt BinaryOperator<V> merge)
    Returns a map containing the entries of this map with one value added or merged.
    CodePointMap<V>
    without(int key)
    Returns a map containing the entries of this map with one value removed.
    CodePointMap<V>
    without(int... keys)
    Returns a map containing the entries of this map with some values removed.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • BOOT_CAPACITY

      static final int BOOT_CAPACITY
      The initial capacity of the backing hash table.
      See Also:

    • MAX_SIZE

      public static final int MAX_SIZE
      The total number of Unicode code points.
      See Also:

  • Method Details

    • getDefaultValue

      V getDefaultValue()
      Returns the value assigned to keys for which nothing particular has been specified.
      Returns:
      the value assigned to keys for which nothing particular has been specified; possibly null

    • empty

      public static <V> CodePointMap<V> empty()
      Returns a map containing no entries.
      Type Parameters:
      V - the value type
      Returns:
      a map containing no entries

    • singleton

      public static <V> CodePointMap<V> singleton(int key, V value)
      Returns a map containing one entry.
      Type Parameters:
      V - the value type
      Parameters:
      key - the code point key
      value - the associated value, possibly null
      Returns:
      a map containing the given entry
      Throws:
      IllegalArgumentException - if the given key is not a valid code point
      See Also:

    • getCollisions

      int getCollisions()
      Returns the number of hashtable collisions in this map. This method is for efficiency profiling. The lower the number, the more efficient the table layout.
      Returns:
      the number of hashtable collisions in this map

    • getCapacity

      int getCapacity()
      Returns the number of hashtable entries in this map. This method is for efficiency profiling. The lower the number, the more efficient the table layout.
      Returns:
      the number of hashtable collision in this map

    • anyOf

      public static <V> CodePointMap<V> anyOf(int[] keys, V value)
      Returns a map containing several entries with the same value.

      Repeating the same code point in the array of keys has no further effect.

      Type Parameters:
      V - the value type
      Parameters:
      keys - an array of code point keys
      value - the value to associate with each of the keys
      Returns:
      a map containing entries for all given keys with the given value

    • anyOf

      public static <V> CodePointMap<V> anyOf(Collection<Integer> keys, V value)
      Returns a map containing several entries with the same value.

      Repeating the same code point in the collection of keys has no further effect.

      Type Parameters:
      V - the value type
      Parameters:
      keys - an array of code point keys
      value - the value to associate with each of the keys
      Returns:
      a map containing entries for all given keys with the given value

    • anyOfRange

      public static <V> CodePointMap<V> anyOfRange(int first, int last, V value)
      Returns a map containing an interval of entries with the same value.
      Type Parameters:
      V - the value type
      Parameters:
      first - the first code point
      last - the last code point
      value - the value to associate with each of the keys
      Returns:
      a map containing entries for all keys greater or equal to first and less or equal to last

    • anyOfRange

      public static <V> CodePointMap<V> anyOfRange(int first, int last, IntPredicate cond, V value)
      Returns a map containing parts of an interval of entries with the same value.
      Type Parameters:
      V - the value type
      Parameters:
      first - the first code point
      last - the last code point
      cond - an additional predicate that code points to be mapped must satisfy
      value - the value to associate with each of the keys
      Returns:
      a map containing entries for all keys greater or equal to first and less or equal to last, and for which cond returns true

    • constant

      public static <V> CodePointMap<V> constant(@Opt V value)
      Returns a total map containing one entry for every code point, all with the same value.
      Type Parameters:
      V - the value type
      Parameters:
      value - the value to associate with all code point keys
      Returns:
      a total map of all code point keys to the given value

    • of

      public static <V> CodePointMap<V> of(Map<? extends Number,? extends V> map)
      Returns a map containing the given entries.

      All map entries are iterated over when this method is called. The method Number.intValue() is used to convert keys to code points. Changes to the given map that occur after this method has returned will have no side-effect on the result.

      Type Parameters:
      V - the value type
      Parameters:
      map - the entries
      Returns:
      a map containing the given entries
      Throws:
      IllegalArgumentException - if any converted key is not a valid code point
      See Also:

    • get

      @Opt public V get(int key)
      Returns the value associated with the given key.
      Parameters:
      key - the code point key
      Returns:
      the value associated with the given key, or null if there is none

    • with

      public CodePointMap<V> with(int key, V value)
      Returns a map containing the entries of this map with one value added or overwritten.
      Parameters:
      key - the code point key to add or overwrite
      value - the value to associate with the given key
      Returns:
      a map containing the entries of this map with the given entry added or overwritten
      Throws:
      IllegalArgumentException - if the given key is not a valid code point
      See Also:

    • with

      public CodePointMap<V> with(int key, V value, @Opt @Opt BinaryOperator<V> merge)
      Returns a map containing the entries of this map with one value added or merged.

      If there is no previous entry with the same key, then the value is just added. If there is one, then the old and new value are merged using the given operator. If the merge operator is null, then the new value overwrites the old one.

      Parameters:
      key - the code point key to add or overwrite
      value - the value to associate with the given key
      merge - an operator for merging the old and the new value, or null for overwriting
      Returns:
      a map containing the entries of this map with the given entry added or merged
      Throws:
      IllegalArgumentException - if the given key is not a valid code point
      See Also:

    • without

      public CodePointMap<V> without(int key)
      Returns a map containing the entries of this map with one value removed.

      Note that this operation is intended for use with constant(V) to define maps that contain most, but not all keys. No attempt is made to shrink or simplify the internal data; hence it is not guaranteed to strictly undo a preceding with(int,Object).

      Parameters:
      key - the code point key to remove
      Returns:
      a map containing the entries of this map with the given entry removed

    • without

      public CodePointMap<V> without(int... keys)
      Returns a map containing the entries of this map with some values removed.

      Note that this operation is intended for use with constant(V) to define maps that contain most, but not all keys. No attempt is made to shrink or simplify the internal data; hence it is not guaranteed to strictly undo a preceding with(int,Object).

      Parameters:
      keys - the code point keys to remove
      Returns:
      a map containing the entries of this map with the given entries removed

    • map

      public <W> CodePointMap<W> map(Function<? super V,? extends W> fun)
      Returns a map containing the entries of this map, with all values transformed.
      Type Parameters:
      W - the target value type
      Parameters:
      fun - the function for transforming all values
      Returns:
      a map containing the entries of this map, with all values transformed with the given function

    • merge

      public static <V> CodePointMap<V> merge(CodePointMap<V> a, CodePointMap<V> b, BinaryOperator<V> merger)
      Returns a map containing the merged entries of two maps, with conflicting values combined.
      Type Parameters:
      V - the value type of the maps
      Parameters:
      a - the first map
      b - the second map
      merger - the operation for combining conflicting values
      Returns:
      a map containing the merged entries of two maps, with conflicting values combined

    • intersect

      public static <V, W, X> CodePointMap<X> intersect(CodePointMap<V> a, CodePointMap<W> b, BiFunction<? super V,? super W,? extends X> intersector)
      Returns a map containing the intersected entries of two maps, with conflicting values combined.
      Type Parameters:
      V - the value type of the first map
      W - the value type of the second map
      X - the value type of the intersection map
      Parameters:
      a - the first map
      b - the second map
      intersector - the operation for combining conflicting values
      Returns:
      a map containing the intersected entries of two maps, with conflicting values combined

    • forEach

      public void forEach(Consumer<? super V> action)
      Performs an action for each value of this map.

      If a value occurs multiple times for different keys, multiple actions may be performed. It is this strongly recommended that the given action be idempotent, such as adding the value to a set.

      Parameters:
      action - the action to perform

    • forEach

      public void forEach(ObjIntConsumer<? super V> keyAction, Consumer<? super V> otherwiseAction)
      Performs an action for all entries.
      Parameters:
      keyAction - the action to perform for explicitly set keys
      otherwiseAction - the action to perform for other keys

    • toString

      public String toString()
      Returns a human-readable representation of this map.
      Overrides:
      toString in class Object

    • quote

      public static String quote(int c)
      Returns a representation of the given code point that works in Java literals.

      In particular, standard backslash escapes apply.

      Parameters:
      c - the code point to represent
      Returns:
      a representation of the given code point that works in Java literals

    • format

      public <F> F format(FormatServer<F> server)
      Returns a human-readable representation of this map.
      Specified by:
      format in interface FormatClient
      Type Parameters:
      F - the type of format objects to produce
      Parameters:
      server - a factory object that can produce format objects
      Returns:
      a format object produced by the server

    • format

      public <F> F format(FormatServer<F> server, Function<? super V,? extends F> onValue)
      Returns a human-readable representation of this map.
      Type Parameters:
      F - the type of format objects to produce
      Parameters:
      server - a factory object that can produce format objects
      onValue - the operation for computing representations of values
      Returns:
      a human-readable representation of this map

    • hardPatch

      void hardPatch(Map<?,?> subst)
      Changes the content of this map according to a given substitution.

      The type of the substituted values is not checked either at compile time or at execution time. Latent causes for ClassCastException may arise if this method is used carelessly.

      Parameters:
      subst - the substitution to apply; values not present as keys are left unchanged.

    • totalize

      public CodePointMap<V> totalize(V otherwise)
      Returns a map that differs from this map by having default entries for all keys previously mapped to null.

      Note that otherwise(null) makes an equivalent copy.

      Parameters:
      otherwise - the default value to replace null
      Returns:
      a map that differs from this map by having entries for all keys previously mapped to null

    • anyMatch

      public boolean anyMatch(Predicate<? super V> pred)
      Checks whether any value of this map satisfies a given predicate.
      Parameters:
      pred - the predicate to satisfy
      Returns:
      true if this map contains a value that satisfies the given predicate; false otherwise

    • simplify

      public CodePointMap<V> simplify()
      Returns a map that differs from this map at most by discarding explicit entries that are already implicit. The resulting map may require less, but not more, space.

      This method can also be used to clean up redundant null-valued entries.

      The resulting map will be undistinguishable from this map in terms of the observable map-like behavior, i.e., results of the method get(int).

      Returns:
      a map that differs from this map at most by discarding explicit entries that are already implicit; can be this if no clean-up is required

    • forEachKey

      void forEachKey(IntConsumer action)
      Performs an action for all specifically mapped or unmapped code points.

      This includes all code points that have been assigned a non-null value explicitly using of(java.util.Map<? extends java.lang.Number, ? extends V>), anyOf(int[], V) or with(int, V), as well as code points that have been exceptionally assigned a null value, but not code points that have been assigned a value implicitly using constant(V) or totalize(V).

      Parameters:
      action - the action to perform

    • allKeysMatch

      public boolean allKeysMatch(IntPredicate pred)
      Performs a check for all specifically mapped or unmapped code points.

      This includes all code points that have been assigned a non-null value explicitly using of(java.util.Map<? extends java.lang.Number, ? extends V>), anyOf(int[], V) or with(int, V), as well as code points that have been exceptionally assigned a null value, but not code points that have been assigned a value implicitly using constant(V) or totalize(V).

      Checks may be performed only until a counterexample is found. The given predicate should not rely on side effects or a precise number of invocations.

      Parameters:
      pred - the check to perform
      Returns:
      true if the check has returned true for each relevant key; false if a counterexample has been found

    • size

      public int size()
      Returns the number of entries in this map.

      Both positive (non-null) and negative (null) particular entries are counted, as well as a non-null default entry.

      Returns:
      the number of entries

    • minKey

      public int minKey()
      Returns the smallest key that has a non-null entry in this map.
      Returns:
      the smallest key that has a non-null entry in this map, or Integer.MAX_VALUE if there is none

    • translate

      public CodePointMap<V> translate(Multimap<Integer,Integer> trans, BinaryOperator<V> merge)
      Returns a map where all keys of this map have been translated according to a relational image.

      For each key k with associated value v in this map, the resulting map attaches v to every key t such that trans.contains(k, t) returns true. Multiple colliding values for the same key are combined using the operator merge, in unspecified order; it is therefore recommended that merge be commutative.

      Parameters:
      trans - the translating relation
      merge - the operation for combining colliding values
      Returns:
      a map where all keys of this map have been translated according to trans
      Throws:
      NullPointerException - if trans or merge is null
      Since:
      1.1